Reference counted strings

Reference counted strings — Strings with reference counted memory management

Functions

char * g_ref_string_new ()
char * g_ref_string_new_intern ()
char * g_ref_string_new_len ()
char * g_ref_string_acquire ()
void g_ref_string_release ()
gsize g_ref_string_length ()

Types and Values

typedef GRefString

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
PersonDetails *
person_details_from_data (const char *data)
{
  // Use g_autoptr() to simplify error cases
  g_autoptr(GRefString) full_name = NULL;
  g_autoptr(GRefString) address =  NULL;
  g_autoptr(GRefString) city = NULL;
  g_autoptr(GRefString) state = NULL;
  g_autoptr(GRefString) zip_code = NULL;

  // parse_person_details() is defined elsewhere; returns refcounted strings
  if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
    return NULL;

  if (!validate_zip_code (zip_code))
    return NULL;

  // add_address_to_cache() and add_full_name_to_cache() are defined
  // elsewhere; they add strings to various caches, using refcounted
  // strings to avoid copying data over and over again
  add_address_to_cache (address, city, state, zip_code);
  add_full_name_to_cache (full_name);

  // person_details_new() is defined elsewhere; it takes a reference
  // on each string
  PersonDetails *res = person_details_new (full_name,
                                           address,
                                           city,
                                           state,
                                           zip_code);

  return res;
}

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.

Parameters

str

a NUL-terminated string.

[not nullable]

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.

Parameters

str

a NUL-terminated string.

[not nullable]

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.

Parameters

str

a string.

[not nullable]

len

length of str to use, or -1 if str is nul-terminated

  

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.

Parameters

str

a reference counted 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.

Parameters

str

a reference counted string

  

Since: 2.58

g_ref_string_length ()

gsize
g_ref_string_length (char *str);

Retrieves the length of str .

Parameters

str

a reference counted string

  

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

Generated by GTK-Doc V1.33.1