Struct

GLibString

Description [src]

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.).