luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 06:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'improve-set_str-documentation' into 'main'

Browse Source 
gstrfuncs: Improve and port g_set_str() docs to gi-docgen

See merge request GNOME/glib!3810
This commit is contained in:
Philip Withnall 2024-01-15 17:09:17 +00:00
commit 0c9fe8156a
1 changed files with 22 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
glib/gstrfuncs.h
View File

@ -456,28 +456,34 @@ gboolean g_ascii_string_to_unsigned (const gchar *str,
/** /**
* g_set_str: (skip) * g_set_str: (skip)
* @str_pointer: (inout) (not optional) (nullable): a pointer to either a string or %NULL * @str_pointer: (inout) (not optional) (nullable): a pointer to either
* @new_str: (nullable): a string to assign to @str_pointer, or %NULL * a string or `NULL`
* @new_str: (nullable): a string to assign to @str_pointer
* *
* Updates a pointer to a string to a copy of @new_str. The previous string * Updates a pointer to a string to a copy of @new_str and returns whether the
* pointed to by @str_pointer will be freed with g_free(). * string was changed.
* *
* @str_pointer must not be %NULL, but can point to a %NULL value. * If @new_str matches the previous string, this function is a no-op. If
* @new_str is different, a copy of it will be assigned to @str_pointer and
* the previous string pointed to by @str_pointer will be freed with
* [func@GLib.free].
*
* @str_pointer must not be `NULL`, but can point to a `NULL` value.
* *
* One convenient usage of this function is in implementing property settings: * One convenient usage of this function is in implementing property settings:
* |[ * ```C
* void * void
* foo_set_bar (Foo *foo, * foo_set_bar (Foo *foo,
* const char *new_bar) * const char *new_bar)
* { * {
* g_return_if_fail (IS_FOO (foo)); * g_return_if_fail (IS_FOO (foo));
* *
* if (g_set_str (&foo->bar, new_bar)) * if (g_set_str (&foo->bar, new_bar))
* g_object_notify (foo, "bar"); * g_object_notify (foo, "bar");
* } * }
* ]| * ```
* *
* Returns: %TRUE if the value of @str_pointer changed, %FALSE otherwise * Returns: true if the value of @str_pointer changed, false otherwise
* *
* Since: 2.76 * Since: 2.76
*/ */