luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +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)
* @str_pointer: (inout) (not optional) (nullable): a pointer to either a string or %NULL
* @new_str: (nullable): a string to assign to @str_pointer, or %NULL
* @str_pointer: (inout) (not optional) (nullable): a pointer to either
* 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
* pointed to by @str_pointer will be freed with g_free().
* Updates a pointer to a string to a copy of @new_str and returns whether the
* 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:
* |[
* void
* foo_set_bar (Foo *foo,
* const char *new_bar)
* {
* g_return_if_fail (IS_FOO (foo));
* ```C
* void
* foo_set_bar (Foo *foo,
* const char *new_bar)
* {
* g_return_if_fail (IS_FOO (foo));
*
* if (g_set_str (&foo->bar, new_bar))
* g_object_notify (foo, "bar");
* }
* ]|
* if (g_set_str (&foo->bar, new_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
*/