Reference counted strings
Reference counted strings — Strings with reference counted memory management
|
|
Includes
#include <glib.h>
#include <glib/gi18n.h>
Description
Reference counted strings are normal C strings that have been augmented
with a reference counter to manage their resources. You allocate a new
reference counted string and acquire and release references as needed,
instead of copying the string among callers; when the last reference on
the string is released, the resources allocated for it are freed.
Typically, reference counted strings can be used when parsing data from
files and storing them into data structures that are passed to various
callers:
In the example above, we have multiple functions taking the same strings
for different uses; with typical C strings, we'd have to copy the strings
every time the life time rules of the data differ from the life time of
the string parsed from the original buffer. With reference counted strings,
each caller can take a reference on the data, and keep it as long as it
needs to own the string.
Reference counted strings can also be "interned" inside a global table
owned by GLib; while an interned string has at least a reference, creating
a new interned reference counted string with the same contents will return
a reference to the existing string instead of creating a new reference
counted string instance. Once the string loses its last reference, it will
be automatically removed from the global interned strings table.
Functions
g_ref_string_new ()
char *
g_ref_string_new (const char *str);
Creates a new reference counted string and copies the contents of str
into it.
Returns
the newly created reference counted string.
[transfer full][not nullable]
Since: 2.58
g_ref_string_new_intern ()
char *
g_ref_string_new_intern (const char *str);
Creates a new reference counted string and copies the content of str
into it.
If you call this function multiple times with the same str
, or with
the same contents of str
, it will return a new reference, instead of
creating a new string.
Returns
the newly created reference
counted string, or a new reference to an existing string.
[transfer full][not nullable]
Since: 2.58
g_ref_string_new_len ()
char *
g_ref_string_new_len (const char *str,
gssize len);
Creates a new reference counted string and copies the contents of str
into it, up to len
bytes.
Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that str
has at least len
addressable bytes.
Returns
the newly created reference counted string.
[transfer full][not nullable]
Since: 2.58
g_ref_string_acquire ()
char *
g_ref_string_acquire (char *str);
Acquires a reference on a string.
Returns
the given string, with its reference count increased
Since: 2.58
g_ref_string_release ()
void
g_ref_string_release (char *str);
Releases a reference on a string; if it was the last reference, the
resources allocated by the string are freed as well.
Since: 2.58
g_ref_string_length ()
gsize
g_ref_string_length (char *str);
Retrieves the length of str
.
Returns
the length of the given string, in bytes
Since: 2.58
Types and Values
GRefString
typedef char GRefString;
A typedef for a reference-counted string. A pointer to a GRefString can be
treated like a standard char* array by all code, but can additionally have
g_ref_string_*() methods called on it. g_ref_string_*() methods cannot be
called on char* arrays not allocated using g_ref_string_new().
If using GRefString with autocleanups, g_autoptr() must be used rather than
g_autofree(), so that the reference counting metadata is also freed.
Since: 2.58