+2001-09-27 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml,
+ glib/tmpl/completion.sgml, glib/tmpl/strings.sgml: Documented
+ some functions, markup fixes.
+ * glib/tmpl/patterns.sgml: New file.
+ * glib/glib-docs.sgml: Add entity for patterns.sgml.
+
2001-09-26 Matthias Clasen <matthiasc@poet.de>
* glib/glib-sections.txt: Add g_mem_is_system_malloc.
<!entity glib-Error-Reporting SYSTEM "sgml/error_reporting.sgml">
<!entity glib-Warnings-and-Assertions SYSTEM "sgml/warnings.sgml">
<!entity glib-Message-Logging SYSTEM "sgml/messages.sgml">
+<!entity glib-Pattern-Matching SYSTEM "sgml/patterns.sgml">
<!entity glib-Timers SYSTEM "sgml/timers.sgml">
<!entity glib-String-Utility-Functions SYSTEM "sgml/string_utils.sgml">
<!entity glib-Character-Set-Conversion SYSTEM "sgml/conversions.sgml">
&glib-Spawn;
&glib-Fileutils;
&glib-Shell;
+ &glib-Pattern-Matching;
&glib-Markup;
&glib-Windows-Compatability-Functions;
</chapter>
or pointers to arbitrary data structures. If data structures are used
you must provide a #GCompletionFunc in g_completion_new(),
which retrieves the item's string from the data structure.
+You can change the way in which strings are compared by setting
+a different #GCompletionStrncmpFunc in g_completion_set_compare().
</para>
<!-- ##### SECTION See_Also ##### -->
</para>
@func: the function to be called to return the string representing an item
-in the #GCompletion, or NULL if strings are going to be used as the
+in the #GCompletion, or %NULL if strings are going to be used as the
#GCompletion items.
@Returns: the new #GCompletion.
@cmp: the #GCompletion.
@prefix: the prefix string, typically typed by the user, which is compared
with each of the items.
-@new_prefix: if non-NULL, returns the longest prefix which is common to all
-items that matched @prefix, or NULL if no items matched @prefix.
+@new_prefix: if non-%NULL, returns the longest prefix which is common to all
+items that matched @prefix, or %NULL if no items matched @prefix.
This string should be freed when no longer needed.
@Returns: the list of items whose strings begin with @prefix. This should
not be changed.
<!-- ##### FUNCTION g_completion_set_compare ##### -->
<para>
-
+Sets the function to use for string comparisons. The default
+string comparison function is <function>strncmp()</function>.
</para>
-@cmp:
-@strncmp_func:
+@cmp: a #GCompletion.
+@strncmp_func: the string comparison function.
<!-- ##### USER_FUNCTION GCompletionStrncmpFunc ##### -->
<para>
-
+Specifies the type of the function passed to g_completion_set_compare().
+This is used when you use strings as #GCompletion items.
</para>
-@s1:
-@s2:
-@n:
-@Returns:
-
+@s1: string to compare with @s2.
+@s2: string to compare with @s1.
+@n: maximal number of bytes to compare.
+@Returns: an integer less than, equal to, or greater than zero if the
+first @n bytes of @s1 is found, respectively, to be less than, to match,
+or to be greater than the first @n bytes of @s2.
+
<!-- ##### FUNCTION g_completion_free ##### -->
<para>
Frees all memory used by the #GCompletion.
the new start of the list, which may have changed.
</para>
<para>
-There is no function to create a #GList. NULL is considered to be the empty
-list so you simply set a #GList* to NULL.
+There is no function to create a #GList. %NULL is considered to be the empty
+list so you simply set a #GList* to %NULL.
</para>
<para>
To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
<!-- ##### FUNCTION g_list_insert_before ##### -->
<para>
-
+Inserts a new element into the list before the given position.
</para>
-@list:
-@sibling:
-@data:
-@Returns:
+@list: a pointer to a #GList.
+@sibling: the list element before which the new element is inserted
+ or %NULL to insert at the end of the list.
+@data: the data for the new element.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_insert_sorted ##### -->
<!-- ##### FUNCTION g_list_remove_link ##### -->
<para>
Removes an element from a #GList, without freeing the element.
-The removed element's prev and next links are set to NULL, so that it becomes a
+The removed element's prev and next links are set to %NULL, so that it becomes a
self-contained list with one element.
</para>
Deletes the node @link from @list.
</para>
-@list: a #GList
-@link: node to delete from @list
-@Returns: the new head of @list
+@list: a #GList.
+@link: node to delete from @list.
+@Returns: the new head of @list.
<!-- ##### FUNCTION g_list_remove_all ##### -->
the first node matching the given data.
</para>
-@list: a #GList
-@data: data to remove
-@Returns: new head of @list
+@list: a #GList.
+@data: data to remove.
+@Returns: new head of @list.
<!-- ##### FUNCTION g_list_free ##### -->
</para>
</note>
-@list:
+@list: a #GList.
<!-- ##### FUNCTION g_list_alloc ##### -->
Like g_list_sort(), but the comparison function accepts a user data argument.
</para>
-@list: a #GList
-@compare_func: comparison function
-@user_data: user data to pass to comparison function
-@Returns: the new head of @list
+@list: a #GList.
+@compare_func: comparison function.
+@user_data: user data to pass to comparison function.
+@Returns: the new head of @list.
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
</para>
@list: a #GList.
-@Returns: the first element in a #GList, or NULL if the #GList has no elements.
+@Returns: the first element in a #GList, or %NULL if the #GList has no elements.
<!-- ##### FUNCTION g_list_last ##### -->
</para>
@list: a #GList.
-@Returns: the last element in the #GList, or NULL if the #GList has no
+@Returns: the last element in the #GList, or %NULL if the #GList has no
elements.
</para>
@list: an element in a #GList.
-@Returns: the previous element, or NULL if there are no previous elements.
+@Returns: the previous element, or %NULL if there are no previous elements.
<!-- ##### MACRO g_list_next ##### -->
</para>
@list: an element in a #GList.
-@Returns: the next element, or NULL if there are no more elements.
+@Returns: the next element, or %NULL if there are no more elements.
<!-- ##### FUNCTION g_list_nth ##### -->
@list: a #GList.
@n: the position of the element, counting from 0.
-@Returns: the element, or NULL if the position is off the end of the #GList.
+@Returns: the element, or %NULL if the position is off the end of the #GList.
<!-- ##### FUNCTION g_list_nth_data ##### -->
@list: a #GList.
@n: the position of the element.
-@Returns: the element's data, or NULL if the position is off the end of the
+@Returns: the element's data, or %NULL if the position is off the end of the
#GList.
<!-- ##### FUNCTION g_list_nth_prev ##### -->
<para>
-
+Gets the element @n places before @list.
</para>
-@list:
-@n:
-@Returns:
+@list: a #GList.
+@n: the position of the element, counting from 0.
+@Returns: the element, or %NULL if the position is off the end of the #GList.
<!-- ##### FUNCTION g_list_find ##### -->
@list: a #GList.
@data: the element data to find.
-@Returns: the found #GList element, or NULL if it is not found.
+@Returns: the found #GList element, or %NULL if it is not found.
<!-- ##### FUNCTION g_list_find_custom ##### -->
@data: user data passed to the function.
@func: the function to call for each element. It should return 0 when the
desired element is found.
-@Returns: the found #GList element, or NULL if it is not found.
+@Returns: the found #GList element, or %NULL if it is not found.
<!-- ##### FUNCTION g_list_position ##### -->
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 null character.
+not including the terminating nul character.
</para>
<para>
-The str field is zero-terminated and so can be used as an ordinary C
+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>
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
+@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.
+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>
<!-- ##### FUNCTION g_string_assign ##### -->
<para>
Copies the characters from one #GString into another, destroying any previous
-contents. It is rather like the standard strcpy() function, except that
+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>
<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.
+except that the #GString buffer automatically expands to contain the results.
+The previous contents of the #GString are destroyed.
</para>
<!-- # Unused Parameters # -->
<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.
+the text is appended to the #GString.
</para>
<!-- # Unused Parameters # -->
<!-- ##### 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:
-@format:
-@Varargs:
+@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_printfa ##### -->
<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:
+@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_append ##### -->
@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
+@string: a #GString.
+@val: bytes to append.
+@len: number of bytes of @val to use.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_prepend ##### -->
@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
+@string: a #GString.
+@val: bytes to prepend.
+@len: number of bytes in @val to prepend.
+@Returns: the #GString passed in.
<!-- ##### FUNCTION g_string_insert ##### -->
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
+@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 ##### -->
<!-- ##### FUNCTION g_string_free ##### -->
<para>
Frees the memory allocated for the #GString.
-If free_segment is TRUE it also frees the character data.
+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:
+@free_segment: if %TRUE the actual character data is freed as well.
<!-- ##### FUNCTION g_string_up ##### -->
Creates a hash code for @str; for use with #GHashTable.
</para>
-@str: a string to hash
-@Returns: hash code for @str
+@str: a string to hash.
+@Returns: hash code for @str.
<!-- ##### FUNCTION g_string_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
+@v: a #GString.
+@v2: another #GString.
+@Returns: %TRUE if they strings are the same length and contain the same bytes.
<!-- ##### MACRO g_return_if_fail ##### -->
<para>
Returns from the current function if the expression is not true.
-If the expression evaluates to FALSE, a critical message is logged and
+If the expression evaluates to %FALSE, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</para>
<para>
Returns from the current function, returning the value @val, if the expression
is not true.
-If the expression evaluates to FALSE, a critical message is logged and
+If the expression evaluates to %FALSE, a critical message is logged and
@val is returned.
</para>
<!-- ##### MACRO g_return_if_reached ##### -->
<para>
-
+Logs a critical message and returns from the current function.
+This can only be used in functions which do not return a value.
</para>
<!-- ##### MACRO g_return_val_if_reached ##### -->
<para>
-
+Logs a critical message and returns @val.
</para>
-@val:
+@val: the value to return from the current function.
<!-- ##### MACRO g_assert ##### -->
</para>
<para>
The macro can be turned off in final releases of code by defining
-G_DISABLE_ASSERT when compiling the application.
+#G_DISABLE_ASSERT when compiling the application.
</para>
@expr: the expression to check.
</para>
<para>
The macro can be turned off in final releases of code by defining
-G_DISABLE_ASSERT when compiling the application.
+#G_DISABLE_ASSERT when compiling the application.
</para>
<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
-Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed".
+Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
This function is intended to be used for debugging use only.
FIXME: How do you set it up?
</para>
<para>
-If Exit is selected, the application terminates with a call to
+If [E]xit is selected, the application terminates with a call to
<function>_exit(0)</function>.
</para>
<para>
-If Halt is selected, the application enters an infinite loop.
+If [H]alt is selected, the application enters an infinite loop.
The infinite loop can only be stopped by killing the application,
-or by setting glib_on_error_halt to FALSE (possibly via a debugger).
+or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
</para>
<para>
-If Stack trace is selected, g_on_error_stack_trace() is called. This
-invokes gdb, which attaches to the current process and shows a stack trace.
+If [S]tack trace is selected, g_on_error_stack_trace() is called. This
+invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</para>
<para>
-If Proceed is selected, the function returns.
+If [P]roceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
-@prg_name: the program name, needed by gdb for the [S]tack trace option.
-If @prg_name is NULL, g_get_prgname() is called to get the program name
+@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
+If @prg_name is %NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
-Invokes gdb, which attaches to the current process and shows a stack trace.
+Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
Called by g_on_error_query() when the [S]tack trace option is selected.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
-@prg_name: the program name, needed by gdb for the [S]tack trace option.
-If @prg_name is NULL, g_get_prgname() is called to get the program name
+@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
+If @prg_name is %NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
projects / platform / upstream / glib.git / commitdiff