### Struct

# GLib String

#### Description

    struct GString {
      gchar* str;
      gsize len;
      gsize allocated_len;
    }

A `GString` is an object that handles the memory management of a C string.

The emphasis of `GString` is on text, typically UTF-8. Crucially, the “str” member of a `GString` is guaranteed to have a trailing nul character, and it is therefore always safe to call functions such as `strchr()` or `strdup()` on it.

However, a `GString` can also hold arbitrary binary data, because it has a “len” member, which includes any possible embedded nul characters in the data. Conceptually then, `GString` is like a `GByteArray` with the addition of many convenience methods for text, and a guaranteed nul terminator.

###### Structure members

`str`

  Points to the character data. It may move as text is added. The `str` field is null-terminated and so can be used as an ordinary C string.

`len`

  Contains the length of the string, not including the terminating nul byte.

`allocated_len`

  The number of bytes that can be stored in the string before it needs to be reallocated. May be larger than `len`.

#### Constructors

###### g_string_new

Creates a new `GString`, initialized with the given string.

###### g_string_new_len

Creates a new `GString` with `len` bytes of the `init` buffer. Because a length is provided, `init` need not be nul-terminated, and can contain embedded nul bytes.

###### g_string_new_take

Creates a new `GString`, initialized with the given string.

since: 2.78

###### g_string_sized_new

Creates a new `GString`, with enough space for `dfl_size` bytes. This is useful if you are going to add a lot of text to the string and don’t want it to be reallocated too often.

#### Instance methods

###### g_string_append

Adds a string onto the end of a `GString`, expanding it if necessary.

###### g_string_append_c

Adds a byte onto the end of a `GString`, expanding it if necessary.

###### g_string_append_len

Appends `len` bytes of `val` to `string`.

###### g_string_append_printf

Appends a formatted string onto the end of a `GString`. This function is similar to `g_string_printf()` except that the text is appended to the `GString`.

###### g_string_append_unichar

Converts a Unicode character into UTF-8, and appends it to the string.

###### g_string_append_uri_escaped

Appends `unescaped` to `string`, escaping any characters that are reserved in URIs using URI-style escape sequences.

since: 2.16

###### g_string_append_vprintf

Appends a formatted string onto the end of a `GString`. This function is similar to `g_string_append_printf()` except that the arguments to the format string are passed as a va_list.

since: 2.14

###### g_string_ascii_down

Converts all uppercase ASCII letters to lowercase ASCII letters.

###### g_string_ascii_up

Converts all lowercase ASCII letters to uppercase ASCII letters.

###### g_string_assign

Copies the bytes from a string into a `GString`, destroying any previous contents. It is rather like the standard `strcpy()` function, except that you do not have to worry about having enough space to copy the string.

###### g_string_down

Converts a `GString` to lowercase.

deprecated: 2.2

###### g_string_equal

Compares two strings for equality, returning `TRUE` if they are equal. For use with `GHashTable`.

###### g_string_erase

Removes `len` bytes from a `GString`, starting at position `pos`. The rest of the `GString` is shifted down to fill the gap.

###### g_string_free

Frees the memory allocated for the `GString`. If `free_segment` is `TRUE` it also frees the character data. If it’s `FALSE`, the caller gains ownership of the buffer and must free it after use with g_free().

###### g_string_free_and_steal

Frees the memory allocated for the `GString`.

since: 2.76

###### g_string_free_to_bytes

Transfers ownership of the contents of `string` to a newly allocated `GBytes`. The `GString` structure itself is deallocated, and it is therefore invalid to use `string` after invoking this function.

since: 2.34

###### g_string_hash

Creates a hash code for `str`; for use with `GHashTable`.

###### g_string_insert

Inserts a copy of a string into a `GString`, expanding it if necessary.

###### g_string_insert_c

Inserts a byte into a `GString`, expanding it if necessary.

###### g_string_insert_len

Inserts `len` bytes of `val` into `string` at `pos`.

###### g_string_insert_unichar

Converts a Unicode character into UTF-8, and insert it into the string at the given position.

###### g_string_overwrite

Overwrites part of a string, lengthening it if necessary.

since: 2.14

###### g_string_overwrite_len

Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls.

since: 2.14

###### g_string_prepend

Adds a string on to the start of a `GString`, expanding it if necessary.

###### g_string_prepend_c

Adds a byte onto the start of a `GString`, expanding it if necessary.

###### g_string_prepend_len

Prepends `len` bytes of `val` to `string`.

###### g_string_prepend_unichar

Converts a Unicode character into UTF-8, and prepends it to the string.

###### g_string_printf

Writes a formatted string into a `GString`. This is similar to the standard `sprintf()` function, except that the `GString` buffer automatically expands to contain the results. The previous contents of the `GString` are destroyed.

###### g_string_replace

Replaces the string `find` with the string `replace` in a `GString` up to `limit` times. If the number of instances of `find` in the `GString` is less than `limit`, all instances are replaced. If `limit` is `0`, all instances of `find` are replaced.

since: 2.68

###### g_string_set_size

Sets the length of a `GString`. If the length is less than the current length, the string will be truncated. If the length is greater than the current length, the contents of the newly added area are undefined. (However, as always, string->str[string->len] will be a nul byte.).

###### g_string_truncate

Cuts off the end of the GString, leaving the first `len` bytes.

###### g_string_up

Converts a `GString` to uppercase.

deprecated: 2.2

###### g_string_vprintf

Writes a formatted string into a `GString`. This function is similar to `g_string_printf()` except that the arguments to the format string are passed as a va_list.

since: 2.14