mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-10-22 05:11:06 +02:00
355 lines
8.7 KiB
Plaintext
355 lines
8.7 KiB
Plaintext
<!-- ##### 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>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### 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.
|
|
<!-- # Unused Parameters # -->
|
|
@gstr:
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
|