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, see <http://www.gnu.org/licenses/>.
18 * Author: Ryan Lortie <desrt@desrt.ca>
23 #include "gvarianttype.h"
25 #include <glib/gtestutils.h>
26 #include <glib/gstrfuncs.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 D-Bus type system, with two major changes and
39 * some minor lifting of restrictions. The
40 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
41 * therefore, provides a significant amount of
42 * information that is useful when working with GVariant.
44 * The first major change with respect to the D-Bus 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 "m" 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 D-Bus. For example, it is possible to speak
53 * of "an array of any type" in GVariant, where the D-Bus 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 "*", "?" and "r" to type strings.
58 * Finally, all arbitrary restrictions relating to the complexity of
59 * types are lifted along with the restriction that dictionary entries
60 * may only appear nested inside of arrays.
62 * Just as in D-Bus, GVariant types are described with strings ("type
63 * strings"). Subject to the differences mentioned above, these strings
64 * are of the same form as those found in DBus. Note, however: D-Bus
65 * always works in terms of messages and therefore individual type
66 * strings appear nowhere in its interface. Instead, "signatures"
67 * are a concatenation of the strings of the type of each argument in a
68 * message. GVariant deals with single values directly so GVariant type
69 * strings always describe the type of exactly one value. This means
70 * that a D-Bus signature string is generally not a valid GVariant type
71 * string -- except in the case that it is the signature of a message
72 * containing exactly one argument.
74 * An indefinite type is similar in spirit to what may be called an
75 * abstract type in other type systems. No value can exist that has an
76 * indefinite type as its type, but values can exist that have types
77 * that are subtypes of indefinite types. That is to say,
78 * g_variant_get_type() will never return an indefinite type, but
79 * calling g_variant_is_of_type() with an indefinite type may return
80 * %TRUE. For example, you cannot have a value that represents "an
81 * array of no particular type", but you can have an "array of integers"
82 * which certainly matches the type of "an array of no particular type",
83 * since "array of integers" is a subtype of "array of no particular
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 * ## GVariant Type Strings
96 * A GVariant type string can be any of the following:
98 * - any basic type string (listed below)
102 * - one of the characters 'a' or 'm', followed by another type string
104 * - the character '(', followed by a concatenation of zero or more other
105 * type strings, followed by the character ')'
107 * - the character '{', followed by a basic type string (see below),
108 * followed by another type string, followed by the character '}'
110 * A basic type string describes a basic type (as per
111 * g_variant_type_is_basic()) and is always a single character in length.
112 * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
113 * "h", "d", "s", "o", "g" and "?".
115 * The above definition is recursive to arbitrary depth. "aaaaai" and
116 * "(ui(nq((y)))s)" are both valid type strings, as is
117 * "a(aa(ui)(qna{ya(yd)}))".
119 * The meaning of each of the characters is as follows:
126 * <emphasis role='strong'>Character</emphasis>
131 * <emphasis role='strong'>Meaning</emphasis>
143 * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
155 * the type string of %G_VARIANT_TYPE_BYTE; a byte.
167 * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
180 * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
193 * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
206 * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
219 * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
232 * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
245 * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
246 * value that, by convention, is used as an index into an array
247 * of file descriptors that are sent alongside a D-Bus message.
259 * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
260 * floating point value.
272 * the type string of %G_VARIANT_TYPE_STRING; a string.
284 * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
285 * the form of a D-Bus object path.
297 * the type string of %G_VARIANT_TYPE_STRING; a string in the
298 * form of a D-Bus type signature.
310 * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
311 * that is a supertype of any of the basic types.
323 * the type string of %G_VARIANT_TYPE_VARIANT; a container type
324 * that contain any other type of value.
336 * used as a prefix on another type string to mean an array of
337 * that type; the type string "ai", for example, is the type of
338 * an array of signed 32-bit integers.
350 * used as a prefix on another type string to mean a "maybe", or
351 * "nullable", version of that type; the type string "ms", for example,
352 * is the type of a value that maybe contains a string, or maybe
365 * used to enclose zero or more other concatenated type strings
366 * to create a tuple type; the type string "(is)", for example,
367 * is the type of a pair of an integer and a string.
379 * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
380 * that is a supertype of any tuple type, regardless of the
393 * used to enclose a basic type string concatenated with another
394 * type string to create a dictionary entry type, which usually
395 * appears inside of an array to form a dictionary; the type
396 * string "a{sd}", for example, is the type of a dictionary that
397 * maps strings to double precision floating point values.
400 * The first type (the basic type) is the key type and the second
401 * type is the value type. The reason that the first type is
402 * restricted to being a basic type is so that it can easily be
415 * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
416 * that is a supertype of all types. Note that, as with all type
417 * strings, this character represents exactly one type. It
418 * cannot be used inside of tuples to mean "any number of items".
426 * Any type string of a container that contains an indefinite type is,
427 * itself, an indefinite type. For example, the type string "a*"
428 * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
429 * that is a supertype of every array type. "(*s)" is a supertype
430 * of all tuples that contain exactly two items where the second
433 * "a{?*}" is an indefinite type that is a supertype of all arrays
434 * containing dictionary entries where the key is any basic type and
435 * the value is any type at all. This is, by definition, a dictionary,
436 * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
437 * that, due to the restriction that the key of a dictionary entry must
438 * be a basic type, "{**}" is not a valid type string.
443 g_variant_type_check (const GVariantType *type)
449 return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
456 * g_variant_type_string_scan:
457 * @string: a pointer to any string
458 * @limit: (allow-none): the end of @string, or %NULL
459 * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
461 * Scan for a single complete and valid GVariant type string in @string.
462 * The memory pointed to by @limit (or bytes beyond it) is never
465 * If a valid type string is found, @endptr is updated to point to the
466 * first character past the end of the string that was found and %TRUE
469 * If there is no valid type string starting at @string, or if the type
470 * string does not end before @limit then %FALSE is returned.
472 * For the simple case of checking if a string is a valid type string,
473 * see g_variant_type_string_is_valid().
475 * Returns: %TRUE if a valid type string was found
480 g_variant_type_string_scan (const gchar *string,
482 const gchar **endptr)
484 g_return_val_if_fail (string != NULL, FALSE);
486 if (string == limit || *string == '\0')
492 while (string == limit || *string != ')')
493 if (!g_variant_type_string_scan (string, limit, &string))
500 if (string == limit || *string == '\0' || /* { */
501 !strchr ("bynqihuxtdsog?", *string++) || /* key */
502 !g_variant_type_string_scan (string, limit, &string) || /* value */
503 string == limit || *string++ != '}') /* } */
509 return g_variant_type_string_scan (string, limit, endptr);
511 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
512 case 'x': case 't': case 'd': case 's': case 'o': case 'g':
513 case 'v': case 'r': case '*': case '?': case 'h':
527 * g_variant_type_string_is_valid:
528 * @type_string: a pointer to any string
530 * Checks if @type_string is a valid GVariant type string. This call is
531 * equivalent to calling g_variant_type_string_scan() and confirming
532 * that the following character is a nul terminator.
534 * Returns: %TRUE if @type_string is exactly one valid type string
539 g_variant_type_string_is_valid (const gchar *type_string)
543 g_return_val_if_fail (type_string != NULL, FALSE);
545 if (!g_variant_type_string_scan (type_string, NULL, &endptr))
548 return *endptr == '\0';
552 * g_variant_type_free:
553 * @type: (allow-none): a #GVariantType, or %NULL
555 * Frees a #GVariantType that was allocated with
556 * g_variant_type_copy(), g_variant_type_new() or one of the container
557 * type constructor functions.
559 * In the case that @type is %NULL, this function does nothing.
564 g_variant_type_free (GVariantType *type)
566 g_return_if_fail (type == NULL || g_variant_type_check (type));
572 * g_variant_type_copy:
573 * @type: a #GVariantType
575 * Makes a copy of a #GVariantType. It is appropriate to call
576 * g_variant_type_free() on the return value. @type may not be %NULL.
578 * Returns: (transfer full): a new #GVariantType
583 g_variant_type_copy (const GVariantType *type)
588 g_return_val_if_fail (g_variant_type_check (type), NULL);
590 length = g_variant_type_get_string_length (type);
591 new = g_malloc (length + 1);
593 memcpy (new, type, length);
596 return (GVariantType *) new;
600 * g_variant_type_new:
601 * @type_string: a valid GVariant type string
603 * Creates a new #GVariantType corresponding to the type string given
604 * by @type_string. It is appropriate to call g_variant_type_free() on
607 * It is a programmer error to call this function with an invalid type
608 * string. Use g_variant_type_string_is_valid() if you are unsure.
610 * Returns: (transfer full): a new #GVariantType
615 g_variant_type_new (const gchar *type_string)
617 g_return_val_if_fail (type_string != NULL, NULL);
619 return g_variant_type_copy (G_VARIANT_TYPE (type_string));
623 * g_variant_type_get_string_length:
624 * @type: a #GVariantType
626 * Returns the length of the type string corresponding to the given
627 * @type. This function must be used to determine the valid extent of
628 * the memory region returned by g_variant_type_peek_string().
630 * Returns: the length of the corresponding type string
635 g_variant_type_get_string_length (const GVariantType *type)
637 const gchar *type_string = (const gchar *) type;
641 g_return_val_if_fail (g_variant_type_check (type), 0);
645 while (type_string[index] == 'a' || type_string[index] == 'm')
648 if (type_string[index] == '(' || type_string[index] == '{')
651 else if (type_string[index] == ')' || type_string[index] == '}')
662 This function is not introspectable, it returns something that
663 is not an array and neither a string
666 * g_variant_type_peek_string: (skip)
667 * @type: a #GVariantType
669 * Returns the type string corresponding to the given @type. The
670 * result is not nul-terminated; in order to determine its length you
671 * must call g_variant_type_get_string_length().
673 * To get a nul-terminated string, see g_variant_type_dup_string().
675 * Returns: the corresponding type string (not nul-terminated)
680 g_variant_type_peek_string (const GVariantType *type)
682 g_return_val_if_fail (g_variant_type_check (type), NULL);
684 return (const gchar *) type;
688 * g_variant_type_dup_string:
689 * @type: a #GVariantType
691 * Returns a newly-allocated copy of the type string corresponding to
692 * @type. The returned string is nul-terminated. It is appropriate to
693 * call g_free() on the return value.
695 * Returns: (transfer full): the corresponding type string
700 g_variant_type_dup_string (const GVariantType *type)
702 g_return_val_if_fail (g_variant_type_check (type), NULL);
704 return g_strndup (g_variant_type_peek_string (type),
705 g_variant_type_get_string_length (type));
709 * g_variant_type_is_definite:
710 * @type: a #GVariantType
712 * Determines if the given @type is definite (ie: not indefinite).
714 * A type is definite if its type string does not contain any indefinite
715 * type characters ('*', '?', or 'r').
717 * A #GVariant instance may not have an indefinite type, so calling
718 * this function on the result of g_variant_get_type() will always
719 * result in %TRUE being returned. Calling this function on an
720 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
721 * %FALSE being returned.
723 * Returns: %TRUE if @type is definite
728 g_variant_type_is_definite (const GVariantType *type)
730 const gchar *type_string;
734 g_return_val_if_fail (g_variant_type_check (type), FALSE);
736 type_length = g_variant_type_get_string_length (type);
737 type_string = g_variant_type_peek_string (type);
739 for (i = 0; i < type_length; i++)
740 if (type_string[i] == '*' ||
741 type_string[i] == '?' ||
742 type_string[i] == 'r')
749 * g_variant_type_is_container:
750 * @type: a #GVariantType
752 * Determines if the given @type is a container type.
754 * Container types are any array, maybe, tuple, or dictionary
755 * entry types plus the variant type.
757 * This function returns %TRUE for any indefinite type for which every
758 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
761 * Returns: %TRUE if @type is a container type
766 g_variant_type_is_container (const GVariantType *type)
770 g_return_val_if_fail (g_variant_type_check (type), FALSE);
772 first_char = g_variant_type_peek_string (type)[0];
789 * g_variant_type_is_basic:
790 * @type: a #GVariantType
792 * Determines if the given @type is a basic type.
794 * Basic types are booleans, bytes, integers, doubles, strings, object
795 * paths and signatures.
797 * Only a basic type may be used as the key of a dictionary entry.
799 * This function returns %FALSE for all indefinite types except
800 * %G_VARIANT_TYPE_BASIC.
802 * Returns: %TRUE if @type is a basic type
807 g_variant_type_is_basic (const GVariantType *type)
811 g_return_val_if_fail (g_variant_type_check (type), FALSE);
813 first_char = g_variant_type_peek_string (type)[0];
838 * g_variant_type_is_maybe:
839 * @type: a #GVariantType
841 * Determines if the given @type is a maybe type. This is true if the
842 * type string for @type starts with an 'm'.
844 * This function returns %TRUE for any indefinite type for which every
845 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
848 * Returns: %TRUE if @type is a maybe type
853 g_variant_type_is_maybe (const GVariantType *type)
855 g_return_val_if_fail (g_variant_type_check (type), FALSE);
857 return g_variant_type_peek_string (type)[0] == 'm';
861 * g_variant_type_is_array:
862 * @type: a #GVariantType
864 * Determines if the given @type is an array type. This is true if the
865 * type string for @type starts with an 'a'.
867 * This function returns %TRUE for any indefinite type for which every
868 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
871 * Returns: %TRUE if @type is an array type
876 g_variant_type_is_array (const GVariantType *type)
878 g_return_val_if_fail (g_variant_type_check (type), FALSE);
880 return g_variant_type_peek_string (type)[0] == 'a';
884 * g_variant_type_is_tuple:
885 * @type: a #GVariantType
887 * Determines if the given @type is a tuple type. This is true if the
888 * type string for @type starts with a '(' or if @type is
889 * %G_VARIANT_TYPE_TUPLE.
891 * This function returns %TRUE for any indefinite type for which every
892 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
895 * Returns: %TRUE if @type is a tuple type
900 g_variant_type_is_tuple (const GVariantType *type)
904 g_return_val_if_fail (g_variant_type_check (type), FALSE);
906 type_char = g_variant_type_peek_string (type)[0];
907 return type_char == 'r' || type_char == '(';
911 * g_variant_type_is_dict_entry:
912 * @type: a #GVariantType
914 * Determines if the given @type is a dictionary entry type. This is
915 * true if the type string for @type starts with a '{'.
917 * This function returns %TRUE for any indefinite type for which every
918 * definite subtype is a dictionary entry type --
919 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
921 * Returns: %TRUE if @type is a dictionary entry type
926 g_variant_type_is_dict_entry (const GVariantType *type)
928 g_return_val_if_fail (g_variant_type_check (type), FALSE);
930 return g_variant_type_peek_string (type)[0] == '{';
934 * g_variant_type_is_variant:
935 * @type: a #GVariantType
937 * Determines if the given @type is the variant type.
939 * Returns: %TRUE if @type is the variant type
944 g_variant_type_is_variant (const GVariantType *type)
946 g_return_val_if_fail (g_variant_type_check (type), FALSE);
948 return g_variant_type_peek_string (type)[0] == 'v';
952 * g_variant_type_hash:
953 * @type: (type GVariantType): a #GVariantType
957 * The argument type of @type is only #gconstpointer to allow use with
958 * #GHashTable without function pointer casting. A valid
959 * #GVariantType must be provided.
961 * Returns: the hash value
966 g_variant_type_hash (gconstpointer type)
968 const gchar *type_string;
973 g_return_val_if_fail (g_variant_type_check (type), 0);
975 type_string = g_variant_type_peek_string (type);
976 length = g_variant_type_get_string_length (type);
978 for (i = 0; i < length; i++)
979 value = (value << 5) - value + type_string[i];
985 * g_variant_type_equal:
986 * @type1: (type GVariantType): a #GVariantType
987 * @type2: (type GVariantType): a #GVariantType
989 * Compares @type1 and @type2 for equality.
991 * Only returns %TRUE if the types are exactly equal. Even if one type
992 * is an indefinite type and the other is a subtype of it, %FALSE will
993 * be returned if they are not exactly equal. If you want to check for
994 * subtypes, use g_variant_type_is_subtype_of().
996 * The argument types of @type1 and @type2 are only #gconstpointer to
997 * allow use with #GHashTable without function pointer casting. For
998 * both arguments, a valid #GVariantType must be provided.
1000 * Returns: %TRUE if @type1 and @type2 are exactly equal
1005 g_variant_type_equal (gconstpointer type1,
1006 gconstpointer type2)
1008 const gchar *string1, *string2;
1011 g_return_val_if_fail (g_variant_type_check (type1), FALSE);
1012 g_return_val_if_fail (g_variant_type_check (type2), FALSE);
1017 size1 = g_variant_type_get_string_length (type1);
1018 size2 = g_variant_type_get_string_length (type2);
1023 string1 = g_variant_type_peek_string (type1);
1024 string2 = g_variant_type_peek_string (type2);
1026 return memcmp (string1, string2, size1) == 0;
1030 * g_variant_type_is_subtype_of:
1031 * @type: a #GVariantType
1032 * @supertype: a #GVariantType
1034 * Checks if @type is a subtype of @supertype.
1036 * This function returns %TRUE if @type is a subtype of @supertype. All
1037 * types are considered to be subtypes of themselves. Aside from that,
1038 * only indefinite types can have subtypes.
1040 * Returns: %TRUE if @type is a subtype of @supertype
1045 g_variant_type_is_subtype_of (const GVariantType *type,
1046 const GVariantType *supertype)
1048 const gchar *supertype_string;
1049 const gchar *supertype_end;
1050 const gchar *type_string;
1052 g_return_val_if_fail (g_variant_type_check (type), FALSE);
1053 g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
1055 supertype_string = g_variant_type_peek_string (supertype);
1056 type_string = g_variant_type_peek_string (type);
1058 supertype_end = supertype_string +
1059 g_variant_type_get_string_length (supertype);
1061 /* we know that type and supertype are both well-formed, so it's
1062 * safe to treat this merely as a text processing problem.
1064 while (supertype_string < supertype_end)
1066 char supertype_char = *supertype_string++;
1068 if (supertype_char == *type_string)
1071 else if (*type_string == ')')
1076 const GVariantType *target_type = (GVariantType *) type_string;
1078 switch (supertype_char)
1081 if (!g_variant_type_is_tuple (target_type))
1089 if (!g_variant_type_is_basic (target_type))
1097 type_string += g_variant_type_get_string_length (target_type);
1105 * g_variant_type_element:
1106 * @type: an array or maybe #GVariantType
1108 * Determines the element type of an array or maybe type.
1110 * This function may only be used with array or maybe types.
1112 * Returns: (transfer none): the element type of @type
1116 const GVariantType *
1117 g_variant_type_element (const GVariantType *type)
1119 const gchar *type_string;
1121 g_return_val_if_fail (g_variant_type_check (type), NULL);
1123 type_string = g_variant_type_peek_string (type);
1125 g_assert (type_string[0] == 'a' || type_string[0] == 'm');
1127 return (const GVariantType *) &type_string[1];
1131 * g_variant_type_first:
1132 * @type: a tuple or dictionary entry #GVariantType
1134 * Determines the first item type of a tuple or dictionary entry
1137 * This function may only be used with tuple or dictionary entry types,
1138 * but must not be used with the generic tuple type
1139 * %G_VARIANT_TYPE_TUPLE.
1141 * In the case of a dictionary entry type, this returns the type of
1144 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
1146 * This call, together with g_variant_type_next() provides an iterator
1147 * interface over tuple and dictionary entry types.
1149 * Returns: (transfer none): the first item type of @type, or %NULL
1153 const GVariantType *
1154 g_variant_type_first (const GVariantType *type)
1156 const gchar *type_string;
1158 g_return_val_if_fail (g_variant_type_check (type), NULL);
1160 type_string = g_variant_type_peek_string (type);
1161 g_assert (type_string[0] == '(' || type_string[0] == '{');
1163 if (type_string[1] == ')')
1166 return (const GVariantType *) &type_string[1];
1170 * g_variant_type_next:
1171 * @type: a #GVariantType from a previous call
1173 * Determines the next item type of a tuple or dictionary entry
1176 * @type must be the result of a previous call to
1177 * g_variant_type_first() or g_variant_type_next().
1179 * If called on the key type of a dictionary entry then this call
1180 * returns the value type. If called on the value type of a dictionary
1181 * entry then this call returns %NULL.
1183 * For tuples, %NULL is returned when @type is the last item in a tuple.
1185 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
1189 const GVariantType *
1190 g_variant_type_next (const GVariantType *type)
1192 const gchar *type_string;
1194 g_return_val_if_fail (g_variant_type_check (type), NULL);
1196 type_string = g_variant_type_peek_string (type);
1197 type_string += g_variant_type_get_string_length (type);
1199 if (*type_string == ')' || *type_string == '}')
1202 return (const GVariantType *) type_string;
1206 * g_variant_type_n_items:
1207 * @type: a tuple or dictionary entry #GVariantType
1209 * Determines the number of items contained in a tuple or
1210 * dictionary entry type.
1212 * This function may only be used with tuple or dictionary entry types,
1213 * but must not be used with the generic tuple type
1214 * %G_VARIANT_TYPE_TUPLE.
1216 * In the case of a dictionary entry type, this function will always
1219 * Returns: the number of items in @type
1224 g_variant_type_n_items (const GVariantType *type)
1228 g_return_val_if_fail (g_variant_type_check (type), 0);
1230 for (type = g_variant_type_first (type);
1232 type = g_variant_type_next (type))
1239 * g_variant_type_key:
1240 * @type: a dictionary entry #GVariantType
1242 * Determines the key type of a dictionary entry type.
1244 * This function may only be used with a dictionary entry type. Other
1245 * than the additional restriction, this call is equivalent to
1246 * g_variant_type_first().
1248 * Returns: (transfer none): the key type of the dictionary entry
1252 const GVariantType *
1253 g_variant_type_key (const GVariantType *type)
1255 const gchar *type_string;
1257 g_return_val_if_fail (g_variant_type_check (type), NULL);
1259 type_string = g_variant_type_peek_string (type);
1260 g_assert (type_string[0] == '{');
1262 return (const GVariantType *) &type_string[1];
1266 * g_variant_type_value:
1267 * @type: a dictionary entry #GVariantType
1269 * Determines the value type of a dictionary entry type.
1271 * This function may only be used with a dictionary entry type.
1273 * Returns: (transfer none): the value type of the dictionary entry
1277 const GVariantType *
1278 g_variant_type_value (const GVariantType *type)
1280 const gchar *type_string;
1282 g_return_val_if_fail (g_variant_type_check (type), NULL);
1284 type_string = g_variant_type_peek_string (type);
1285 g_assert (type_string[0] == '{');
1287 return g_variant_type_next (g_variant_type_key (type));
1291 * g_variant_type_new_tuple:
1292 * @items: (array length=length): an array of #GVariantTypes, one for each item
1293 * @length: the length of @items, or -1
1295 * Constructs a new tuple type, from @items.
1297 * @length is the number of items in @items, or -1 to indicate that
1298 * @items is %NULL-terminated.
1300 * It is appropriate to call g_variant_type_free() on the return value.
1302 * Returns: (transfer full): a new tuple #GVariantType
1306 static GVariantType *
1307 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1310 /* the "slow" version is needed in case the static buffer of 1024
1311 * bytes is exceeded when running the normal version. this will
1312 * happen only in truly insane code, so it can be slow.
1317 string = g_string_new ("(");
1318 for (i = 0; i < length; i++)
1320 const GVariantType *type;
1323 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1326 size = g_variant_type_get_string_length (type);
1327 g_string_append_len (string, (const gchar *) type, size);
1329 g_string_append_c (string, ')');
1331 return (GVariantType *) g_string_free (string, FALSE);
1335 g_variant_type_new_tuple (const GVariantType * const *items,
1342 g_return_val_if_fail (length == 0 || items != NULL, NULL);
1345 for (length = 0; items[length] != NULL; length++);
1348 buffer[offset++] = '(';
1350 for (i = 0; i < length; i++)
1352 const GVariantType *type;
1355 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1358 size = g_variant_type_get_string_length (type);
1360 if (offset + size >= sizeof buffer) /* leave room for ')' */
1361 return g_variant_type_new_tuple_slow (items, length);
1363 memcpy (&buffer[offset], type, size);
1367 g_assert (offset < sizeof buffer);
1368 buffer[offset++] = ')';
1370 return (GVariantType *) g_memdup (buffer, offset);
1374 * g_variant_type_new_array: (constructor)
1375 * @element: a #GVariantType
1377 * Constructs the type corresponding to an array of elements of the
1380 * It is appropriate to call g_variant_type_free() on the return value.
1382 * Returns: (transfer full): a new array #GVariantType
1387 g_variant_type_new_array (const GVariantType *element)
1392 g_return_val_if_fail (g_variant_type_check (element), NULL);
1394 size = g_variant_type_get_string_length (element);
1395 new = g_malloc (size + 1);
1398 memcpy (new + 1, element, size);
1400 return (GVariantType *) new;
1404 * g_variant_type_new_maybe: (constructor)
1405 * @element: a #GVariantType
1407 * Constructs the type corresponding to a maybe instance containing
1408 * type @type or Nothing.
1410 * It is appropriate to call g_variant_type_free() on the return value.
1412 * Returns: (transfer full): a new maybe #GVariantType
1417 g_variant_type_new_maybe (const GVariantType *element)
1422 g_return_val_if_fail (g_variant_type_check (element), NULL);
1424 size = g_variant_type_get_string_length (element);
1425 new = g_malloc (size + 1);
1428 memcpy (new + 1, element, size);
1430 return (GVariantType *) new;
1434 * g_variant_type_new_dict_entry: (constructor)
1435 * @key: a basic #GVariantType
1436 * @value: a #GVariantType
1438 * Constructs the type corresponding to a dictionary entry with a key
1439 * of type @key and a value of type @value.
1441 * It is appropriate to call g_variant_type_free() on the return value.
1443 * Returns: (transfer full): a new dictionary entry #GVariantType
1448 g_variant_type_new_dict_entry (const GVariantType *key,
1449 const GVariantType *value)
1451 gsize keysize, valsize;
1454 g_return_val_if_fail (g_variant_type_check (key), NULL);
1455 g_return_val_if_fail (g_variant_type_check (value), NULL);
1457 keysize = g_variant_type_get_string_length (key);
1458 valsize = g_variant_type_get_string_length (value);
1460 new = g_malloc (1 + keysize + valsize + 1);
1463 memcpy (new + 1, key, keysize);
1464 memcpy (new + 1 + keysize, value, valsize);
1465 new[1 + keysize + valsize] = '}';
1467 return (GVariantType *) new;
1471 const GVariantType *
1472 g_variant_type_checked_ (const gchar *type_string)
1474 g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1475 return (const GVariantType *) type_string;