luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-27 20:52:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify handling of 64-bit integer literals with g_object_new()

Browse Source 
As with `g_variant_new()` (or any varargs function which takes integer
literals of differing widths), callers need to be careful to ensure
their integer literals have the right width.

Tweak the documentation for `g_object_new()`, `g_object_set()` and
`g_object_get()` to clarify this. The documentation for `g_object_get()`
shows that it is not subject to the same caveats, since it operates on
pointers.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Closes: #833
This commit is contained in:
Philip Withnall 2019-12-17 11:56:35 +00:00
parent c597b0e552
commit 2474c65037
1 changed files with 23 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
gobject/gobject.c
View File

@ -1747,6 +1747,20 @@ g_object_get_type (void)
* Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
* which are not explicitly specified are set to their default values.
*
* Note that in C, small integer types in variable argument lists are promoted
* up to #gint or #guint as appropriate, and read back accordingly. #gint is 32
* bits on every platform on which GLib is currently supported. This means that
* you can use C expressions of type #gint with g_object_new() and properties of
* type #gint or #guint or smaller. Specifically, you can use integer literals
* with these property types.
*
* When using property types of #gint64 or #guint64, you must ensure that the
* value that you provide is 64 bit. This means that you should use a cast or
* make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
*
* Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value
* you provide is a #gdouble, even for a property of type #gfloat.
*
* Returns: (transfer full) (type GObject.Object): a new instance of
* @object_type
*/
@ -2575,6 +2589,11 @@ g_object_get_valist (GObject *object,
*
* Sets properties on an object.
*
* The same caveats about passing integer literals as varargs apply as with
* g_object_new(). In particular, any integer literals set as the values for
* properties of type #gint64 or #guint64 must be 64 bits wide, using the
* %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
*
* Note that the "notify" signals are queued and only emitted (in
* reverse order) after all properties have been set. See
* g_object_freeze_notify().
@ -2611,16 +2630,18 @@ g_object_set (gpointer _object,
* of three properties: an integer, a string and an object:
* |[<!-- language="C" -->
* gint intval;
* guint64 uint64val;
* gchar *strval;
* GObject *objval;
*
* g_object_get (my_object,
* "int-property", &intval,
* "uint64-property", &uint64val,
* "str-property", &strval,
* "obj-property", &objval,
* NULL);
*
* // Do something with intval, strval, objval
* // Do something with intval, uint64val, strval, objval
*
* g_free (strval);
* g_object_unref (objval);