X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=docs%2Freference%2Fglib%2Ftmpl%2Fstrings.sgml;h=8a35eeb2ec5b2918754c72cd5047d8125a3f88cf;hb=9090c67afc1aea46e2bc2ccd18574a52f9d52bec;hp=c9167c23e1efd03e03d0e69984e24db6536879a3;hpb=19f04a9024d48c9524604bc8097c2527b1675b98;p=platform%2Fupstream%2Fglib.git

diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml
index c9167c2..8a35eeb 100644
--- a/docs/reference/glib/tmpl/strings.sgml
+++ b/docs/reference/glib/tmpl/strings.sgml
@@ -2,185 +2,295 @@
 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 byte.
+</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: 
-@Returns: 
+@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 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.
 </para>
 
-@dfl_size: 
-@Returns: 
+@dfl_size: the default size of the space allocated to hold the string.
+@Returns: the new #GString.
 
 
 <!-- ##### FUNCTION g_string_assign ##### -->
 <para>
-
+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.
 </para>
 
-@string: 
-@rval: 
-@Returns: 
+@string: the destination #GString. Its current contents are destroyed.
+@rval: the string to copy into @string
+@Returns: the destination #GString.
+<!-- # Unused Parameters # -->
+@val: the string to copy into @string.
 
 
-<!-- ##### FUNCTION g_string_sprintf ##### -->
+<!-- ##### MACRO g_string_sprintf ##### -->
 <para>
+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. 
+</para>
+
+@Deprecated: This function has been renamed to g_string_printf().
+<!-- # Unused Parameters # -->
+@string: a #GString.
+@format: the string format. See the sprintf() 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>
 
-@string: 
-@format: 
-@Varargs: 
+@Deprecated: This function has been renamed to g_string_append_printf().
+<!-- # Unused Parameters # -->
+@string: a #GString.
+@format: the string format. See the sprintf() documentation.
+@Varargs: the parameters to insert into the format string.
 
 
-<!-- ##### FUNCTION g_string_sprintfa ##### -->
+<!-- ##### FUNCTION g_string_printf ##### -->
 <para>
+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.
+</para>
+
+@string: a #GString.
+@format: the string format. See the printf() 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: 
-@format: 
-@Varargs: 
+@string: a #GString.
+@format: the string format. See the printf() 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: 
-@val: 
-@Returns: 
+@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 byte onto the end of a #GString, expanding it if necessary.
+</para>
+
+@string: a #GString.
+@c: the byte to append onto the end of the #GString.
+@Returns: the #GString.
+
+
+<!-- ##### FUNCTION g_string_append_unichar ##### -->
+<para>
 
 </para>
 
 @string: 
-@c: 
+@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: 
-@val: 
-@len: 
-@Returns: 
+@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: 
-@val: 
-@Returns: 
+@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 byte onto the start of a #GString, expanding it if necessary.
+</para>
+
+@string: a #GString.
+@c: the byte to prepend on the start of the #GString.
+@Returns: the #GString.
+
+
+<!-- ##### FUNCTION g_string_prepend_unichar ##### -->
+<para>
 
 </para>
 
 @string: 
-@c: 
+@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: 
-@val: 
-@len: 
-@Returns: 
+@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: 
-@pos: 
-@val: 
-@Returns: 
+@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 byte into a #GString, expanding it if necessary.
+</para>
+
+@string: a #GString.
+@pos: the position to insert the byte.
+@c: the byte to insert.
+@Returns: the #GString.
+
+
+<!-- ##### FUNCTION g_string_insert_unichar ##### -->
+<para>
 
 </para>
 
 @string: 
 @pos: 
-@c: 
+@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: 
-@pos: 
-@val: 
-@len: 
-@Returns: 
+@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 bytes from a #GString, starting at position @pos.
+The rest of the #GString is shifted down to fill the gap.
 </para>
 
-@string: 
-@pos: 
-@len: 
-@Returns: 
+@string: a #GString.
+@pos: the position of the content to remove.
+@len: the number of bytes to remove, or -1 to remove all
+      following bytes.
+@Returns: the #GString.
 
 
 <!-- ##### FUNCTION g_string_truncate ##### -->
 <para>
+Cuts off the end of the GString, leaving the first @len bytes.
+</para>
+
+@string: a #GString.
+@len: the new size of the #GString.
+@Returns: the #GString.
+
+
+<!-- ##### FUNCTION g_string_set_size ##### -->
+<para>
 
 </para>
 
@@ -191,17 +301,17 @@ Strings
 
 <!-- ##### 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: 
-@free_segment: 
-@Returns: 
+@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: 
@@ -210,7 +320,6 @@ Strings
 
 <!-- ##### FUNCTION g_string_down ##### -->
 <para>
-
 </para>
 
 @string: 
@@ -219,20 +328,21 @@ Strings
 
 <!-- ##### FUNCTION g_string_hash ##### -->
 <para>
-
+Creates a hash code for @str; for use with #GHashTable.
 </para>
 
-@str: 
-@Returns: 
+@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: 
-@v2: 
-@Returns: 
+@v: a #GString.
+@v2: another #GString.
+@Returns: %TRUE if they strings are the same length and contain the same bytes.