2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2009, 2010 Codethink Limited
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the licence, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Ryan Lortie <desrt@desrt.ca>
23 #include "gvarianttype.h"
25 #include <glib/gtestutils.h>
32 * SECTION: gvarianttype
33 * @title: GVariantType
34 * @short_description: introduction to the GVariant type system
35 * @see_also: #GVariantType, #GVariant
37 * This section introduces the GVariant type system. It is based, in
38 * large part, on the DBus type system, with two major changes and some minor
39 * lifting of restrictions. The <ulink
40 * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
41 * specification</ulink>, therefore, provides a significant amount of
42 * information that is useful when working with GVariant.
44 * The first major change with respect to the DBus type system is the
45 * introduction of maybe (or "nullable") types. Any type in GVariant can be
46 * converted to a maybe type, in which case, "nothing" (or "null") becomes a
47 * valid value. Maybe types have been added by introducing the
48 * character "<literal>m</literal>" to type strings.
50 * The second major change is that the GVariant type system supports the
51 * concept of "indefinite types" -- types that are less specific than
52 * the normal types found in DBus. For example, it is possible to speak
53 * of "an array of any type" in GVariant, where the DBus type system
54 * would require you to speak of "an array of integers" or "an array of
55 * strings". Indefinite types have been added by introducing the
56 * characters "<literal>*</literal>", "<literal>?</literal>" and
57 * "<literal>r</literal>" to type strings.
59 * Finally, all arbitrary restrictions relating to the complexity of
60 * types are lifted along with the restriction that dictionary entries
61 * may only appear nested inside of arrays.
63 * Just as in DBus, GVariant types are described with strings ("type
64 * strings"). Subject to the differences mentioned above, these strings
65 * are of the same form as those found in DBus. Note, however: DBus
66 * always works in terms of messages and therefore individual type
67 * strings appear nowhere in its interface. Instead, "signatures"
68 * are a concatenation of the strings of the type of each argument in a
69 * message. GVariant deals with single values directly so GVariant type
70 * strings always describe the type of exactly one value. This means
71 * that a DBus signature string is generally not a valid GVariant type
72 * string -- except in the case that it is the signature of a message
73 * containing exactly one argument.
75 * An indefinite type is similar in spirit to what may be called an
76 * abstract type in other type systems. No value can exist that has an
77 * indefinite type as its type, but values can exist that have types
78 * that are subtypes of indefinite types. That is to say,
79 * g_variant_get_type() will never return an indefinite type, but
80 * calling g_variant_is_a() with an indefinite type may return %TRUE.
81 * For example, you can not have a value that represents "an array of no
82 * particular type", but you can have an "array of integers" which
83 * certainly matches the type of "an array of no particular type", since
84 * "array of integers" is a subtype of "array of no particular type".
86 * This is similar to how instances of abstract classes may not
87 * directly exist in other type systems, but instances of their
88 * non-abstract subtypes may. For example, in GTK, no object that has
89 * the type of #GtkBin can exist (since #GtkBin is an abstract class),
90 * but a #GtkWindow can certainly be instantiated, and you would say
91 * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
94 * A detailed description of GVariant type strings is given here:
96 * <refsect2 id='gvariant-typestrings'>
97 * <title>GVariant Type Strings</title>
99 * A GVariant type string can be any of the following:
104 * any basic type string (listed below)
109 * "<literal>v</literal>", "<literal>r</literal>" or
110 * "<literal>*</literal>"
115 * one of the characters '<literal>a</literal>' or
116 * '<literal>m</literal>', followed by another type string
121 * the character '<literal>(</literal>', followed by a concatenation
122 * of zero or more other type strings, followed by the character
123 * '<literal>)</literal>'
128 * the character '<literal>{</literal>', followed by a basic type
129 * string (see below), followed by another type string, followed by
130 * the character '<literal>}</literal>'
135 * A basic type string describes a basic type (as per
136 * g_variant_type_is_basic()) and is always a single
137 * character in length. The valid basic type strings are
138 * "<literal>b</literal>", "<literal>y</literal>",
139 * "<literal>n</literal>", "<literal>q</literal>",
140 * "<literal>i</literal>", "<literal>u</literal>",
141 * "<literal>x</literal>", "<literal>t</literal>",
142 * "<literal>h</literal>", "<literal>d</literal>",
143 * "<literal>s</literal>", "<literal>o</literal>",
144 * "<literal>g</literal>" and "<literal>?</literal>".
147 * The above definition is recursive to arbitrary depth.
148 * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
149 * are both valid type strings, as is
150 * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
153 * The meaning of each of the characters is as follows:
161 * <emphasis role='strong'>Character</emphasis>
166 * <emphasis role='strong'>Meaning</emphasis>
173 * <literal>b</literal>
178 * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
185 * <literal>y</literal>
190 * the type string of %G_VARIANT_TYPE_BYTE; a byte.
197 * <literal>n</literal>
202 * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
210 * <literal>q</literal>
215 * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
223 * <literal>i</literal>
228 * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
236 * <literal>u</literal>
241 * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
249 * <literal>x</literal>
254 * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
262 * <literal>t</literal>
267 * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
275 * <literal>h</literal>
280 * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
281 * value that, by convention, is used as an index into an array
282 * of file descriptors that are sent alongside a DBus message.
289 * <literal>d</literal>
294 * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
295 * floating point value.
302 * <literal>s</literal>
307 * the type string of %G_VARIANT_TYPE_STRING; a string.
314 * <literal>o</literal>
319 * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
320 * the form of a DBus object path.
327 * <literal>g</literal>
332 * the type string of %G_VARIANT_TYPE_STRING; a string in the
333 * form of a DBus type signature.
340 * <literal>?</literal>
345 * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
346 * that is a supertype of any of the basic types.
353 * <literal>v</literal>
358 * the type string of %G_VARIANT_TYPE_VARIANT; a container type
359 * that contain any other type of value.
366 * <literal>a</literal>
371 * used as a prefix on another type string to mean an array of
372 * that type; the type string "<literal>ai</literal>", for
373 * example, is the type of an array of 32 bit signed integers.
380 * <literal>m</literal>
385 * used as a prefix on another type string to mean a "maybe", or
386 * "nullable", version of that type; the type string
387 * "<literal>ms</literal>", for example, is the type of a value
388 * that maybe contains a string, or maybe contains nothing.
395 * <literal>()</literal>
400 * used to enclose zero or more other concatenated type strings
401 * to create a tuple type; the type string
402 * "<literal>(is)</literal>", for example, is the type of a pair
403 * of an integer and a string.
410 * <literal>r</literal>
415 * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
416 * that is a supertype of any tuple type, regardless of the
424 * <literal>{}</literal>
429 * used to enclose a basic type string concatenated with another
430 * type string to create a dictionary entry type, which usually
431 * appears inside of an array to form a dictionary; the type
432 * string "<literal>a{sd}</literal>", for example, is the type of
433 * a dictionary that maps strings to double precision floating
437 * The first type (the basic type) is the key type and the second
438 * type is the value type. The reason that the first type is
439 * restricted to being a basic type is so that it can easily be
447 * <literal>*</literal>
452 * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
453 * that is a supertype of all types. Note that, as with all type
454 * strings, this character represents exactly one type. It
455 * cannot be used inside of tuples to mean "any number of items".
463 * Any type string of a container that contains an indefinite type is,
464 * itself, an indefinite type. For example, the type string
465 * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
466 * an indefinite type that is a supertype of every array type.
467 * "<literal>(*s)</literal>" is a supertype of all tuples that
468 * contain exactly two items where the second item is a string.
471 * "<literal>a{?*}</literal>" is an indefinite type that is a
472 * supertype of all arrays containing dictionary entries where the key
473 * is any basic type and the value is any type at all. This is, by
474 * definition, a dictionary, so this type string corresponds to
475 * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that
476 * the key of a dictionary entry must be a basic type,
477 * "<literal>{**}</literal>" is not a valid type string.
485 * A type in the GVariant type system.
487 * Two types may not be compared by value; use g_variant_type_equal() or
488 * g_variant_type_is_subtype(). May be copied using
489 * g_variant_type_copy() and freed using g_variant_type_free().
494 * @type_string: a well-formed #GVariantType type string
496 * Converts a string to a const #GVariantType. Depending on the
497 * current debugging level, this function may perform a runtime check
498 * to ensure that @string is a valid GVariant type string.
500 * It is always a programmer error to use this macro with an invalid
507 g_variant_type_check (const GVariantType *type)
509 const gchar *type_string;
514 type_string = (const gchar *) type;
515 #ifndef G_DISABLE_CHECKS
516 return g_variant_type_string_scan (type_string, NULL, NULL);
523 * g_variant_type_string_scan:
524 * @string: a pointer to any string
525 * @limit: the end of @string, or %NULL
526 * @endptr: location to store the end pointer, or %NULL
527 * @returns: %TRUE if a valid type string was found
529 * Scan for a single complete and valid GVariant type string in @string.
530 * The memory pointed to by @limit (or bytes beyond it) is never
533 * If a valid type string is found, @endptr is updated to point to the
534 * first character past the end of the string that was found and %TRUE
537 * If there is no valid type string starting at @string, or if the type
538 * string does not end before @limit then %FALSE is returned.
540 * For the simple case of checking if a string is a valid type string,
541 * see g_variant_type_string_is_valid().
546 g_variant_type_string_scan (const gchar *string,
548 const gchar **endptr)
550 g_return_val_if_fail (string != NULL, FALSE);
552 if (string == limit || *string == '\0')
558 while (string == limit || *string != ')')
559 if (!g_variant_type_string_scan (string, limit, &string))
566 if (string == limit || *string == '\0' || /* { */
567 !strchr ("bynqihuxtdsog?", *string++) || /* key */
568 !g_variant_type_string_scan (string, limit, &string) || /* value */
569 string == limit || *string++ != '}') /* } */
575 return g_variant_type_string_scan (string, limit, endptr);
577 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
578 case 'x': case 't': case 'd': case 's': case 'o': case 'g':
579 case 'v': case 'r': case '*': case '?': case 'h':
593 * g_variant_type_string_is_valid:
594 * @type_string: a pointer to any string
595 * @returns: %TRUE if @type_string is exactly one valid type string
597 * Checks if @type_string is a valid GVariant type string. This call is
598 * equivalent to calling g_variant_type_string_scan() and confirming
599 * that the following character is a nul terminator.
604 g_variant_type_string_is_valid (const gchar *type_string)
608 g_return_val_if_fail (type_string != NULL, FALSE);
610 if (!g_variant_type_string_scan (type_string, NULL, &endptr))
613 return *endptr == '\0';
617 * g_variant_type_free:
618 * @type: a #GVariantType, or %NULL
620 * Frees a #GVariantType that was allocated with
621 * g_variant_type_copy(), g_variant_type_new() or one of the container
622 * type constructor functions.
624 * In the case that @type is %NULL, this function does nothing.
629 g_variant_type_free (GVariantType *type)
631 g_return_if_fail (type == NULL || g_variant_type_check (type));
637 * g_variant_type_copy:
638 * @type: a #GVariantType
639 * @returns: a new #GVariantType
641 * Makes a copy of a #GVariantType. It is appropriate to call
642 * g_variant_type_free() on the return value. @type may not be %NULL.
647 g_variant_type_copy (const GVariantType *type)
652 g_return_val_if_fail (g_variant_type_check (type), NULL);
654 length = g_variant_type_get_string_length (type);
655 new = g_malloc (length + 1);
657 memcpy (new, type, length);
660 return (GVariantType *) new;
664 * g_variant_type_new:
665 * @type_string: a valid GVariant type string
666 * @returns: a new #GVariantType
668 * Creates a new #GVariantType corresponding to the type string given
669 * by @type_string. It is appropriate to call g_variant_type_free() on
672 * It is a programmer error to call this function with an invalid type
673 * string. Use g_variant_type_string_is_valid() if you are unsure.
676 g_variant_type_new (const gchar *type_string)
678 g_return_val_if_fail (type_string != NULL, NULL);
680 return g_variant_type_copy (G_VARIANT_TYPE (type_string));
684 * g_variant_type_get_string_length:
685 * @type: a #GVariantType
686 * @returns: the length of the corresponding type string
688 * Returns the length of the type string corresponding to the given
689 * @type. This function must be used to determine the valid extent of
690 * the memory region returned by g_variant_type_peek_string().
695 g_variant_type_get_string_length (const GVariantType *type)
697 const gchar *type_string = (const gchar *) type;
701 g_return_val_if_fail (g_variant_type_check (type), 0);
705 while (type_string[index] == 'a' || type_string[index] == 'm')
708 if (type_string[index] == '(' || type_string[index] == '{')
711 else if (type_string[index] == ')' || type_string[index] == '}')
722 * g_variant_type_peek_string:
723 * @type: a #GVariantType
724 * @returns: the corresponding type string (not nul-terminated)
726 * Returns the type string corresponding to the given @type. The
727 * result is not nul-terminated; in order to determine its length you
728 * must call g_variant_type_get_string_length().
730 * To get a nul-terminated string, see g_variant_type_dup_string().
735 g_variant_type_peek_string (const GVariantType *type)
737 g_return_val_if_fail (g_variant_type_check (type), NULL);
739 return (const gchar *) type;
743 * g_variant_type_dup_string:
744 * @type: a #GVariantType
745 * @returns: the corresponding type string
747 * Returns a newly-allocated copy of the type string corresponding to
748 * @type. The returned string is nul-terminated. It is appropriate to
749 * call g_free() on the return value.
754 g_variant_type_dup_string (const GVariantType *type)
756 g_return_val_if_fail (g_variant_type_check (type), NULL);
758 return g_strndup (g_variant_type_peek_string (type),
759 g_variant_type_get_string_length (type));
763 * g_variant_type_is_definite:
764 * @type: a #GVariantType
765 * @returns: %TRUE if @type is definite
767 * Determines if the given @type is definite (ie: not indefinite).
769 * A type is definite if its type string does not contain any indefinite
770 * type characters ('*', '?', or 'r').
772 * A #GVariant instance may not have an indefinite type, so calling
773 * this function on the result of g_variant_get_type() will always
774 * result in %TRUE being returned. Calling this function on an
775 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
776 * %FALSE being returned.
781 g_variant_type_is_definite (const GVariantType *type)
783 const gchar *type_string;
787 g_return_val_if_fail (g_variant_type_check (type), FALSE);
789 type_length = g_variant_type_get_string_length (type);
790 type_string = g_variant_type_peek_string (type);
792 for (i = 0; i < type_length; i++)
793 if (type_string[i] == '*' ||
794 type_string[i] == '?' ||
795 type_string[i] == 'r')
802 * g_variant_type_is_container:
803 * @type: a #GVariantType
804 * @returns: %TRUE if @type is a container type
806 * Determines if the given @type is a container type.
808 * Container types are any array, maybe, tuple, or dictionary
809 * entry types plus the variant type.
811 * This function returns %TRUE for any indefinite type for which every
812 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
818 g_variant_type_is_container (const GVariantType *type)
822 g_return_val_if_fail (g_variant_type_check (type), FALSE);
824 first_char = g_variant_type_peek_string (type)[0];
841 * g_variant_type_is_basic:
842 * @type: a #GVariantType
843 * @returns: %TRUE if @type is a basic type
845 * Determines if the given @type is a basic type.
847 * Basic types are booleans, bytes, integers, doubles, strings, object
848 * paths and signatures.
850 * Only a basic type may be used as the key of a dictionary entry.
852 * This function returns %FALSE for all indefinite types except
853 * %G_VARIANT_TYPE_BASIC.
858 g_variant_type_is_basic (const GVariantType *type)
862 g_return_val_if_fail (g_variant_type_check (type), FALSE);
864 first_char = g_variant_type_peek_string (type)[0];
889 * g_variant_type_is_maybe:
890 * @type: a #GVariantType
891 * @returns: %TRUE if @type is a maybe type
893 * Determines if the given @type is a maybe type. This is true if the
894 * type string for @type starts with an 'm'.
896 * This function returns %TRUE for any indefinite type for which every
897 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
903 g_variant_type_is_maybe (const GVariantType *type)
905 g_return_val_if_fail (g_variant_type_check (type), FALSE);
907 return g_variant_type_peek_string (type)[0] == 'm';
911 * g_variant_type_is_array:
912 * @type: a #GVariantType
913 * @returns: %TRUE if @type is an array type
915 * Determines if the given @type is an array type. This is true if the
916 * type string for @type starts with an 'a'.
918 * This function returns %TRUE for any indefinite type for which every
919 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
925 g_variant_type_is_array (const GVariantType *type)
927 g_return_val_if_fail (g_variant_type_check (type), FALSE);
929 return g_variant_type_peek_string (type)[0] == 'a';
933 * g_variant_type_is_tuple:
934 * @type: a #GVariantType
935 * @returns: %TRUE if @type is a tuple type
937 * Determines if the given @type is a tuple type. This is true if the
938 * type string for @type starts with a '(' or if @type is
939 * %G_VARIANT_TYPE_TUPLE.
941 * This function returns %TRUE for any indefinite type for which every
942 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
948 g_variant_type_is_tuple (const GVariantType *type)
952 g_return_val_if_fail (g_variant_type_check (type), FALSE);
954 type_char = g_variant_type_peek_string (type)[0];
955 return type_char == 'r' || type_char == '(';
959 * g_variant_type_is_dict_entry:
960 * @type: a #GVariantType
961 * @returns: %TRUE if @type is a dictionary entry type
963 * Determines if the given @type is a dictionary entry type. This is
964 * true if the type string for @type starts with a '{'.
966 * This function returns %TRUE for any indefinite type for which every
967 * definite subtype is a dictionary entry type --
968 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
973 g_variant_type_is_dict_entry (const GVariantType *type)
975 g_return_val_if_fail (g_variant_type_check (type), FALSE);
977 return g_variant_type_peek_string (type)[0] == '{';
981 * g_variant_type_hash:
982 * @type: a #GVariantType
983 * @returns: the hash value
987 * The argument type of @type is only #gconstpointer to allow use with
988 * #GHashTable without function pointer casting. A valid
989 * #GVariantType must be provided.
994 g_variant_type_hash (gconstpointer type)
996 const gchar *type_string;
1001 g_return_val_if_fail (g_variant_type_check (type), 0);
1003 type_string = g_variant_type_peek_string (type);
1004 length = g_variant_type_get_string_length (type);
1006 for (i = 0; i < length; i++)
1007 value = (value << 5) - value + type_string[i];
1013 * g_variant_type_equal:
1014 * @type1: a #GVariantType
1015 * @type2: a #GVariantType
1016 * @returns: %TRUE if @type1 and @type2 are exactly equal
1018 * Compares @type1 and @type2 for equality.
1020 * Only returns %TRUE if the types are exactly equal. Even if one type
1021 * is an indefinite type and the other is a subtype of it, %FALSE will
1022 * be returned if they are not exactly equal. If you want to check for
1023 * subtypes, use g_variant_type_is_subtype_of().
1025 * The argument types of @type1 and @type2 are only #gconstpointer to
1026 * allow use with #GHashTable without function pointer casting. For
1027 * both arguments, a valid #GVariantType must be provided.
1032 g_variant_type_equal (gconstpointer type1,
1033 gconstpointer type2)
1035 const gchar *string1, *string2;
1038 g_return_val_if_fail (g_variant_type_check (type1), FALSE);
1039 g_return_val_if_fail (g_variant_type_check (type2), FALSE);
1044 size1 = g_variant_type_get_string_length (type1);
1045 size2 = g_variant_type_get_string_length (type2);
1050 string1 = g_variant_type_peek_string (type1);
1051 string2 = g_variant_type_peek_string (type2);
1053 return memcmp (string1, string2, size1) == 0;
1057 * g_variant_type_is_subtype_of:
1058 * @type: a #GVariantType
1059 * @supertype: a #GVariantType
1060 * @returns: %TRUE if @type is a subtype of @supertype
1062 * Checks if @type is a subtype of @supertype.
1064 * This function returns %TRUE if @type is a subtype of @supertype. All
1065 * types are considered to be subtypes of themselves. Aside from that,
1066 * only indefinite types can have subtypes.
1071 g_variant_type_is_subtype_of (const GVariantType *type,
1072 const GVariantType *supertype)
1074 const gchar *supertype_string;
1075 const gchar *supertype_end;
1076 const gchar *type_string;
1078 g_return_val_if_fail (g_variant_type_check (type), FALSE);
1079 g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
1081 supertype_string = g_variant_type_peek_string (supertype);
1082 type_string = g_variant_type_peek_string (type);
1084 supertype_end = supertype_string +
1085 g_variant_type_get_string_length (supertype);
1087 /* we know that type and supertype are both well-formed, so it's
1088 * safe to treat this merely as a text processing problem.
1090 while (supertype_string < supertype_end)
1092 char supertype_char = *supertype_string++;
1094 if (supertype_char == *type_string)
1097 else if (*type_string == ')')
1102 const GVariantType *target_type = (GVariantType *) type_string;
1104 switch (supertype_char)
1107 if (!g_variant_type_is_tuple (target_type))
1115 if (!g_variant_type_is_basic (target_type))
1123 type_string += g_variant_type_get_string_length (target_type);
1131 * g_variant_type_element:
1132 * @type: an array or maybe #GVariantType
1133 * @returns: the element type of @type
1135 * Determines the element type of an array or maybe type.
1137 * This function may only be used with array or maybe types.
1141 const GVariantType *
1142 g_variant_type_element (const GVariantType *type)
1144 const gchar *type_string;
1146 g_return_val_if_fail (g_variant_type_check (type), NULL);
1148 type_string = g_variant_type_peek_string (type);
1150 g_assert (type_string[0] == 'a' || type_string[0] == 'm');
1152 return (const GVariantType *) &type_string[1];
1156 * g_variant_type_first:
1157 * @type: a tuple or dictionary entry #GVariantType
1158 * @returns: the first item type of @type, or %NULL
1160 * Determines the first item type of a tuple or dictionary entry
1163 * This function may only be used with tuple or dictionary entry types,
1164 * but must not be used with the generic tuple type
1165 * %G_VARIANT_TYPE_TUPLE.
1167 * In the case of a dictionary entry type, this returns the type of
1170 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
1172 * This call, together with g_variant_type_next() provides an iterator
1173 * interface over tuple and dictionary entry types.
1177 const GVariantType *
1178 g_variant_type_first (const GVariantType *type)
1180 const gchar *type_string;
1182 g_return_val_if_fail (g_variant_type_check (type), NULL);
1184 type_string = g_variant_type_peek_string (type);
1185 g_assert (type_string[0] == '(' || type_string[0] == '{');
1187 if (type_string[1] == ')')
1190 return (const GVariantType *) &type_string[1];
1194 * g_variant_type_next:
1195 * @type: a #GVariantType from a previous call
1196 * @returns: the next #GVariantType after @type, or %NULL
1198 * Determines the next item type of a tuple or dictionary entry
1201 * @type must be the result of a previous call to
1202 * g_variant_type_first() or g_variant_type_next().
1204 * If called on the key type of a dictionary entry then this call
1205 * returns the value type. If called on the value type of a dictionary
1206 * entry then this call returns %NULL.
1208 * For tuples, %NULL is returned when @type is the last item in a tuple.
1212 const GVariantType *
1213 g_variant_type_next (const GVariantType *type)
1215 const gchar *type_string;
1217 g_return_val_if_fail (g_variant_type_check (type), NULL);
1219 type_string = g_variant_type_peek_string (type);
1220 type_string += g_variant_type_get_string_length (type);
1222 if (*type_string == ')' || *type_string == '}')
1225 return (const GVariantType *) type_string;
1229 * g_variant_type_n_items:
1230 * @type: a tuple or dictionary entry #GVariantType
1231 * @returns: the number of items in @type
1233 * Determines the number of items contained in a tuple or
1234 * dictionary entry type.
1236 * This function may only be used with tuple or dictionary entry types,
1237 * but must not be used with the generic tuple type
1238 * %G_VARIANT_TYPE_TUPLE.
1240 * In the case of a dictionary entry type, this function will always
1246 g_variant_type_n_items (const GVariantType *type)
1250 g_return_val_if_fail (g_variant_type_check (type), 0);
1252 for (type = g_variant_type_first (type);
1254 type = g_variant_type_next (type))
1261 * g_variant_type_key:
1262 * @type: a dictionary entry #GVariantType
1263 * @returns: the key type of the dictionary entry
1265 * Determines the key type of a dictionary entry type.
1267 * This function may only be used with a dictionary entry type. Other
1268 * than the additional restriction, this call is equivalent to
1269 * g_variant_type_first().
1273 const GVariantType *
1274 g_variant_type_key (const GVariantType *type)
1276 const gchar *type_string;
1278 g_return_val_if_fail (g_variant_type_check (type), NULL);
1280 type_string = g_variant_type_peek_string (type);
1281 g_assert (type_string[0] == '{');
1283 return (const GVariantType *) &type_string[1];
1287 * g_variant_type_value:
1288 * @type: a dictionary entry #GVariantType
1289 * @returns: the value type of the dictionary entry
1291 * Determines the value type of a dictionary entry type.
1293 * This function may only be used with a dictionary entry type.
1297 const GVariantType *
1298 g_variant_type_value (const GVariantType *type)
1300 const gchar *type_string;
1302 g_return_val_if_fail (g_variant_type_check (type), NULL);
1304 type_string = g_variant_type_peek_string (type);
1305 g_assert (type_string[0] == '{');
1307 return g_variant_type_next (g_variant_type_key (type));
1311 * g_variant_type_new_tuple:
1312 * @items: an array of #GVariantTypes, one for each item
1313 * @length: the length of @items, or -1
1314 * @returns: a new tuple #GVariantType
1316 * Constructs a new tuple type, from @items.
1318 * @length is the number of items in @items, or -1 to indicate that
1319 * @items is %NULL-terminated.
1321 * It is appropriate to call g_variant_type_free() on the return value.
1325 static GVariantType *
1326 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1329 /* the "slow" version is needed in case the static buffer of 1024
1330 * bytes is exceeded when running the normal version. this will
1331 * happen only in truly insane code, so it can be slow.
1336 string = g_string_new ("(");
1337 for (i = 0; i < length; i++)
1339 const GVariantType *type;
1342 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1345 size = g_variant_type_get_string_length (type);
1346 g_string_append_len (string, (const gchar *) type, size);
1348 g_string_append_c (string, ')');
1350 return (GVariantType *) g_string_free (string, FALSE);
1354 g_variant_type_new_tuple (const GVariantType * const *items,
1361 g_return_val_if_fail (length == 0 || items != NULL, NULL);
1364 for (length = 0; items[length] != NULL; length++);
1367 buffer[offset++] = '(';
1369 for (i = 0; i < length; i++)
1371 const GVariantType *type;
1374 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1377 size = g_variant_type_get_string_length (type);
1379 if (offset + size >= sizeof buffer) /* leave room for ')' */
1380 return g_variant_type_new_tuple_slow (items, length);
1382 memcpy (&buffer[offset], type, size);
1386 g_assert (offset < sizeof buffer);
1387 buffer[offset++] = ')';
1389 return (GVariantType *) g_memdup (buffer, offset);
1393 * g_variant_type_new_array:
1394 * @element: a #GVariantType
1395 * @returns: a new array #GVariantType
1397 * Constructs the type corresponding to an array of elements of the
1400 * It is appropriate to call g_variant_type_free() on the return value.
1405 g_variant_type_new_array (const GVariantType *element)
1410 g_return_val_if_fail (g_variant_type_check (element), NULL);
1412 size = g_variant_type_get_string_length (element);
1413 new = g_malloc (size + 1);
1416 memcpy (new + 1, element, size);
1418 return (GVariantType *) new;
1422 * g_variant_type_new_maybe:
1423 * @element: a #GVariantType
1424 * @returns: a new maybe #GVariantType
1426 * Constructs the type corresponding to a maybe instance containing
1427 * type @type or Nothing.
1429 * It is appropriate to call g_variant_type_free() on the return value.
1434 g_variant_type_new_maybe (const GVariantType *element)
1439 g_return_val_if_fail (g_variant_type_check (element), NULL);
1441 size = g_variant_type_get_string_length (element);
1442 new = g_malloc (size + 1);
1445 memcpy (new + 1, element, size);
1447 return (GVariantType *) new;
1451 * g_variant_type_new_dict_entry:
1452 * @key: a basic #GVariantType
1453 * @value: a #GVariantType
1454 * @returns: a new dictionary entry #GVariantType
1456 * Constructs the type corresponding to a dictionary entry with a key
1457 * of type @key and a value of type @value.
1459 * It is appropriate to call g_variant_type_free() on the return value.
1464 g_variant_type_new_dict_entry (const GVariantType *key,
1465 const GVariantType *value)
1467 gsize keysize, valsize;
1470 g_return_val_if_fail (g_variant_type_check (key), NULL);
1471 g_return_val_if_fail (g_variant_type_check (value), NULL);
1473 keysize = g_variant_type_get_string_length (key);
1474 valsize = g_variant_type_get_string_length (value);
1476 new = g_malloc (1 + keysize + valsize + 1);
1479 memcpy (new + 1, key, keysize);
1480 memcpy (new + 1 + keysize, value, valsize);
1481 new[1 + keysize + valsize] = '}';
1483 return (GVariantType *) new;
1487 const GVariantType *
1488 g_variant_type_checked_ (const gchar *type_string)
1490 g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1491 return (const GVariantType *) type_string;
1494 #define __G_VARIANT_TYPE_C__
1495 #include "galiasdef.c"
projects / platform / upstream / glib.git / blob