[glib/gvariant: 1/11] improve documentation of indefinite types
- From: Ryan Lortie <ryanl src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [glib/gvariant: 1/11] improve documentation of indefinite types
- Date: Mon, 25 Jan 2010 16:58:06 +0000 (UTC)
commit a9669308ad6be1d95ad7c5966936736a489c279d
Author: Ryan Lortie <desrt desrt ca>
Date: Fri Jan 22 13:52:04 2010 -0500
improve documentation of indefinite types
glib/gvarianttype.c | 33 ++++++++++++++++++++++++++++++---
1 files changed, 30 insertions(+), 3 deletions(-)
---
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index eae42a0..ee81f63 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -41,14 +41,17 @@
* The first major change with respect to the DBus type system is the
* introduction of maybe (or "nullable") types. Any type in GVariant can be
* converted to a maybe type, in which case, "nothing" (or "null") becomes a
- * valid value.
+ * valid value. Maybe types have been added by introducing the
+ * character "<literal>m</literal>" to type strings.
*
* 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".
+ * strings". Indefinite types have been added by introducing the
+ * characters "<literal>*</literal>", "<literal>?</literal>" and
+ * "<literal>r</literal>" to type strings.
*
* Finally, all arbitrary restrictions relating to the complexity of
* types are lifted along with the restriction that dictionary entries
@@ -66,6 +69,25 @@
* string -- except in the case that it is the signature of a message
* containing exactly one argument.
*
+ * An indefinite type is similar in spirit to what may be called an
+ * abstract type in other type systems. No value can exist that has an
+ * indefinite type as its type, but values can exist that have types
+ * that are subtypes of indefinite types. That is to say,
+ * g_variant_get_type() will never return an indefinite type, but
+ * calling g_variant_is_a() with an indefinite type may return %TRUE.
+ * For example, you can not have a value that represents "an array of no
+ * particular type", but you can have an "array of integers" which
+ * certainly matches the type of "an array of no particular type", since
+ * "array of integers" is a subtype of "array of no particular type".
+ *
+ * This is similar to how instances of abstract classes may not
+ * directly exist in other type systems, but instances of their
+ * non-abstract subtypes may. For example, in GTK, no object that has
+ * the type of #GtkBin can exist (since #GtkBin is an abstract class),
+ * but a #GtkWindow can certainly be instantiated, and you would say
+ * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
+ * #GtkBin).
+ *
* A detailed description of GVariant type strings is given here:
*
* <refsect2 id='gvariant-typestrings'>
@@ -685,10 +707,15 @@ g_variant_type_dup_string (const GVariantType *type)
* @returns: %TRUE if @type is definite
*
* Determines if the given @type is definite (ie: not indefinite).
- * A #GVariant instance may only have a definite type.
*
* A type is definite if its type string does not contain any indefinite
* type characters ('*', '?', or 'r').
+ *
+ * A #GVariant instance may not have an indefinite type, so calling
+ * this function on the result of g_variant_get_type() will always
+ * result in %TRUE being returned. Calling this function on an
+ * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
+ * %FALSE being returned.
**/
gboolean
g_variant_type_is_definite (const GVariantType *type)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]