<!-- ##### SECTION Title ##### --> Strings <!-- ##### SECTION Short_Description ##### --> text buffers which grow automatically as text is added. <!-- ##### SECTION Long_Description ##### --> <para> A #GString is similar to a standard C string, except that it grows automatically as text is appended or inserted. Also, it stores the length of the string, so can be used for binary data with embedded nul bytes. </para> <!-- ##### SECTION See_Also ##### --> <para> </para> <!-- ##### STRUCT GString ##### --> <para> The #GString struct contains the public fields of a #GString. The <structfield>str</structfield> field points to the character data. It may move as text is added. The <structfield>len</structfield> field contains the length of the string, not including the terminating nul character. </para> <para> The <structfield>str</structfield> field is nul-terminated and so can be used as an ordinary C string. But it may be moved when text is appended or inserted into the string. </para> @str: @len: @allocated_len: <!-- ##### FUNCTION g_string_new ##### --> <para> Creates a new #GString, initialized with the given string. </para> @init: the initial text to copy into the string. @Returns: the new #GString. <!-- ##### FUNCTION g_string_new_len ##### --> <para> 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. </para> @init: initial contents of string. @len: length of @init to use. @Returns: a new #GString. <!-- ##### FUNCTION g_string_sized_new ##### --> <para> Creates a new #GString, with enough space for @dfl_size characters. 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. </para> @dfl_size: the default size of the space allocated to hold the string. @Returns: the new #GString. <!-- ##### FUNCTION g_string_assign ##### --> <para> Copies the characters from a string into a #GString, destroying any previous contents. It is rather like the standard <function>strcpy()</function> function, except that you do not have to worry about having enough space to copy the string. </para> @string: the destination #GString. Its current contents are destroyed. @rval: @Returns: the destination #GString. <!-- # Unused Parameters # --> @val: the string to copy into @string. <!-- ##### MACRO g_string_sprintf ##### --> <para> Writes a formatted string into a #GString. This is similar to the standard <function>sprintf()</function> function, except that the #GString buffer automatically expands to contain the results. The previous contents of the #GString are destroyed. </para> @Deprecated: This function has been renamed to g_string_printf(). <!-- # Unused Parameters # --> @string: a #GString. @format: the string format. See the <function>sprintf()</function> documentation. @Varargs: the parameters to insert into the format string. <!-- ##### MACRO g_string_sprintfa ##### --> <para> Appends a formatted string onto the end of a #GString. This function is is similar to g_string_sprintf() except that the text is appended to the #GString. </para> @Deprecated: This function has been renamed to g_string_append_printf(). <!-- # Unused Parameters # --> @string: a #GString. @format: the string format. See the <function>sprintf()</function> documentation. @Varargs: the parameters to insert into the format string. <!-- ##### FUNCTION g_string_printf ##### --> <para> Writes a formatted string into a #GString. This is similar to the standard <function>sprintf()</function> function, except that the #GString buffer automatically expands to contain the results. The previous contents of the #GString are destroyed. </para> @string: a #GString. @format: the string format. See the <function>printf()</function> documentation. @Varargs: the parameters to insert into the format string. <!-- ##### FUNCTION g_string_append_printf ##### --> <para> Appends a formatted string onto the end of a #GString. This function is is similar to g_string_printf() except that the text is appended to the #GString. </para> @string: a #GString. @format: the string format. See the <function>printf()</function> documentation. @Varargs: the parameters to insert into the format string. <!-- ##### FUNCTION g_string_append ##### --> <para> Adds a string onto the end of a #GString, expanding it if necessary. </para> @string: a #GString. @val: the string to append onto the end of the #GString. @Returns: the #GString. <!-- ##### FUNCTION g_string_append_c ##### --> <para> Adds a character onto the end of a #GString, expanding it if necessary. </para> @string: a #GString. @c: the character to append onto the end of the #GString. @Returns: the #GString. <!-- ##### FUNCTION g_string_append_unichar ##### --> <para> </para> @string: @wc: @Returns: <!-- ##### FUNCTION g_string_append_len ##### --> <para> Appends @len bytes of @val to @string. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. </para> @string: a #GString. @val: bytes to append. @len: number of bytes of @val to use. @Returns: the #GString. <!-- ##### FUNCTION g_string_prepend ##### --> <para> Adds a string on to the start of a #GString, expanding it if necessary. </para> @string: a #GString. @val: the string to prepend on the start of the #GString. @Returns: the #GString. <!-- ##### FUNCTION g_string_prepend_c ##### --> <para> Adds a character onto the start of a #GString, expanding it if necessary. </para> @string: a #GString. @c: the character to prepend on the start of the #GString. @Returns: the #GString. <!-- ##### FUNCTION g_string_prepend_unichar ##### --> <para> </para> @string: @wc: @Returns: <!-- ##### FUNCTION g_string_prepend_len ##### --> <para> Prepends @len bytes of @val to @string. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. </para> @string: a #GString. @val: bytes to prepend. @len: number of bytes in @val to prepend. @Returns: the #GString passed in. <!-- ##### FUNCTION g_string_insert ##### --> <para> Inserts a copy of a string into a #GString, expanding it if necessary. </para> @string: a #GString. @pos: the position to insert the copy of the string. @val: the string to insert. @Returns: the #GString. <!-- ##### FUNCTION g_string_insert_c ##### --> <para> Inserts a character into a #GString, expanding it if necessary. </para> @string: a #GString. @pos: the position to insert the character. @c: the character to insert. @Returns: the #GString. <!-- ##### FUNCTION g_string_insert_unichar ##### --> <para> </para> @string: @pos: @wc: @Returns: <!-- ##### FUNCTION g_string_insert_len ##### --> <para> Inserts @len bytes of @val into @string at @pos. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. If @pos is -1, bytes are inserted at the end of the string. </para> @string: a #GString. @pos: position in @string where insertion should happen, or -1 for at the end. @val: bytes to insert. @len: number of bytes of @val to insert. @Returns: the #GString. <!-- ##### FUNCTION g_string_erase ##### --> <para> Removes @len characters from a #GString, starting at position @pos. The rest of the #GString is shifted down to fill the gap. </para> @string: a #GString. @pos: the position of the characters to remove. @len: the number of characters to remove, or -1 to remove all following characters. @Returns: the #GString. <!-- ##### FUNCTION g_string_truncate ##### --> <para> Cuts off the end of the GString, leaving the first @len characters. </para> @string: a #GString. @len: the new size of the #GString. @Returns: the #GString. <!-- ##### FUNCTION g_string_set_size ##### --> <para> </para> @string: @len: @Returns: <!-- ##### FUNCTION g_string_free ##### --> <para> Frees the memory allocated for the #GString. If @free_segment is %TRUE it also frees the character data. </para> @string: a #GString. @free_segment: if %TRUE the actual character data is freed as well. @Returns: the character data of @string (i.e. %NULL if @free_segment is %TRUE) <!-- ##### FUNCTION g_string_up ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_string_down ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_string_hash ##### --> <para> Creates a hash code for @str; for use with #GHashTable. </para> @str: a string to hash. @Returns: hash code for @str. <!-- ##### FUNCTION g_string_equal ##### --> <para> Compares two strings for equality, returning %TRUE if they are equal. For use with #GHashTable. </para> @v: a #GString. @v2: another #GString. @Returns: %TRUE if they strings are the same length and contain the same bytes.