[glib/gvariant] lots of GVariantType docs/consistency fixes
- From: Ryan Lortie <ryanl src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [glib/gvariant] lots of GVariantType docs/consistency fixes
- Date: Fri, 22 Jan 2010 02:57:55 +0000 (UTC)
commit f2d30dd0067d3b0b3e9f0318d943fd57fa81aa13
Author: Ryan Lortie <desrt desrt ca>
Date: Thu Jan 21 21:54:46 2010 -0500
lots of GVariantType docs/consistency fixes
glib/glib.symbols | 2 +-
glib/gvariant-parser.c | 4 +-
glib/gvariant-serialiser.c | 4 +-
glib/gvariant-util.c | 20 ++--
glib/gvariant-valist.c | 8 +-
glib/gvarianttype.c | 326 +++++++++++++++++++++++---------------------
glib/gvarianttype.h | 41 ++++--
7 files changed, 216 insertions(+), 189 deletions(-)
---
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 2ee1333..ba4cb82 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -1765,7 +1765,7 @@ g_variant_type_new
g_variant_type_get_string_length
g_variant_type_peek_string
g_variant_type_dup_string
-g_variant_type_is_concrete
+g_variant_type_is_definite
g_variant_type_is_container
g_variant_type_is_basic
g_variant_type_is_maybe
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index c6f2456..c6f760d 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -1892,10 +1892,10 @@ typedecl_parse (TokenStream *stream,
type = g_variant_type_new (token + 1);
- if (!g_variant_type_is_concrete (type))
+ if (!g_variant_type_is_definite (type))
{
set_error (&stream->error, stream->stream, stream->stream,
- "Type declarations must be concrete");
+ "Type declarations must be definite");
g_variant_type_free (type);
g_free (token);
diff --git a/glib/gvariant-serialiser.c b/glib/gvariant-serialiser.c
index 8747b6e..259554d 100644
--- a/glib/gvariant-serialiser.c
+++ b/glib/gvariant-serialiser.c
@@ -267,7 +267,7 @@ g_variant_serialised_get_child (GVariantSerialised container,
{
const GVariantType *type = G_VARIANT_TYPE (str);
- if (g_variant_type_is_concrete (type))
+ if (g_variant_type_is_definite (type))
child.type = g_variant_type_info_get (type);
}
@@ -964,7 +964,7 @@ g_variant_serialised_is_normal (GVariantSerialised value)
{
const GVariantType *type = G_VARIANT_TYPE (str);
- if (g_variant_type_is_concrete (type))
+ if (g_variant_type_is_definite (type))
child.type = g_variant_type_info_get (type);
}
diff --git a/glib/gvariant-util.c b/glib/gvariant-util.c
index 6bee4f1..f6e88b7 100644
--- a/glib/gvariant-util.c
+++ b/glib/gvariant-util.c
@@ -479,7 +479,7 @@ g_variant_new_signature (const gchar *string)
* should ensure that a string is a valid DBus object path before
* passing it to g_variant_new_signature().
*
- * DBus type signatures consist of zero or more concrete #GVariantType
+ * DBus type signatures consist of zero or more definite #GVariantType
* strings in sequence.
**/
gboolean
@@ -489,7 +489,7 @@ g_variant_is_signature (const gchar *string)
g_return_val_if_fail (string != NULL, FALSE);
- /* make sure no non-concrete characters appear */
+ /* make sure no non-definite characters appear */
first_invalid = strspn (string, "ybnqihuxtdvmasog(){}");
if (string[first_invalid])
return FALSE;
@@ -893,7 +893,7 @@ struct _GVariantBuilder
GVariantClass container_class;
GVariantType *type;
const GVariantType *expected;
- /* expected2 is always concrete. it is set if adding a second
+ /* expected2 is always definite. it is set if adding a second
* element to an array (or open sub-builder thereof). it is
* required to ensure the following works correctly:
*
@@ -1218,7 +1218,7 @@ g_variant_builder_end (GVariantBuilder *builder)
g_variant_builder_resize (builder, builder->offset);
- if (g_variant_type_is_concrete (builder->type))
+ if (g_variant_type_is_definite (builder->type))
{
my_type = g_variant_type_copy (builder->type);
}
@@ -1302,8 +1302,8 @@ g_variant_builder_end (GVariantBuilder *builder)
* ensures that 2 items were added.
*
* This function also checks that array and maybe builders that were
- * created without concrete type information contain at least one item
- * (without which it would be impossible to infer the concrete type).
+ * created without definite type information contain at least one item
+ * (without which it would be impossible to infer the definite type).
*
* If some sort of error (either too few items were added or type
* inference is not possible) prevents the builder from being ended
@@ -1339,7 +1339,7 @@ g_variant_builder_check_end (GVariantBuilder *builder,
return FALSE;
}
- if (!g_variant_type_is_concrete (builder->type) &&
+ if (!g_variant_type_is_definite (builder->type) &&
(builder->container_class == G_VARIANT_CLASS_MAYBE ||
builder->container_class == G_VARIANT_CLASS_ARRAY) &&
builder->offset == 0)
@@ -1370,7 +1370,7 @@ g_variant_builder_check_end (GVariantBuilder *builder,
*
* It is an error to call this function with an invalid @tclass
* (including %G_VARIANT_CLASS_INVALID) or a class that's not the
- * smallest class for some concrete type (for example,
+ * smallest class for some definite type (for example,
* %G_VARIANT_CLASS_ALL).
*
* If @type is non-%NULL this function first checks that it is a
@@ -1379,14 +1379,14 @@ g_variant_builder_check_end (GVariantBuilder *builder,
*
* The function then checks if any child of class @tclass (and type
* @type, if given) would be suitable for adding to the builder. If
- * @type is non-%NULL and is non-concrete then all concrete types
+ * @type is non-%NULL and is non-definite then all definite types
* matching @type must be suitable for adding (ie: @type must be equal
* to or less general than the type expected by the builder).
*
* In the case of an array that already has at least one item in it,
* this function performs an additional check to ensure that @tclass
* and @type match the items already in the array. @type, if given,
- * need not be concrete in order for this check to pass.
+ * need not be definite in order for this check to pass.
*
* Errors are flagged in the event that the builder contains too many
* items or the addition would cause a type error.
diff --git a/glib/gvariant-valist.c b/glib/gvariant-valist.c
index c2900a1..91e409b 100644
--- a/glib/gvariant-valist.c
+++ b/glib/gvariant-valist.c
@@ -322,7 +322,7 @@ g_variant_valist_new (const gchar **format_string,
type = g_variant_format_string_scan_type (*format_string,
NULL, format_string);
- g_assert (g_variant_type_is_concrete (type));
+ g_assert (g_variant_type_is_definite (type));
value = g_variant_load_fixed (type, ptr, n_items);
g_variant_type_free (type);
@@ -394,7 +394,7 @@ g_variant_valist_new (const gchar **format_string,
type = g_variant_format_string_scan_type (string,
NULL, NULL);
- g_assert (g_variant_type_is_concrete (type));
+ g_assert (g_variant_type_is_definite (type));
if (g_variant_type_is_array (type))
n_items = va_arg (*app, gsize);
@@ -898,7 +898,7 @@ g_variant_valist_get (GVariant *value,
*
* The type of the created instance and the arguments that are
* expected by this function are determined by @format_string. In the
- * most simple case, @format_string is exactly equal to a concrete
+ * most simple case, @format_string is exactly equal to a definite
* #GVariantType type string and the result is of that type. All
* exceptions to this case are explicitly mentioned below.
*
@@ -1157,7 +1157,7 @@ g_variant_new_va (gpointer must_be_null,
* an incompatible type.
*
* In the most simple case, @format_string is exactly equal to a
- * concrete #GVariantType type string and @value must have that type.
+ * definite #GVariantType type string and @value must have that type.
* All exceptions to this case are explicitly mentioned below.
*
* The arguments that this function collects are determined by
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index c162273..3c76e1d 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -27,67 +27,46 @@
/**
* SECTION: gvarianttype
- * @title: GVariantType
- * @short_description: a variant type system
- * @see_also: GVariantType
- *
- * A #GVariantType represents the type of a #GVariant instance.
- **/
-
-/**
- * GVariantType:
- *
- * An opaque type representing either the type of a #GVariant instance
- * or a pattern that could match other types.
- *
- * Each #GVariantType has a corresponding type string. The grammar
- * generating all valid type strings is:
- *
- * <programlisting>
- * type = base | 'a' type | 'm' type | 'v' | '*'
- * | 'r' | '{' + base + type + '}' | '(' + types + ')'
- *
- * base = 'b' | 'y' | 'n' | 'q' | 'i' | 'u' | 'x'
- * | 't' | 'd' | 's' | 'o' | 'g' | 'h' | '?'
- *
- * types = '' | type + types
- * </programlisting>
- *
- * The types that have single character type strings are all defined
- * with their own constants (for example, %G_VARIANT_TYPE_BOOLEAN).
- *
- * The types that have type strings starting with 'a' are array types,
- * where the characters after the 'a' are the type string of the array
- * element type.
- *
- * The types that have type strings starting with 'm' are maybe types,
- * where the characters after the 'm' are the type string of the maybe
- * element type.
- *
- * The types that start with '{' and end with '}' are dictionary
- * entry types, where the first contained type string is the one
- * corresponding to the type of the key, and the second is the one
- * corresponding to the type of the value.
- *
- * The types that start with '(' and end with ')' are tuple types,
- * where each type string contained between the brackets corresponds
- * to an item type of that tuple type.
- *
- * Any type that has a type string that can be generated from 'base'
- * is in the #GVariantTypeClass %G_VARIANT_TYPE_CLASS_BASIC.
- *
- * Any type that has a type string that can be generated from 'type'
- * is in the class %G_VARIANT_TYPE_CLASS_ALL. This is all types.
- *
- * Each type is a member of at least one other #GVariantTypeClass.
- *
- * Note that, in reality, a #GVariantType is just a string pointer
- * cast to an opaque type. It is only valid to have a pointer of
- * this type, however, if you are sure that it is a valid type string.
- * Functions that take #GVariantType as parameters assume that the
- * string is well-formed. Also note that a #GVariantType is not
- * necessarily nul-terminated.
- **/
+ * @title: The GVariant type system
+ * @short_description: introduction to the GVariant type system
+ * @see_also: #GVariantType, #GVariant
+ *
+ * This section introduces the GVariant type system. It is based, in
+ * large part, on the DBus type system, with two major changes and some
+ * minor lifting of restrictions. The DBus specification, therefore,
+ * provides a significant amount information that is useful when working
+ * with GVariant.
+ *
+ * The first major change with respect to the DBus type system is the
+ * introduction of nullable types. Any type in GVariant can be
+ * converted to a nullable type, in which case, "null" becomes a valid
+ * value.
+ *
+ * The second major change is that the GVariant type system supports the
+ * concept of "indefinite types" -- types that are less specific than
+ * the normal types found in DBus. For example, it is possible to speak
+ * of "an array of any type" in GVariant, where the DBus type system
+ * would require you to speak of "an array of integers" or "an array of
+ * strings".
+ *
+ * Finally, all arbitrary restrictions relating to the complexity of
+ * types are lifted along with the restriction that dictionary entries
+ * may only appear nested inside of arrays.
+ *
+ * Just as in DBus, GVariant types are described with strings ("type
+ * strings"). Subject to the differences mentioned above, these strings
+ * are of the same form as those found in DBus. Note, however: DBus
+ * always works in terms of messages and therefore individual type
+ * strings appear nowhere in its interface. Instead, "signatures"
+ * are a concatenation of the strings of the type of each argument in a
+ * message. GVariant deals with single values directly so GVariant type
+ * strings always describe the type of exactly one value. This means
+ * that a DBus signature string is generally not a valid GVariant type
+ * string -- except in the case that it is the signature of a message
+ * containing exactly one argument.
+ *
+ * A detailed description of GVariant type strings is given here XXX.
+ */
/**
* G_VARIANT_TYPE:
@@ -95,7 +74,7 @@
*
* Converts a string to a const #GVariantType. Depending on the
* current debugging level, this function may perform a runtime check
- * to ensure that @string is valid.
+ * to ensure that @string is a valid GVariant type string.
*
* It is always a programmer error to use this macro with an invalid
* type string.
@@ -108,16 +87,16 @@
* @endptr: location to store the end pointer, or %NULL
* @returns: %TRUE if a valid type string was found
*
- * Scan for a single complete and valid #GVariantType type string in
- * @string. The memory pointed to by @limit (or bytes beyond it)
- * is never accessed.
+ * Scan for a single complete and valid GVariant type string in @string.
+ * The memory pointed to by @limit (or bytes beyond it) is never
+ * accessed.
*
- * If a valid type string is found, @endptr is updated to point
- * to the first character past the end of the string that was found
- * and %TRUE is returned.
+ * If a valid type string is found, @endptr is updated to point to the
+ * first character past the end of the string that was found and %TRUE
+ * is returned.
*
- * If there is no valid type string starting at @string, or if
- * the type string does not end before @limit then %FALSE is returned.
+ * If there is no valid type string starting at @string, or if the type
+ * string does not end before @limit then %FALSE is returned.
*
* For the simple case of checking if a string is a valid type string,
* see g_variant_type_string_is_valid().
@@ -150,7 +129,7 @@ g_variant_type_string_scan (const gchar *string,
break;
case 'm': case 'a':
- return g_variant_type_string_scan (string, limit, endptr); /* tcall */
+ return g_variant_type_string_scan (string, limit, endptr);
case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
case 'x': case 't': case 'd': case 's': case 'o': case 'g':
@@ -177,9 +156,9 @@ g_variant_type_string_scan (const gchar *string,
* @type_string: a pointer to any string
* @returns: %TRUE if @type_string is exactly one valid type string
*
- * Checks if @type_string is a valid #GVariantType type string. This
- * call is equivalent to calling g_variant_type_string_scan() and
- * confirming that the following character is a nul terminator.
+ * Checks if @type_string is a valid GVariant type string. This call is
+ * equivalent to calling g_variant_type_string_scan() and confirming
+ * that the following character is a nul terminator.
**/
gboolean
g_variant_type_string_is_valid (const gchar *type_string)
@@ -192,11 +171,13 @@ g_variant_type_string_is_valid (const gchar *type_string)
/**
* g_variant_type_free:
- * @type: a #GVariantType
+ * @type: a #GVariantType, or %NULL
*
* Frees a #GVariantType that was allocated with
* g_variant_type_copy(), g_variant_type_new() or one of the container
* type constructor functions.
+ *
+ * In the case that @type is %NULL, this function does nothing.
**/
void
g_variant_type_free (GVariantType *type)
@@ -209,8 +190,8 @@ g_variant_type_free (GVariantType *type)
* @type: a #GVariantType
* @returns: a new #GVariantType
*
- * Makes a copy of a #GVariantType. This copy must be freed using
- * g_variant_type_free().
+ * Makes a copy of a #GVariantType. It is appropriate to call
+ * g_variant_type_free() on the return value. @type may not be %NULL.
**/
GVariantType *
g_variant_type_copy (const GVariantType *type)
@@ -229,14 +210,15 @@ g_variant_type_copy (const GVariantType *type)
/**
* g_variant_type_new:
- * @type_string: a valid #GVariantType type string
+ * @type_string: a valid GVariant type string
* @returns: a new #GVariantType
*
* Creates a new #GVariantType corresponding to the type string given
- * by @type_string. This new type must be freed using
- * g_variant_type_free().
+ * by @type_string. It is appropriate to call g_variant_type_free() on
+ * the return value.
*
- * It is an error to call this function with an invalid type string.
+ * 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.
*/
GVariantType *
g_variant_type_new (const gchar *type_string)
@@ -265,7 +247,7 @@ g_variant_type_get_string_length (const GVariantType *type)
while (type_string[index] == 'a' || type_string[index] == 'm')
index++;
- if (type_string[index]== '(' || type_string[index] == '{')
+ if (type_string[index] == '(' || type_string[index] == '{')
brackets++;
else if (type_string[index] == ')' || type_string[index] == '}')
@@ -281,7 +263,7 @@ g_variant_type_get_string_length (const GVariantType *type)
/**
* g_variant_type_peek_string:
* @type: a #GVariantType
- * @returns: the corresponding type string (non-terminated)
+ * @returns: the corresponding type string (not nul-terminated)
*
* Returns the type string corresponding to the given @type. The
* result is not nul-terminated; in order to determine its length you
@@ -298,11 +280,11 @@ g_variant_type_peek_string (const GVariantType *type)
/**
* g_variant_type_dup_string:
* @type: a #GVariantType
- * @returns: the corresponding type string (must be freed)
+ * @returns: the corresponding type string
*
* Returns a newly-allocated copy of the type string corresponding to
- * @type. The return result is nul-terminated and must be freed using
- * g_free().
+ * @type. The returned string is nul-terminated. It is appropriate to
+ * call g_free() on the return value.
**/
gchar *
g_variant_type_dup_string (const GVariantType *type)
@@ -311,34 +293,28 @@ g_variant_type_dup_string (const GVariantType *type)
g_variant_type_get_string_length (type));
}
-const GVariantType *
-g_variant_type_check_string_ (const gchar *type_string)
-{
- g_assert (g_variant_type_string_is_valid (type_string));
-
- return (GVariantType *) type_string;
-}
-
/**
- * g_variant_type_is_concrete:
+ * g_variant_type_is_definite:
* @type: a #GVariantType
- * @returns: %TRUE if @type is concrete
+ * @returns: %TRUE if @type is definite
*
- * Determines if the given @type is a concrete (ie: non-wildcard)
- * type. A #GVariant instance may only have a concrete type.
+ * Determines if the given @type is definite (ie: not indefinite).
+ * A #GVariant instance may only have a definite type.
*
- * A type is concrete if its type string does not contain any wildcard
- * characters ('*', '?' or 'r').
+ * A type is definite if its type string does not contain any indefinite
+ * type characters ('*', '?', or 'r').
**/
gboolean
-g_variant_type_is_concrete (const GVariantType *type)
+g_variant_type_is_definite (const GVariantType *type)
{
const gchar *type_string = g_variant_type_peek_string (type);
gsize type_length = g_variant_type_get_string_length (type);
gsize i;
for (i = 0; i < type_length; i++)
- if (strchr ("*?r", type_string[i]))
+ if (type_string[i] == '*' ||
+ type_string[i] == '?' ||
+ type_string[i] == 'r')
return FALSE;
return TRUE;
@@ -354,9 +330,9 @@ g_variant_type_is_concrete (const GVariantType *type)
* Container types are any array, maybe, tuple, or dictionary
* entry types plus the variant type.
*
- * This function returns %TRUE for any wildcard type for which every
- * matching concrete type is a container. This does not include
- * %G_VARIANT_TYPE_ANY.
+ * This function returns %TRUE for any indefinite type for which every
+ * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
+ * example.
**/
gboolean
g_variant_type_is_container (const GVariantType *type)
@@ -390,7 +366,7 @@ g_variant_type_is_container (const GVariantType *type)
*
* Only a basic type may be used as the key of a dictionary entry.
*
- * This function returns %FALSE for all wildcard types except
+ * This function returns %FALSE for all indefinite types except
* %G_VARIANT_TYPE_BASIC.
**/
gboolean
@@ -421,18 +397,55 @@ g_variant_type_is_basic (const GVariantType *type)
}
}
+/**
+ * g_variant_type_is_maybe:
+ * @type: a #GVariantType
+ * @returns: %TRUE if @type is a maybe type
+ *
+ * Determines if the given @type is a maybe type. This is true if the
+ * type string for @type starts with an 'm'.
+ *
+ * This function returns %TRUE for any indefinite type for which every
+ * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
+ * example.
+ **/
gboolean
g_variant_type_is_maybe (const GVariantType *type)
{
return g_variant_type_peek_string (type)[0] == 'm';
}
+/**
+ * g_variant_type_is_array:
+ * @type: a #GVariantType
+ * @returns: %TRUE if @type is an array type
+ *
+ * Determines if the given @type is an array type. This is true if the
+ * type string for @type starts with an 'a'.
+ *
+ * This function returns %TRUE for any indefinite type for which every
+ * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
+ * example.
+ **/
gboolean
g_variant_type_is_array (const GVariantType *type)
{
return g_variant_type_peek_string (type)[0] == 'a';
}
+/**
+ * g_variant_type_is_tuple:
+ * @type: a #GVariantType
+ * @returns: %TRUE if @type is a tuple type
+ *
+ * Determines if the given @type is a tuple type. This is true if the
+ * 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
+ * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
+ * example.
+ **/
gboolean
g_variant_type_is_tuple (const GVariantType *type)
{
@@ -441,6 +454,18 @@ g_variant_type_is_tuple (const GVariantType *type)
return type_char == 'r' || type_char == '(';
}
+/**
+ * g_variant_type_is_dict_entry:
+ * @type: a #GVariantType
+ * @returns: %TRUE if @type is a dictionary entry type
+ *
+ * Determines if the given @type is a dictionary entry type. This is
+ * true if the type string for @type starts with a '{'.
+ *
+ * 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.
+ **/
gboolean
g_variant_type_is_dict_entry (const GVariantType *type)
{
@@ -480,10 +505,10 @@ g_variant_type_hash (gconstpointer type)
*
* Compares @type1 and @type2 for equality.
*
- * Only returns %TRUE if the types are exactly equal. Even if one
- * type is a wildcard type and the other matches it, false will be
- * returned if they are not exactly equal. If you want to check for
- * matching, use g_variant_type_matches().
+ * 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
+ * be returned if they are not exactly equal. If you want to check for
+ * subtypes, use g_variant_type_is_subtype_of().
*
* The argument types of @type1 and @type2 are only #gconstpointer to
* allow use with #GHashTable without function pointer casting. For
@@ -514,18 +539,14 @@ g_variant_type_equal (gconstpointer type1,
/**
* g_variant_type_is_subtype_of:
* @type: a #GVariantType
- * @pattern: a #GVariantType
- * @returns: %TRUE if @type matches @pattern
- *
- * Performs a pattern match between @type and @pattern.
+ * @supertype: a #GVariantType
+ * @returns: %TRUE if @type is a subtype of @supertype
*
- * This function returns %TRUE if @type can be reached by making
- * @pattern less general (ie: by replacing zero or more wildcard
- * characters in the type string of @pattern with matching type
- * strings that possibly contain wildcards themselves).
+ * Checks if @type is a subtype of @supertype.
*
- * This function defines a bounded join-semilattice over #GVariantType
- * for which %G_VARIANT_TYPE_ANY is top.
+ * This function returns %TRUE if @type is a subtype of @supertype. All
+ * types are considered to be subtypes of themselves. Aside from that,
+ * only indefinite types can have subtypes.
**/
gboolean
g_variant_type_is_subtype_of (const GVariantType *type,
@@ -585,13 +606,12 @@ g_variant_type_is_subtype_of (const GVariantType *type,
/**
* g_variant_type_element:
- * @type: a #GVariantType of class array or maybe
+ * @type: an array or maybe #GVariantType
* @returns: the element type of @type
*
* Determines the element type of an array or maybe type.
*
- * This function must be called with a type in one of the classes
- * %G_VARIANT_TYPE_CLASS_MAYBE or %G_VARIANT_TYPE_CLASS_ARRAY.
+ * This function may only be used with array or maybe types.
**/
const GVariantType *
g_variant_type_element (const GVariantType *type)
@@ -605,15 +625,14 @@ g_variant_type_element (const GVariantType *type)
/**
* g_variant_type_first:
- * @type: a #GVariantType of class tuple or dict entry
+ * @type: a tuple or dictionary entry #GVariantType
* @returns: the first item type of @type, or %NULL
*
* Determines the first item type of a tuple or dictionary entry
* type.
*
- * This function must be called with a type in one of the classes
- * %G_VARIANT_TYPE_CLASS_TUPLE or %G_VARIANT_TYPE_CLASS_DICT_ENTRY
- * but must not be called on the generic tuple type
+ * This function may only be used with tuple or dictionary entry types,
+ * but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE.
*
* In the case of a dictionary entry type, this returns the type of
@@ -639,21 +658,20 @@ g_variant_type_first (const GVariantType *type)
/**
* g_variant_type_next:
- * @type: a #GVariantType
+ * @type: a #GVariantType from a previous call
* @returns: the next #GVariantType after @type, or %NULL
*
* Determines the next item type of a tuple or dictionary entry
* type.
*
* @type must be the result of a previous call to
- * g_variant_type_first(). Together, these two functions provide an
- * iterator interface over tuple and dictioanry entry types.
+ * g_variant_type_first() or g_variant_type_next().
*
* If called on the key type of a dictionary entry then this call
- * returns the value type.
+ * returns the value type. If called on the value type of a dictionary
+ * entry then this call returns %NULL.
*
- * %NULL is returned when @type is the last item in a tuple or the
- * value type of a dictionary entry.
+ * For tuples, %NULL is returned when @type is the last item in a tuple.
**/
const GVariantType *
g_variant_type_next (const GVariantType *type)
@@ -670,15 +688,14 @@ g_variant_type_next (const GVariantType *type)
/**
* g_variant_type_n_items:
- * @type: a #GVariantType of class tuple or dict entry
+ * @type: a tuple or dictionary entry #GVariantType
* @returns: the number of items in @type
*
* Determines the number of items contained in a tuple or
* dictionary entry type.
*
- * This function must be called with a type in one of the classes
- * %G_VARIANT_TYPE_CLASS_TUPLE or %G_VARIANT_TYPE_CLASS_DICT_ENTRY
- * but must not be called on the generic tuple type
+ * This function may only be used with tuple or dictionary entry types,
+ * but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE.
*
* In the case of a dictionary entry type, this function will always
@@ -699,14 +716,14 @@ g_variant_type_n_items (const GVariantType *type)
/**
* g_variant_type_key:
- * @type: a #GVariantType of class dict entry
+ * @type: a dictionary entry #GVariantType
* @returns: the key type of the dictionary entry
*
* Determines the key type of a dictionary entry type.
*
- * This function must be called with a type in the class
- * %G_VARIANT_TYPE_CLASS_DICT_ENTRY. Other than that, this call is
- * exactly equivalent to g_variant_type_first().
+ * This function may only be used with a dictionary entry type. Other
+ * than the additional restriction, this call is equivalent to
+ * g_variant_type_first().
**/
const GVariantType *
g_variant_type_key (const GVariantType *type)
@@ -720,13 +737,12 @@ g_variant_type_key (const GVariantType *type)
/**
* g_variant_type_value:
- * @type: a #GVariantType of class dict entry
+ * @type: a dictionary entry #GVariantType
* @returns: the value type of the dictionary entry
*
* Determines the value type of a dictionary entry type.
*
- * This function must be called with a type in the class
- * %G_VARIANT_TYPE_CLASS_DICT_ENTRY.
+ * This function may only be used with a dictionary entry type.
**/
const GVariantType *
g_variant_type_value (const GVariantType *type)
@@ -742,17 +758,20 @@ g_variant_type_value (const GVariantType *type)
* g_variant_type_new_tuple:
* @items: an array of #GVariantTypes, one for each item
* @length: the length of @items
- * @returns: a new #GVariantType
+ * @returns: a new tuple #GVariantType
*
* Constructs a new tuple type, from @items.
*
- * The result of this function must be freed with a call to
- * g_variant_type_free().
+ * It is appropriate to call g_variant_type_free() on the return value.
**/
static GVariantType *
g_variant_type_new_tuple_slow (const GVariantType * const *items,
gint length)
{
+ /* the "slow" version is needed in case the static buffer of 1024
+ * bytes is exceeded when running the normal version. this will
+ * happen only in truly insane code, so it can be slow.
+ */
GString *string;
gsize i;
@@ -808,7 +827,7 @@ g_variant_type_new_tuple (const GVariantType * const *items,
g_assert (offset < sizeof buffer);
buffer[offset++] = ')';
- return g_memdup (buffer, offset);
+ return (GVariantType *) g_memdup (buffer, offset);
}
/**
@@ -819,8 +838,7 @@ g_variant_type_new_tuple (const GVariantType * const *items,
* Constructs the type corresponding to an array of elements of the
* type @type.
*
- * The result of this function must be freed with a call to
- * g_variant_type_free().
+ * It is appropriate to call g_variant_type_free() on the return value.
**/
GVariantType *
g_variant_type_new_array (const GVariantType *element)
@@ -847,10 +865,9 @@ g_variant_type_new_array (const GVariantType *element)
* @returns: a new maybe #GVariantType
*
* Constructs the type corresponding to a maybe instance containing
- * type @type.
+ * type @type or Nothing.
*
- * The result of this function must be freed with a call to
- * g_variant_type_free().
+ * It is appropriate to call g_variant_type_free() on the return value.
**/
GVariantType *
g_variant_type_new_maybe (const GVariantType *element)
@@ -880,8 +897,7 @@ g_variant_type_new_maybe (const GVariantType *element)
* Constructs the type corresponding to a dictionary entry with a key
* of type @key and a value of type @value.
*
- * The result of this function must be freed with a call to
- * g_variant_type_free().
+ * It is appropriate to call g_variant_type_free() on the return value.
**/
GVariantType *
g_variant_type_new_dict_entry (const GVariantType *key,
diff --git a/glib/gvarianttype.h b/glib/gvarianttype.h
index 11d0222..c34e049 100644
--- a/glib/gvarianttype.h
+++ b/glib/gvarianttype.h
@@ -51,7 +51,7 @@ typedef struct _GVariantType GVariantType;
* G_VARIANT_TYPE_UINT16:
*
* 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")
@@ -112,6 +112,10 @@ typedef struct _GVariantType GVariantType;
* The type of a DBus object reference. These are strings of a
* specific format used to identify objects at a given destination on
* the bus.
+ *
+ * If you are not interacting with DBus, then there is no reason to make
+ * use of this type. If you are, then the DBus specification contains a
+ * precise description of valid object paths.
**/
#define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o")
@@ -121,11 +125,9 @@ typedef struct _GVariantType GVariantType;
* The type of a DBus type signature. These are strings of a specific
* format used as type signatures for DBus methods and messages.
*
- * Any valid concrete #GVariantType signature string is a valid DBus
- * type signature. In addition, a concatenation of any number of
- * valid concrete #GVariantType signature strings is also a valid DBus
- * type signature, subject to the restriction that DBus signature
- * strings have a maximum length of 255 characters.
+ * If you are not interacting with DBus, then there is no reason to make
+ * use of this type. If you are, then the DBus specification contains a
+ * precise description of valid signature strings.
**/
#define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g")
@@ -143,6 +145,9 @@ typedef struct _GVariantType GVariantType;
* The type of a 32bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside
* a DBus message.
+ *
+ * If you are not interacting with DBus, then there is no reason to make
+ * use of this type.
**/
#define G_VARIANT_TYPE_HANDLE ((const GVariantType *) "h")
@@ -157,49 +162,55 @@ typedef struct _GVariantType GVariantType;
/**
* G_VARIANT_TYPE_ANY:
*
- * The wildcard type. Matches any type.
+ * An indefinite type that is a supertype of every type (including
+ * itself).
**/
#define G_VARIANT_TYPE_ANY ((const GVariantType *) "*")
/**
* G_VARIANT_TYPE_BASIC:
*
- * A wildcard type matching any basic type.
+ * An indefinite type that is a supertype of every basic (ie:
+ * non-container) type.
**/
#define G_VARIANT_TYPE_BASIC ((const GVariantType *) "?")
/**
* G_VARIANT_TYPE_MAYBE:
*
- * A wildcard type matching any maybe type.
+ * An indefinite type that is a supertype of every maybe type.
**/
#define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*")
/**
* G_VARIANT_TYPE_ARRAY:
*
- * A wildcard type matching any array type.
+ * An indefinite type that is a supertype of every array type.
**/
#define G_VARIANT_TYPE_ARRAY ((const GVariantType *) "a*")
/**
* G_VARIANT_TYPE_TUPLE:
*
- * A wildcard type matching any tuple type.
+ * An indefinite type that is a supertype of every tuple type,
+ * regardless of the number of items in the tuple.
**/
#define G_VARIANT_TYPE_TUPLE ((const GVariantType *) "r")
/**
* G_VARIANT_TYPE_DICT_ENTRY:
*
- * A wildcard type matching any dictionary entry type.
+ * An indefinite type that is a supertype of every dictionary entry
+ * type.
**/
#define G_VARIANT_TYPE_DICT_ENTRY ((const GVariantType *) "{?*}")
/**
* G_VARIANT_TYPE_DICTIONARY:
*
- * A wildcard type matching any 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
+ * dictionary entry type.
**/
#define G_VARIANT_TYPE_DICTIONARY ((const GVariantType *) "a{?*}")
@@ -222,7 +233,7 @@ const gchar * g_variant_type_peek_string (const G
gchar * g_variant_type_dup_string (const GVariantType *type);
/* classification */
-gboolean g_variant_type_is_concrete (const GVariantType *type);
+gboolean g_variant_type_is_definite (const GVariantType *type);
gboolean g_variant_type_is_container (const GVariantType *type);
gboolean g_variant_type_is_basic (const GVariantType *type);
gboolean g_variant_type_is_maybe (const GVariantType *type);
@@ -235,7 +246,7 @@ guint g_variant_type_hash (gconstp
gboolean g_variant_type_equal (gconstpointer type1,
gconstpointer type2);
-/* matching */
+/* subtypes */
gboolean g_variant_type_is_subtype_of (const GVariantType *type,
const GVariantType *supertype);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
