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

Merge branch 'gvarianttype-docs' into 'main'

Browse Source 
gvarianttype: Add two missing (nullable) annotations and port docs to gi-docgen format

See merge request GNOME/glib!4326
This commit is contained in:
Philip Withnall 2024-10-19 00:44:46 +00:00
commit b465ca1e9e
2 changed files with 193 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

309
glib/gvarianttype.c
View File

@ -276,10 +276,11 @@ variant_type_string_scan_internal (const gchar *string,
/** /**
* g_variant_type_string_scan: * g_variant_type_string_scan:
* @string: a pointer to any string * @string: a pointer to any string
* @limit: (nullable): the end of @string, or %NULL * @limit: (nullable): the end of @string
* @endptr: (out) (optional): location to store the end pointer, or %NULL * @endptr: (out) (optional): location to store the end pointer
* *
* Scan for a single complete and valid GVariant type string in @string. * Scan for a single complete and valid GVariant type string in @string.
*
* The memory pointed to by @limit (or bytes beyond it) is never * The memory pointed to by @limit (or bytes beyond it) is never
* accessed. * accessed.
* *
@ -291,10 +292,9 @@ variant_type_string_scan_internal (const gchar *string,
* string does not end before @limit then %FALSE is returned. * string does not end before @limit then %FALSE is returned.
* *
* For the simple case of checking if a string is a valid type string, * For the simple case of checking if a string is a valid type string,
* see g_variant_type_string_is_valid(). * see [func@GLib.VariantType.string_is_valid].
*
* Returns: %TRUE if a valid type string was found
* *
* Returns: true if a valid type string was found
* Since: 2.24 * Since: 2.24
**/ **/
gboolean gboolean
@ -314,9 +314,9 @@ g_variant_type_string_scan (const gchar *string,
* return depth 1, and a container type will return a greater value. The depth * return depth 1, and a container type will return a greater value. The depth
* of a tuple is 1 plus the depth of its deepest child type. * of a tuple is 1 plus the depth of its deepest child type.
* *
* If @type_string is not a valid #GVariant type string, 0 will be returned. * If @type_string is not a valid [type@GLib.Variant] type string, `0` will be returned.
* *
* Returns: depth of @type_string, or 0 on error * Returns: depth of @type_string, or `0` on error
* Since: 2.60 * Since: 2.60
*/ */
gsize gsize
@ -339,12 +339,13 @@ g_variant_type_string_get_depth_ (const gchar *type_string)
* g_variant_type_string_is_valid: * g_variant_type_string_is_valid:
* @type_string: a pointer to any string * @type_string: a pointer to any string
* *
* Checks if @type_string is a valid GVariant type string. This call is * Checks if @type_string is a valid
* equivalent to calling g_variant_type_string_scan() and confirming * [GVariant type string](./struct.VariantType.html#gvariant-type-strings).
* that the following character is a nul terminator.
* *
* Returns: %TRUE if @type_string is exactly one valid type string * This call is equivalent to calling [func@GLib.VariantType.string_scan] and
* confirming that the following character is a nul terminator.
* *
* Returns: true if @type_string is exactly one valid type string
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -362,13 +363,13 @@ g_variant_type_string_is_valid (const gchar *type_string)
/** /**
* g_variant_type_free: * g_variant_type_free:
* @type: (nullable): a #GVariantType, or %NULL * @type: (nullable): type to free
* *
* Frees a #GVariantType that was allocated with * Frees a [type@GLib.VariantType] that was allocated with
* g_variant_type_copy(), g_variant_type_new() or one of the container * [method@GLib.VariantType.copy], [ctor@GLib.VariantType.new] or one of the
* type constructor functions. * container type constructor functions.
* *
* In the case that @type is %NULL, this function does nothing. * In the case that @type is `NULL`, this function does nothing.
* *
* Since 2.24 * Since 2.24
**/ **/
@ -382,13 +383,14 @@ g_variant_type_free (GVariantType *type)
/** /**
* g_variant_type_copy: * g_variant_type_copy:
* @type: a #GVariantType * @type: (not nullable): type to copy
* *
* Makes a copy of a #GVariantType. It is appropriate to call * Makes a copy of a [type@GLib.VariantType].
* g_variant_type_free() on the return value. @type may not be %NULL.
* *
* Returns: (transfer full): a new #GVariantType * It is appropriate to call [method@GLib.VariantType.free] on the return value.
* @type may not be `NULL`.
* *
* Returns: (transfer full): a new [type@GLib.VariantType]
* Since 2.24 * Since 2.24
**/ **/
GVariantType * GVariantType *
@ -410,17 +412,17 @@ g_variant_type_copy (const GVariantType *type)
/** /**
* g_variant_type_new: * g_variant_type_new:
* @type_string: a valid GVariant type string * @type_string: a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings)
* *
* Creates a new #GVariantType corresponding to the type string given * Creates a new [type@GLib.VariantType] corresponding to the type string given
* by @type_string. It is appropriate to call g_variant_type_free() on * by @type_string.
* the return value. *
* It is appropriate to call [method@GLib.VariantType.free] on the return value.
* *
* It is a programmer error to call this function with an invalid type * It is a programmer error to call this function with an invalid type
* string. Use g_variant_type_string_is_valid() if you are unsure. * string. Use [func@GLib.VariantType.string_is_valid] if you are unsure.
*
* Returns: (transfer full): a new #GVariantType
* *
* Returns: (transfer full): a new [type@GLib.VariantType]
* Since: 2.24 * Since: 2.24
*/ */
GVariantType * GVariantType *
@ -433,14 +435,14 @@ g_variant_type_new (const gchar *type_string)
/** /**
* g_variant_type_get_string_length: * g_variant_type_get_string_length:
* @type: a #GVariantType * @type: type to measure
* *
* Returns the length of the type string corresponding to the given * Returns the length of the type string corresponding to the given @type.
* @type. This function must be used to determine the valid extent of *
* the memory region returned by g_variant_type_peek_string(). * This function must be used to determine the valid extent of
* the memory region returned by [method@GLib.VariantType.peek_string].
* *
* Returns: the length of the corresponding type string * Returns: the length of the corresponding type string
*
* Since 2.24 * Since 2.24
**/ **/
gsize gsize
@ -476,16 +478,16 @@ g_variant_type_get_string_length (const GVariantType *type)
*/ */
/** /**
* g_variant_type_peek_string: (skip) * g_variant_type_peek_string: (skip)
* @type: a #GVariantType * @type: type to peek at
* *
* Returns the type string corresponding to the given @type. The * Returns the type string corresponding to the given @type.
* result is not nul-terminated; in order to determine its length you
* must call g_variant_type_get_string_length().
* *
* To get a nul-terminated string, see g_variant_type_dup_string(). * The result is not nul-terminated; in order to determine its length you
* must call [method@GLib.VariantType.get_string_length].
*
* To get a nul-terminated string, see [method@GLib.VariantType.dup_string].
* *
* Returns: the corresponding type string (not nul-terminated) * Returns: the corresponding type string (not nul-terminated)
*
* Since 2.24 * Since 2.24
**/ **/
const gchar * const gchar *
@ -498,14 +500,14 @@ g_variant_type_peek_string (const GVariantType *type)
/** /**
* g_variant_type_dup_string: * g_variant_type_dup_string:
* @type: a #GVariantType * @type: type to copy
* *
* Returns a newly-allocated copy of the type string corresponding to * Returns a newly-allocated copy of the type string corresponding to @type.
* @type. The returned string is nul-terminated. It is appropriate to *
* call g_free() on the return value. * The returned string is nul-terminated. It is appropriate to call
* [func@GLib.free] on the return value.
* *
* Returns: (transfer full): the corresponding type string * Returns: (transfer full): the corresponding type string
*
* Since 2.24 * Since 2.24
**/ **/
gchar * gchar *
@ -519,21 +521,20 @@ g_variant_type_dup_string (const GVariantType *type)
/** /**
* g_variant_type_is_definite: * g_variant_type_is_definite:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is definite (ie: not indefinite). * Determines if the given @type is definite (ie: not indefinite).
* *
* A type is definite if its type string does not contain any indefinite * A type is definite if its type string does not contain any indefinite
* type characters ('*', '?', or 'r'). * type characters (`*`, `?`, or `r`).
* *
* A #GVariant instance may not have an indefinite type, so calling * A [type@GLib.Variant] instance may not have an indefinite type, so calling
* this function on the result of g_variant_get_type() will always * this function on the result of [method@GLib.Variant.get_type] will always
* result in %TRUE being returned. Calling this function on an * result in true being returned. Calling this function on an
* indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in * indefinite type like `G_VARIANT_TYPE_ARRAY`, however, will result in
* %FALSE being returned. * `FALSE` being returned.
*
* Returns: %TRUE if @type is definite
* *
* Returns: true if @type is definite
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -559,19 +560,18 @@ g_variant_type_is_definite (const GVariantType *type)
/** /**
* g_variant_type_is_container: * g_variant_type_is_container:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is a container type. * Determines if the given @type is a container type.
* *
* Container types are any array, maybe, tuple, or dictionary * Container types are any array, maybe, tuple, or dictionary
* entry types plus the variant type. * entry types plus the variant type.
* *
* This function returns %TRUE for any indefinite type for which every * This function returns true for any indefinite type for which every
* definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for * definite subtype is a container — `G_VARIANT_TYPE_ARRAY`, for
* example. * example.
* *
* Returns: %TRUE if @type is a container type * Returns: true if @type is a container type
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -599,7 +599,7 @@ g_variant_type_is_container (const GVariantType *type)
/** /**
* g_variant_type_is_basic: * g_variant_type_is_basic:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is a basic type. * Determines if the given @type is a basic type.
* *
@ -608,11 +608,10 @@ g_variant_type_is_container (const GVariantType *type)
* *
* Only a basic type may be used as the key of a dictionary entry. * Only a basic type may be used as the key of a dictionary entry.
* *
* This function returns %FALSE for all indefinite types except * This function returns `FALSE` for all indefinite types except
* %G_VARIANT_TYPE_BASIC. * `G_VARIANT_TYPE_BASIC`.
*
* Returns: %TRUE if @type is a basic type
* *
* Returns: true if @type is a basic type
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -648,17 +647,17 @@ g_variant_type_is_basic (const GVariantType *type)
/** /**
* g_variant_type_is_maybe: * g_variant_type_is_maybe:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is a maybe type. This is true if the * Determines if the given @type is a ‘maybe’ type.
* type string for @type starts with an 'm'.
* *
* This function returns %TRUE for any indefinite type for which every * This is true if the type string for @type starts with an `m`.
* definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for *
* This function returns true for any indefinite type for which every
* definite subtype is a ‘maybe’ type — `G_VARIANT_TYPE_MAYBE`, for
* example. * example.
* *
* Returns: %TRUE if @type is a maybe type * Returns: true if @type is a ‘maybe’ type
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -671,17 +670,17 @@ g_variant_type_is_maybe (const GVariantType *type)
/** /**
* g_variant_type_is_array: * g_variant_type_is_array:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is an array type. This is true if the * Determines if the given @type is an array type.
* type string for @type starts with an 'a'.
* *
* This function returns %TRUE for any indefinite type for which every * This is true if the type string for @type starts with an `a`.
* definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for *
* This function returns true for any indefinite type for which every
* definite subtype is an array type — `G_VARIANT_TYPE_ARRAY`, for
* example. * example.
* *
* Returns: %TRUE if @type is an array type * Returns: true if @type is an array type
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -694,18 +693,18 @@ g_variant_type_is_array (const GVariantType *type)
/** /**
* g_variant_type_is_tuple: * g_variant_type_is_tuple:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is a tuple type. This is true if the * Determines if the given @type is a tuple type.
* type string for @type starts with a '(' or if @type is
* %G_VARIANT_TYPE_TUPLE.
* *
* This function returns %TRUE for any indefinite type for which every * This is true if the type string for @type starts with a `(` or if @type is
* definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for * `G_VARIANT_TYPE_TUPLE`.
*
* This function returns true for any indefinite type for which every
* definite subtype is a tuple type — `G_VARIANT_TYPE_TUPLE`, for
* example. * example.
* *
* Returns: %TRUE if @type is a tuple type * Returns: true if @type is a tuple type
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -721,17 +720,17 @@ g_variant_type_is_tuple (const GVariantType *type)
/** /**
* g_variant_type_is_dict_entry: * g_variant_type_is_dict_entry:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is a dictionary entry type. This is * Determines if the given @type is a dictionary entry type.
* true if the type string for @type starts with a '{'.
* *
* This function returns %TRUE for any indefinite type for which every * This is true if the type string for @type starts with a `{`.
* definite subtype is a dictionary entry type --
* %G_VARIANT_TYPE_DICT_ENTRY, for example.
* *
* Returns: %TRUE if @type is a dictionary entry type * This function returns true for any indefinite type for which every
* definite subtype is a dictionary entry type —
* `G_VARIANT_TYPE_DICT_ENTRY`, for example.
* *
* Returns: true if @type is a dictionary entry type
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -744,12 +743,11 @@ g_variant_type_is_dict_entry (const GVariantType *type)
/** /**
* g_variant_type_is_variant: * g_variant_type_is_variant:
* @type: a #GVariantType * @type: type to check
* *
* Determines if the given @type is the variant type. * Determines if the given @type is the variant type.
* *
* Returns: %TRUE if @type is the variant type * Returns: true if @type is the variant type
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -762,16 +760,15 @@ g_variant_type_is_variant (const GVariantType *type)
/** /**
* g_variant_type_hash: * g_variant_type_hash:
* @type: (type GVariantType): a #GVariantType * @type: (type GVariantType): type to hash
* *
* Hashes @type. * Hashes @type.
* *
* The argument type of @type is only #gconstpointer to allow use with * The argument type of @type is only `gconstpointer` to allow use with
* #GHashTable without function pointer casting. A valid * [type@GLib.HashTable] without function pointer casting. A valid
* #GVariantType must be provided. * [type@GLib.VariantType] must be provided.
* *
* Returns: the hash value * Returns: the hash value
*
* Since 2.24 * Since 2.24
**/ **/
guint guint
@ -784,22 +781,21 @@ g_variant_type_hash (gconstpointer type)
/** /**
* g_variant_type_equal: * g_variant_type_equal:
* @type1: (type GVariantType): a #GVariantType * @type1: (type GVariantType): type to compare
* @type2: (type GVariantType): a #GVariantType * @type2: (type GVariantType): another type to compare
* *
* Compares @type1 and @type2 for equality. * Compares @type1 and @type2 for equality.
* *
* Only returns %TRUE if the types are exactly equal. Even if one type * Only returns true if the types are exactly equal. Even if one type
* is an indefinite type and the other is a subtype of it, %FALSE will * is an indefinite type and the other is a subtype of it, false will
* be returned if they are not exactly equal. If you want to check for * be returned if they are not exactly equal. If you want to check for
* subtypes, use g_variant_type_is_subtype_of(). * subtypes, use [method@GLib.VariantType.is_subtype_of].
* *
* The argument types of @type1 and @type2 are only #gconstpointer to * The argument types of @type1 and @type2 are only `gconstpointer` to
* allow use with #GHashTable without function pointer casting. For * allow use with [type@GLib.HashTable] without function pointer casting. For
* both arguments, a valid #GVariantType must be provided. * both arguments, a valid [type@GLib.VariantType] must be provided.
*
* Returns: %TRUE if @type1 and @type2 are exactly equal
* *
* Returns: true if @type1 and @type2 are exactly equal
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -814,17 +810,16 @@ g_variant_type_equal (gconstpointer type1,
/** /**
* g_variant_type_is_subtype_of: * g_variant_type_is_subtype_of:
* @type: a #GVariantType * @type: type to check
* @supertype: a #GVariantType * @supertype: type of potential supertype
* *
* Checks if @type is a subtype of @supertype. * Checks if @type is a subtype of @supertype.
* *
* This function returns %TRUE if @type is a subtype of @supertype. All * This function returns true if @type is a subtype of @supertype. All
* types are considered to be subtypes of themselves. Aside from that, * types are considered to be subtypes of themselves. Aside from that,
* only indefinite types can have subtypes. * only indefinite types can have subtypes.
* *
* Returns: %TRUE if @type is a subtype of @supertype * Returns: true if @type is a subtype of @supertype
*
* Since 2.24 * Since 2.24
**/ **/
gboolean gboolean
@ -907,14 +902,13 @@ g_variant_type_is_subtype_of (const GVariantType *type,
/** /**
* g_variant_type_element: * g_variant_type_element:
* @type: an array or maybe #GVariantType * @type: an array or ‘maybe’ type
* *
* Determines the element type of an array or maybe type. * Determines the element type of an array or ‘maybe’ type.
* *
* This function may only be used with array or maybe types. * This function may only be used with array or ‘maybe’ types.
* *
* Returns: (transfer none): the element type of @type * Returns: (transfer none): the element type of @type
*
* Since 2.24 * Since 2.24
**/ **/
const GVariantType * const GVariantType *
@ -933,25 +927,25 @@ g_variant_type_element (const GVariantType *type)
/** /**
* g_variant_type_first: * g_variant_type_first:
* @type: a tuple or dictionary entry #GVariantType * @type: a tuple or dictionary entry type
* *
* Determines the first item type of a tuple or dictionary entry * Determines the first item type of a tuple or dictionary entry
* type. * type.
* *
* This function may only be used with tuple or dictionary entry types, * This function may only be used with tuple or dictionary entry types,
* but must not be used with the generic tuple type * but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE. * `G_VARIANT_TYPE_TUPLE`.
* *
* In the case of a dictionary entry type, this returns the type of * In the case of a dictionary entry type, this returns the type of
* the key. * the key.
* *
* %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. * `NULL` is returned in case of @type being `G_VARIANT_TYPE_UNIT`.
* *
* This call, together with g_variant_type_next() provides an iterator * This call, together with [method@GLib.VariantType.next] provides an iterator
* interface over tuple and dictionary entry types. * interface over tuple and dictionary entry types.
* *
* Returns: (transfer none): the first item type of @type, or %NULL * Returns: (transfer none) (nullable): the first item type of @type, or `NULL`
* * if the type has no item types
* Since 2.24 * Since 2.24
**/ **/
const GVariantType * const GVariantType *
@ -972,22 +966,22 @@ g_variant_type_first (const GVariantType *type)
/** /**
* g_variant_type_next: * g_variant_type_next:
* @type: a #GVariantType from a previous call * @type: a type from a previous call
* *
* Determines the next item type of a tuple or dictionary entry * Determines the next item type of a tuple or dictionary entry
* type. * type.
* *
* @type must be the result of a previous call to * @type must be the result of a previous call to
* g_variant_type_first() or g_variant_type_next(). * [method@GLib.VariantType.first] or [method@GLib.VariantType.next].
* *
* If called on the key type of a dictionary entry then this call * If called on the key type of a dictionary entry then this call
* returns the value type. If called on the value type of a dictionary * returns the value type. If called on the value type of a dictionary
* entry then this call returns %NULL. * entry then this call returns `NULL`.
* *
* For tuples, %NULL is returned when @type is the last item in a tuple. * For tuples, `NULL` is returned when @type is the last item in the tuple.
*
* Returns: (transfer none): the next #GVariantType after @type, or %NULL
* *
* Returns: (transfer none) (nullable): the next type after @type, or `NULL` if
* there are no further types
* Since 2.24 * Since 2.24
**/ **/
const GVariantType * const GVariantType *
@ -1008,20 +1002,19 @@ g_variant_type_next (const GVariantType *type)
/** /**
* g_variant_type_n_items: * g_variant_type_n_items:
* @type: a tuple or dictionary entry #GVariantType * @type: a tuple or dictionary entry type
* *
* Determines the number of items contained in a tuple or * Determines the number of items contained in a tuple or
* dictionary entry type. * dictionary entry type.
* *
* This function may only be used with tuple or dictionary entry types, * This function may only be used with tuple or dictionary entry types,
* but must not be used with the generic tuple type * but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE. * `G_VARIANT_TYPE_TUPLE`.
* *
* In the case of a dictionary entry type, this function will always * In the case of a dictionary entry type, this function will always
* return 2. * return `2`.
* *
* Returns: the number of items in @type * Returns: the number of items in @type
*
* Since 2.24 * Since 2.24
**/ **/
gsize gsize
@ -1041,16 +1034,15 @@ g_variant_type_n_items (const GVariantType *type)
/** /**
* g_variant_type_key: * g_variant_type_key:
* @type: a dictionary entry #GVariantType * @type: a dictionary entry type
* *
* Determines the key type of a dictionary entry type. * Determines the key type of a dictionary entry type.
* *
* This function may only be used with a dictionary entry type. Other * This function may only be used with a dictionary entry type. Other
* than the additional restriction, this call is equivalent to * than the additional restriction, this call is equivalent to
* g_variant_type_first(). * [method@GLib.VariantType.first].
* *
* Returns: (transfer none): the key type of the dictionary entry * Returns: (transfer none): the key type of the dictionary entry
*
* Since 2.24 * Since 2.24
**/ **/
const GVariantType * const GVariantType *
@ -1068,14 +1060,13 @@ g_variant_type_key (const GVariantType *type)
/** /**
* g_variant_type_value: * g_variant_type_value:
* @type: a dictionary entry #GVariantType * @type: a dictionary entry type
* *
* Determines the value type of a dictionary entry type. * Determines the value type of a dictionary entry type.
* *
* This function may only be used with a dictionary entry type. * This function may only be used with a dictionary entry type.
* *
* Returns: (transfer none): the value type of the dictionary entry * Returns: (transfer none): the value type of the dictionary entry
*
* Since 2.24 * Since 2.24
**/ **/
const GVariantType * const GVariantType *
@ -1097,18 +1088,17 @@ g_variant_type_value (const GVariantType *type)
/** /**
* g_variant_type_new_tuple: * g_variant_type_new_tuple:
* @items: (array length=length): an array of #GVariantTypes, one for each item * @items: (array length=length): an array of types, one for each item
* @length: the length of @items, or -1 * @length: the length of @items, or `-1`
* *
* Constructs a new tuple type, from @items. * Constructs a new tuple type, from @items.
* *
* @length is the number of items in @items, or -1 to indicate that * @length is the number of items in @items, or `-1` to indicate that
* @items is %NULL-terminated. * @items is `NULL`-terminated.
* *
* It is appropriate to call g_variant_type_free() on the return value. * It is appropriate to call [method@GLib.VariantType.free] on the return value.
*
* Returns: (transfer full): a new tuple #GVariantType
* *
* Returns: (transfer full): a new tuple type
* Since 2.24 * Since 2.24
**/ **/
static GVariantType * static GVariantType *
@ -1183,15 +1173,14 @@ g_variant_type_new_tuple (const GVariantType * const *items,
/** /**
* g_variant_type_new_array: (constructor) * g_variant_type_new_array: (constructor)
* @element: a #GVariantType * @element: an element type
* *
* Constructs the type corresponding to an array of elements of the * Constructs the type corresponding to an array of elements of the
* type @type. * type @type.
* *
* It is appropriate to call g_variant_type_free() on the return value. * It is appropriate to call [method@GLib.VariantType.first] on the return value.
*
* Returns: (transfer full): a new array #GVariantType
* *
* Returns: (transfer full): a new array type
* Since 2.24 * Since 2.24
**/ **/
GVariantType * GVariantType *
@ -1213,15 +1202,14 @@ g_variant_type_new_array (const GVariantType *element)
/** /**
* g_variant_type_new_maybe: (constructor) * g_variant_type_new_maybe: (constructor)
* @element: a #GVariantType * @element: an element type
* *
* Constructs the type corresponding to a maybe instance containing * Constructs the type corresponding to a ‘maybe’ instance containing
* type @type or Nothing. * type @type or `Nothing`.
* *
* It is appropriate to call g_variant_type_free() on the return value. * It is appropriate to call [method@GLib.VariantType.free] on the return value.
*
* Returns: (transfer full): a new maybe #GVariantType
* *
* Returns: (transfer full): a new ‘maybe’ type
* Since 2.24 * Since 2.24
**/ **/
GVariantType * GVariantType *
@ -1243,16 +1231,15 @@ g_variant_type_new_maybe (const GVariantType *element)
/** /**
* g_variant_type_new_dict_entry: (constructor) * g_variant_type_new_dict_entry: (constructor)
* @key: a basic #GVariantType * @key: a basic type to use for the key
* @value: a #GVariantType * @value: a type to use for the value
* *
* Constructs the type corresponding to a dictionary entry with a key * Constructs the type corresponding to a dictionary entry with a key
* of type @key and a value of type @value. * of type @key and a value of type @value.
* *
* It is appropriate to call g_variant_type_free() on the return value. * It is appropriate to call [method@GLib.VariantType.free] on the return value.
*
* Returns: (transfer full): a new dictionary entry #GVariantType
* *
* Returns: (transfer full): a new dictionary entry type
* Since 2.24 * Since 2.24
**/ **/
GVariantType * GVariantType *

74
glib/gvarianttype.h
View File

@ -36,7 +36,7 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_BOOLEAN: * G_VARIANT_TYPE_BOOLEAN:
* *
* The type of a value that can be either %TRUE or %FALSE. * The type of a value that can be either true or false.
**/ **/
#define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b") #define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b")
@ -58,6 +58,7 @@ typedef struct _GVariantType GVariantType;
* G_VARIANT_TYPE_UINT16: * G_VARIANT_TYPE_UINT16:
* *
* The type of an integer value that can range from 0 to 65535. * The type of an integer value that can range from 0 to 65535.
*
* There were about this many people living in Toronto in the 1870s. * There were about this many people living in Toronto in the 1870s.
**/ **/
#define G_VARIANT_TYPE_UINT16 ((const GVariantType *) "q") #define G_VARIANT_TYPE_UINT16 ((const GVariantType *) "q")
@ -74,7 +75,8 @@ typedef struct _GVariantType GVariantType;
* G_VARIANT_TYPE_UINT32: * G_VARIANT_TYPE_UINT32:
* *
* The type of an integer value that can range from 0 to 4294967295. * The type of an integer value that can range from 0 to 4294967295.
* That's one number for everyone who was around in the late 1970s. *
* That’s one number for everyone who was around in the late 1970s.
**/ **/
#define G_VARIANT_TYPE_UINT32 ((const GVariantType *) "u") #define G_VARIANT_TYPE_UINT32 ((const GVariantType *) "u")
@ -90,18 +92,21 @@ typedef struct _GVariantType GVariantType;
* G_VARIANT_TYPE_UINT64: * G_VARIANT_TYPE_UINT64:
* *
* The type of an integer value that can range from 0 * The type of an integer value that can range from 0
* to 18446744073709551615 (inclusive). That's a really big number, * to 18446744073709551615 (inclusive).
* but a Rubik's cube can have a bit more than twice as many possible *
* positions. * That’s a really big number, but a Rubik’s cube can have a bit more than
* twice as many possible positions.
**/ **/
#define G_VARIANT_TYPE_UINT64 ((const GVariantType *) "t") #define G_VARIANT_TYPE_UINT64 ((const GVariantType *) "t")
/** /**
* G_VARIANT_TYPE_DOUBLE: * G_VARIANT_TYPE_DOUBLE:
* *
* The type of a double precision IEEE754 floating point number. * The type of a double precision
* These guys go up to about 1.80e308 (plus and minus) but miss out on * [IEEE 754 floating point number](https://en.wikipedia.org/wiki/IEEE_754).
* some numbers in between. In any case, that's far greater than the *
* These go up to about 1.80e308 (plus and minus) but miss out on
* some numbers in between. In any case, that’s far greater than the
* estimated number of fundamental particles in the observable * estimated number of fundamental particles in the observable
* universe. * universe.
**/ **/
@ -110,32 +115,39 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_STRING: * G_VARIANT_TYPE_STRING:
* *
* The type of a string. "" is a string. %NULL is not a string. * The type of a string.
*
* `""` is a string. `NULL` is not a string.
**/ **/
#define G_VARIANT_TYPE_STRING ((const GVariantType *) "s") #define G_VARIANT_TYPE_STRING ((const GVariantType *) "s")
/** /**
* G_VARIANT_TYPE_OBJECT_PATH: * G_VARIANT_TYPE_OBJECT_PATH:
* *
* The type of a D-Bus object reference. These are strings of a * The type of a
* specific format used to identify objects at a given destination on * [D-Bus object path](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path).
* the bus. *
* These are strings of a specific format used to identify objects at a given
* destination on the bus.
* *
* If you are not interacting with D-Bus, then there is no reason to make * If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a * use of this type. If you are, then the D-Bus specification contains a
* precise description of valid object paths. * [precise description of valid object paths](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path).
**/ **/
#define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o") #define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o")
/** /**
* G_VARIANT_TYPE_SIGNATURE: * G_VARIANT_TYPE_SIGNATURE:
* *
* The type of a D-Bus type signature. These are strings of a specific * The type of a
* format used as type signatures for D-Bus methods and messages. * [D-Bus type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system).
*
* These are strings of a specific format used as type signatures for D-Bus
* methods and messages.
* *
* If you are not interacting with D-Bus, then there is no reason to make * If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a * use of this type. If you are, then the D-Bus specification contains a
* precise description of valid signature strings. * [precise description of valid signature strings](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system).
**/ **/
#define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g") #define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g")
@ -150,7 +162,7 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_HANDLE: * G_VARIANT_TYPE_HANDLE:
* *
* The type of a 32bit signed integer value, that by convention, is used * The type of a 32-bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside * as an index into an array of file descriptors that are sent alongside
* a D-Bus message. * a D-Bus message.
* *
@ -162,8 +174,9 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_UNIT: * G_VARIANT_TYPE_UNIT:
* *
* The empty tuple type. Has only one instance. Known also as "triv" * The empty tuple type.
* or "void". *
* Has only one instance. Known also as ‘triv’ or ‘void’.
**/ **/
#define G_VARIANT_TYPE_UNIT ((const GVariantType *) "()") #define G_VARIANT_TYPE_UNIT ((const GVariantType *) "()")
@ -186,7 +199,7 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_MAYBE: * G_VARIANT_TYPE_MAYBE:
* *
* An indefinite type that is a supertype of every maybe type. * An indefinite type that is a supertype of every ‘maybe’ type.
**/ **/
#define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*") #define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*")
@ -216,7 +229,7 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_DICTIONARY: * G_VARIANT_TYPE_DICTIONARY:
* *
* An indefinite type that is a supertype of every dictionary type -- * An indefinite type that is a supertype of every dictionary type —
* that is, any array type that has an element type equal to any * that is, any array type that has an element type equal to any
* dictionary entry type. * dictionary entry type.
**/ **/
@ -239,8 +252,10 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE_BYTESTRING: * G_VARIANT_TYPE_BYTESTRING:
* *
* The type of an array of bytes. This type is commonly used to pass * The type of an array of bytes.
* around strings that may not be valid utf8. In that case, the *
* This type is commonly used to pass around strings that may not be valid
* UTF-8, such as file system paths. In that case, the
* convention is that the nul terminator character should be included as * convention is that the nul terminator character should be included as
* the last character in the array. * the last character in the array.
**/ **/
@ -257,7 +272,7 @@ typedef struct _GVariantType GVariantType;
* G_VARIANT_TYPE_VARDICT: * G_VARIANT_TYPE_VARDICT:
* *
* The type of a dictionary mapping strings to variants (the ubiquitous * The type of a dictionary mapping strings to variants (the ubiquitous
* "a{sv}" type). * `a{sv}` type).
* *
* Since: 2.30 * Since: 2.30
**/ **/
@ -266,14 +281,15 @@ typedef struct _GVariantType GVariantType;
/** /**
* G_VARIANT_TYPE: * G_VARIANT_TYPE:
* @type_string: a well-formed #GVariantType type string * @type_string: a well-formed [type@GLib.VariantType] type string
* *
* Converts a string to a const #GVariantType. Depending on the * Converts a string to a const [type@GLib.VariantType].
* current debugging level, this function may perform a runtime check *
* to ensure that @string is a valid GVariant type string. * Depending on the current debugging level, this function may perform a runtime
* check to ensure that @string is a valid [type@GLib.Variant] type string.
* *
* It is always a programmer error to use this macro with an invalid * It is always a programmer error to use this macro with an invalid
* type string. If in doubt, use g_variant_type_string_is_valid() to * type string. If in doubt, use [func@GLib.variant_type_string_is_valid] to
* check if the string is valid. * check if the string is valid.
* *
* Since 2.24 * Since 2.24