Reference counted strings: GLib Reference Manual

## 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