* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Author: Ryan Lortie <desrt@desrt.ca>
*/
* @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 D-Bus type system, with two major changes and some minor
- * lifting of restrictions. The <ulink
- * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
- * specification</ulink>, therefore, provides a significant amount of
+ * This section introduces the GVariant type system. It is based, in
+ * large part, on the D-Bus type system, with two major changes and
+ * some minor lifting of restrictions. The
+ * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
+ * therefore, provides a significant amount of
* information that is useful when working with GVariant.
*
* The first major change with respect to the D-Bus 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. Maybe types have been added by introducing the
- * character "<literal>m</literal>" to type strings.
+ * character "m" 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
* of "an array of any type" in GVariant, where the D-Bus type system
* would require you to speak of "an array of integers" or "an array of
* strings". Indefinite types have been added by introducing the
- * characters "<literal>*</literal>", "<literal>?</literal>" and
- * "<literal>r</literal>" to type strings.
+ * characters "*", "?" and "r" to type strings.
*
* Finally, all arbitrary restrictions relating to the complexity of
* types are lifted along with the restriction that dictionary entries
* 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'>
- * <title>GVariant Type Strings</title>
- * <para>
- * A GVariant type string can be any of the following:
- * </para>
- * <itemizedlist>
- * <listitem>
- * <para>
- * any basic type string (listed below)
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * "<literal>v</literal>", "<literal>r</literal>" or
- * "<literal>*</literal>"
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * one of the characters '<literal>a</literal>' or
- * '<literal>m</literal>', followed by another type string
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * the character '<literal>(</literal>', followed by a concatenation
- * of zero or more other type strings, followed by the character
- * '<literal>)</literal>'
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * the character '<literal>{</literal>', followed by a basic type
- * string (see below), followed by another type string, followed by
- * the character '<literal>}</literal>'
- * </para>
- * </listitem>
- * </itemizedlist>
- * <para>
- * A basic type string describes a basic type (as per
- * g_variant_type_is_basic()) and is always a single
- * character in length. The valid basic type strings are
- * "<literal>b</literal>", "<literal>y</literal>",
- * "<literal>n</literal>", "<literal>q</literal>",
- * "<literal>i</literal>", "<literal>u</literal>",
- * "<literal>x</literal>", "<literal>t</literal>",
- * "<literal>h</literal>", "<literal>d</literal>",
- * "<literal>s</literal>", "<literal>o</literal>",
- * "<literal>g</literal>" and "<literal>?</literal>".
- * </para>
- * <para>
- * The above definition is recursive to arbitrary depth.
- * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
- * are both valid type strings, as is
- * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
- * </para>
- * <para>
- * The meaning of each of the characters is as follows:
- * </para>
- * <informaltable>
- * <tgroup cols='2'>
- * <tbody>
- * <row>
- * <entry>
- * <para>
- * <emphasis role='strong'>Character</emphasis>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * <emphasis role='strong'>Meaning</emphasis>
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>b</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>y</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BYTE; a byte.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>n</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>q</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>i</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>u</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>x</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>t</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>h</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
- * value that, by convention, is used as an index into an array
- * of file descriptors that are sent alongside a D-Bus message.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>d</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
- * floating point value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>s</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_STRING; a string.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>o</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
- * the form of a D-Bus object path.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>g</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_STRING; a string in the
- * form of a D-Bus type signature.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>?</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
- * that is a supertype of any of the basic types.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>v</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_VARIANT; a container type
- * that contain any other type of value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>a</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used as a prefix on another type string to mean an array of
- * that type; the type string "<literal>ai</literal>", for
- * example, is the type of an array of 32 bit signed integers.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>m</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used as a prefix on another type string to mean a "maybe", or
- * "nullable", version of that type; the type string
- * "<literal>ms</literal>", for example, is the type of a value
- * that maybe contains a string, or maybe contains nothing.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>()</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used to enclose zero or more other concatenated type strings
- * to create a tuple type; the type string
- * "<literal>(is)</literal>", for example, is the type of a pair
- * of an integer and a string.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>r</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
- * that is a supertype of any tuple type, regardless of the
- * number of items.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>{}</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used to enclose a basic type string concatenated with another
- * type string to create a dictionary entry type, which usually
- * appears inside of an array to form a dictionary; the type
- * string "<literal>a{sd}</literal>", for example, is the type of
- * a dictionary that maps strings to double precision floating
- * point values.
- * </para>
- * <para>
- * The first type (the basic type) is the key type and the second
- * type is the value type. The reason that the first type is
- * restricted to being a basic type is so that it can easily be
- * hashed.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>*</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
- * that is a supertype of all types. Note that, as with all type
- * strings, this character represents exactly one type. It
- * cannot be used inside of tuples to mean "any number of items".
- * </para>
- * </entry>
- * </row>
- * </tbody>
- * </tgroup>
- * </informaltable>
- * <para>
- * Any type string of a container that contains an indefinite type is,
- * itself, an indefinite type. For example, the type string
- * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
- * an indefinite type that is a supertype of every array type.
- * "<literal>(*s)</literal>" is a supertype of all tuples that
- * contain exactly two items where the second item is a string.
- * </para>
- * <para>
- * "<literal>a{?*}</literal>" is an indefinite type that is a
- * supertype of all arrays containing dictionary entries where the key
- * is any basic type and the value is any type at all. This is, by
- * definition, a dictionary, so this type string corresponds to
- * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that
- * the key of a dictionary entry must be a basic type,
- * "<literal>{**}</literal>" is not a valid type string.
- * </para>
- * </refsect2>
+ * ## GVariant Type Strings
+ *
+ * A GVariant type string can be any of the following:
+ *
+ * - any basic type string (listed below)
+ *
+ * - "v", "r" or "*"
+ *
+ * - one of the characters 'a' or 'm', followed by another type string
+ *
+ * - the character '(', followed by a concatenation of zero or more other
+ * type strings, followed by the character ')'
+ *
+ * - the character '{', followed by a basic type string (see below),
+ * followed by another type string, followed by the character '}'
+ *
+ * A basic type string describes a basic type (as per
+ * g_variant_type_is_basic()) and is always a single character in length.
+ * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
+ * "h", "f", "d", "s", "o", "g" and "?".
+ *
+ * The above definition is recursive to arbitrary depth. "aaaaai" and
+ * "(ui(nq((y)))s)" are both valid type strings, as is
+ * "a(aa(ui)(qna{ya(yd)}))".
+ *
+ * The meaning of each of the characters is as follows:
+ * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
+ * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
+ * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
+ * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
+ * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
+ * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
+ * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
+ * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
+ * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
+ * that, by convention, is used as an index into an array of file
+ * descriptors that are sent alongside a D-Bus message.
+ * - `f`: the type string of %G_VARIANT_TYPE_FLOAT; a single precision
+ * floating point value.
+ * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
+ * floating point value.
+ * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
+ * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
+ * of a D-Bus object path.
+ * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of
+ * a D-Bus type signature.
+ * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
+ * is a supertype of any of the basic types.
+ * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
+ * contain any other type of value.
+ * - `a`: used as a prefix on another type string to mean an array of that
+ * type; the type string "ai", for example, is the type of an array of
+ * signed 32-bit integers.
+ * - `m`: used as a prefix on another type string to mean a "maybe", or
+ * "nullable", version of that type; the type string "ms", for example,
+ * is the type of a value that maybe contains a string, or maybe contains
+ * nothing.
+ * - `()`: used to enclose zero or more other concatenated type strings to
+ * create a tuple type; the type string "(is)", for example, is the type of
+ * a pair of an integer and a string.
+ * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
+ * a supertype of any tuple type, regardless of the number of items.
+ * - `{}`: used to enclose a basic type string concatenated with another type
+ * string to create a dictionary entry type, which usually appears inside of
+ * an array to form a dictionary; the type string "a{sd}", for example, is
+ * the type of a dictionary that maps strings to double precision floating
+ * point values.
+ *
+ * The first type (the basic type) is the key type and the second type is
+ * the value type. The reason that the first type is restricted to being a
+ * basic type is so that it can easily be hashed.
+ * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
+ * a supertype of all types. Note that, as with all type strings, this
+ * character represents exactly one type. It cannot be used inside of tuples
+ * to mean "any number of items".
+ *
+ * Any type string of a container that contains an indefinite type is,
+ * itself, an indefinite type. For example, the type string "a*"
+ * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
+ * that is a supertype of every array type. "(*s)" is a supertype
+ * of all tuples that contain exactly two items where the second
+ * item is a string.
+ *
+ * "a{?*}" is an indefinite type that is a supertype of all arrays
+ * containing dictionary entries where the key is any basic type and
+ * the value is any type at all. This is, by definition, a dictionary,
+ * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
+ * that, due to the restriction that the key of a dictionary entry must
+ * be a basic type, "{**}" is not a valid type string.
*/
static gboolean
g_variant_type_check (const GVariantType *type)
{
- const gchar *type_string;
-
if (type == NULL)
return FALSE;
- type_string = (const gchar *) type;
-#ifndef G_DISABLE_CHECKS
- return g_variant_type_string_scan (type_string, NULL, NULL);
+#if 0
+ return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
#else
return TRUE;
#endif
case '{':
if (string == limit || *string == '\0' || /* { */
- !strchr ("bynqihuxtdsog?", *string++) || /* key */
+ !strchr ("bynqihuxtfdsog?", *string++) || /* key */
!g_variant_type_string_scan (string, limit, &string) || /* value */
string == limit || *string++ != '}') /* } */
return FALSE;
case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
case 'x': case 't': case 'd': case 's': case 'o': case 'g':
- case 'v': case 'r': case '*': case '?': case 'h':
+ case 'v': case 'r': case '*': case '?': case 'h': case 'f':
break;
default:
*
* Determines if the given @type is a basic type.
*
- * Basic types are booleans, bytes, integers, doubles, strings, object
- * paths and signatures.
+ * Basic types are booleans, bytes, integers, floats, doubles, strings,
+ * object paths and signatures.
*
* Only a basic type may be used as the key of a dictionary entry.
*
case 'u':
case 't':
case 'x':
+ case 'f':
case 'd':
case 's':
case 'o':
projects / platform / upstream / glib.git / blobdiff