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>
25 #include "gvarianttype.h"
27 #include <glib/gtestutils.h>
28 #include <glib/gstrfuncs.h>
34 * SECTION:gvarianttype
35 * @title: GVariantType
36 * @short_description: introduction to the GVariant type system
37 * @see_also: #GVariantType, #GVariant
39 * This section introduces the GVariant type system. It is based, in
40 * large part, on the D-Bus type system, with two major changes and some minor
41 * lifting of restrictions. The <ulink
42 * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
43 * specification</ulink>, therefore, provides a significant amount of
44 * information that is useful when working with GVariant.
46 * The first major change with respect to the D-Bus type system is the
47 * introduction of maybe (or "nullable") types. Any type in GVariant can be
48 * converted to a maybe type, in which case, "nothing" (or "null") becomes a
49 * valid value. Maybe types have been added by introducing the
50 * character "<literal>m</literal>" to type strings.
52 * The second major change is that the GVariant type system supports the
53 * concept of "indefinite types" -- types that are less specific than
54 * the normal types found in D-Bus. For example, it is possible to speak
55 * of "an array of any type" in GVariant, where the D-Bus type system
56 * would require you to speak of "an array of integers" or "an array of
57 * strings". Indefinite types have been added by introducing the
58 * characters "<literal>*</literal>", "<literal>?</literal>" and
59 * "<literal>r</literal>" to type strings.
61 * Finally, all arbitrary restrictions relating to the complexity of
62 * types are lifted along with the restriction that dictionary entries
63 * may only appear nested inside of arrays.
65 * Just as in D-Bus, GVariant types are described with strings ("type
66 * strings"). Subject to the differences mentioned above, these strings
67 * are of the same form as those found in DBus. Note, however: D-Bus
68 * always works in terms of messages and therefore individual type
69 * strings appear nowhere in its interface. Instead, "signatures"
70 * are a concatenation of the strings of the type of each argument in a
71 * message. GVariant deals with single values directly so GVariant type
72 * strings always describe the type of exactly one value. This means
73 * that a D-Bus signature string is generally not a valid GVariant type
74 * string -- except in the case that it is the signature of a message
75 * containing exactly one argument.
77 * An indefinite type is similar in spirit to what may be called an
78 * abstract type in other type systems. No value can exist that has an
79 * indefinite type as its type, but values can exist that have types
80 * that are subtypes of indefinite types. That is to say,
81 * g_variant_get_type() will never return an indefinite type, but
82 * calling g_variant_is_of_type() with an indefinite type may return
83 * %TRUE. For example, you cannot have a value that represents "an
84 * array of no particular type", but you can have an "array of integers"
85 * which certainly matches the type of "an array of no particular type",
86 * since "array of integers" is a subtype of "array of no particular
89 * This is similar to how instances of abstract classes may not
90 * directly exist in other type systems, but instances of their
91 * non-abstract subtypes may. For example, in GTK, no object that has
92 * the type of #GtkBin can exist (since #GtkBin is an abstract class),
93 * but a #GtkWindow can certainly be instantiated, and you would say
94 * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
97 * A detailed description of GVariant type strings is given here:
99 * <refsect2 id='gvariant-typestrings'>
100 * <title>GVariant Type Strings</title>
102 * A GVariant type string can be any of the following:
107 * any basic type string (listed below)
112 * "<literal>v</literal>", "<literal>r</literal>" or
113 * "<literal>*</literal>"
118 * one of the characters '<literal>a</literal>' or
119 * '<literal>m</literal>', followed by another type string
124 * the character '<literal>(</literal>', followed by a concatenation
125 * of zero or more other type strings, followed by the character
126 * '<literal>)</literal>'
131 * the character '<literal>{</literal>', followed by a basic type
132 * string (see below), followed by another type string, followed by
133 * the character '<literal>}</literal>'
138 * A basic type string describes a basic type (as per
139 * g_variant_type_is_basic()) and is always a single
140 * character in length. The valid basic type strings are
141 * "<literal>b</literal>", "<literal>y</literal>",
142 * "<literal>n</literal>", "<literal>q</literal>",
143 * "<literal>i</literal>", "<literal>u</literal>",
144 * "<literal>x</literal>", "<literal>t</literal>",
145 * "<literal>h</literal>", "<literal>d</literal>",
146 * "<literal>s</literal>", "<literal>o</literal>",
147 * "<literal>g</literal>" and "<literal>?</literal>".
150 * The above definition is recursive to arbitrary depth.
151 * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
152 * are both valid type strings, as is
153 * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
156 * The meaning of each of the characters is as follows:
164 * <emphasis role='strong'>Character</emphasis>
169 * <emphasis role='strong'>Meaning</emphasis>
176 * <literal>b</literal>
181 * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
188 * <literal>y</literal>
193 * the type string of %G_VARIANT_TYPE_BYTE; a byte.
200 * <literal>n</literal>
205 * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
213 * <literal>q</literal>
218 * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
226 * <literal>i</literal>
231 * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
239 * <literal>u</literal>
244 * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
252 * <literal>x</literal>
257 * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
265 * <literal>t</literal>
270 * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
278 * <literal>h</literal>
283 * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
284 * value that, by convention, is used as an index into an array
285 * of file descriptors that are sent alongside a D-Bus message.
292 * <literal>d</literal>
297 * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
298 * floating point value.
305 * <literal>s</literal>
310 * the type string of %G_VARIANT_TYPE_STRING; a string.
317 * <literal>o</literal>
322 * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
323 * the form of a D-Bus object path.
330 * <literal>g</literal>
335 * the type string of %G_VARIANT_TYPE_STRING; a string in the
336 * form of a D-Bus type signature.
343 * <literal>?</literal>
348 * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
349 * that is a supertype of any of the basic types.
356 * <literal>v</literal>
361 * the type string of %G_VARIANT_TYPE_VARIANT; a container type
362 * that contain any other type of value.
369 * <literal>a</literal>
374 * used as a prefix on another type string to mean an array of
375 * that type; the type string "<literal>ai</literal>", for
376 * example, is the type of an array of 32 bit signed integers.
383 * <literal>m</literal>
388 * used as a prefix on another type string to mean a "maybe", or
389 * "nullable", version of that type; the type string
390 * "<literal>ms</literal>", for example, is the type of a value
391 * that maybe contains a string, or maybe contains nothing.
398 * <literal>()</literal>
403 * used to enclose zero or more other concatenated type strings
404 * to create a tuple type; the type string
405 * "<literal>(is)</literal>", for example, is the type of a pair
406 * of an integer and a string.
413 * <literal>r</literal>
418 * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
419 * that is a supertype of any tuple type, regardless of the
427 * <literal>{}</literal>
432 * used to enclose a basic type string concatenated with another
433 * type string to create a dictionary entry type, which usually
434 * appears inside of an array to form a dictionary; the type
435 * string "<literal>a{sd}</literal>", for example, is the type of
436 * a dictionary that maps strings to double precision floating
440 * The first type (the basic type) is the key type and the second
441 * type is the value type. The reason that the first type is
442 * restricted to being a basic type is so that it can easily be
450 * <literal>*</literal>
455 * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
456 * that is a supertype of all types. Note that, as with all type
457 * strings, this character represents exactly one type. It
458 * cannot be used inside of tuples to mean "any number of items".
466 * Any type string of a container that contains an indefinite type is,
467 * itself, an indefinite type. For example, the type string
468 * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
469 * an indefinite type that is a supertype of every array type.
470 * "<literal>(*s)</literal>" is a supertype of all tuples that
471 * contain exactly two items where the second item is a string.
474 * "<literal>a{?*}</literal>" is an indefinite type that is a
475 * supertype of all arrays containing dictionary entries where the key
476 * is any basic type and the value is any type at all. This is, by
477 * definition, a dictionary, so this type string corresponds to
478 * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that
479 * the key of a dictionary entry must be a basic type,
480 * "<literal>{**}</literal>" is not a valid type string.
487 g_variant_type_check (const GVariantType *type)
493 return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
500 * g_variant_type_string_scan:
501 * @string: a pointer to any string
502 * @limit: (allow-none): the end of @string, or %NULL
503 * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
505 * Scan for a single complete and valid GVariant type string in @string.
506 * The memory pointed to by @limit (or bytes beyond it) is never
509 * If a valid type string is found, @endptr is updated to point to the
510 * first character past the end of the string that was found and %TRUE
513 * If there is no valid type string starting at @string, or if the type
514 * string does not end before @limit then %FALSE is returned.
516 * For the simple case of checking if a string is a valid type string,
517 * see g_variant_type_string_is_valid().
519 * Returns: %TRUE if a valid type string was found
524 g_variant_type_string_scan (const gchar *string,
526 const gchar **endptr)
528 g_return_val_if_fail (string != NULL, FALSE);
530 if (string == limit || *string == '\0')
536 while (string == limit || *string != ')')
537 if (!g_variant_type_string_scan (string, limit, &string))
544 if (string == limit || *string == '\0' || /* { */
545 !strchr ("bynqihuxtdsog?", *string++) || /* key */
546 !g_variant_type_string_scan (string, limit, &string) || /* value */
547 string == limit || *string++ != '}') /* } */
553 return g_variant_type_string_scan (string, limit, endptr);
555 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
556 case 'x': case 't': case 'd': case 's': case 'o': case 'g':
557 case 'v': case 'r': case '*': case '?': case 'h':
571 * g_variant_type_string_is_valid:
572 * @type_string: a pointer to any string
574 * Checks if @type_string is a valid GVariant type string. This call is
575 * equivalent to calling g_variant_type_string_scan() and confirming
576 * that the following character is a nul terminator.
578 * Returns: %TRUE if @type_string is exactly one valid type string
583 g_variant_type_string_is_valid (const gchar *type_string)
587 g_return_val_if_fail (type_string != NULL, FALSE);
589 if (!g_variant_type_string_scan (type_string, NULL, &endptr))
592 return *endptr == '\0';
596 * g_variant_type_free:
597 * @type: (allow-none): a #GVariantType, or %NULL
599 * Frees a #GVariantType that was allocated with
600 * g_variant_type_copy(), g_variant_type_new() or one of the container
601 * type constructor functions.
603 * In the case that @type is %NULL, this function does nothing.
608 g_variant_type_free (GVariantType *type)
610 g_return_if_fail (type == NULL || g_variant_type_check (type));
616 * g_variant_type_copy:
617 * @type: a #GVariantType
619 * Makes a copy of a #GVariantType. It is appropriate to call
620 * g_variant_type_free() on the return value. @type may not be %NULL.
622 * Returns: (transfer full): a new #GVariantType
627 g_variant_type_copy (const GVariantType *type)
632 g_return_val_if_fail (g_variant_type_check (type), NULL);
634 length = g_variant_type_get_string_length (type);
635 new = g_malloc (length + 1);
637 memcpy (new, type, length);
640 return (GVariantType *) new;
644 * g_variant_type_new:
645 * @type_string: a valid GVariant type string
647 * Creates a new #GVariantType corresponding to the type string given
648 * by @type_string. It is appropriate to call g_variant_type_free() on
651 * It is a programmer error to call this function with an invalid type
652 * string. Use g_variant_type_string_is_valid() if you are unsure.
654 * Returns: (transfer full): a new #GVariantType
659 g_variant_type_new (const gchar *type_string)
661 g_return_val_if_fail (type_string != NULL, NULL);
663 return g_variant_type_copy (G_VARIANT_TYPE (type_string));
667 * g_variant_type_get_string_length:
668 * @type: a #GVariantType
670 * Returns the length of the type string corresponding to the given
671 * @type. This function must be used to determine the valid extent of
672 * the memory region returned by g_variant_type_peek_string().
674 * Returns: the length of the corresponding type string
679 g_variant_type_get_string_length (const GVariantType *type)
681 const gchar *type_string = (const gchar *) type;
685 g_return_val_if_fail (g_variant_type_check (type), 0);
689 while (type_string[index] == 'a' || type_string[index] == 'm')
692 if (type_string[index] == '(' || type_string[index] == '{')
695 else if (type_string[index] == ')' || type_string[index] == '}')
706 This function is not introspectable, it returns something that
707 is not an array and neither a string
710 * g_variant_type_peek_string: (skip)
711 * @type: a #GVariantType
713 * Returns the type string corresponding to the given @type. The
714 * result is not nul-terminated; in order to determine its length you
715 * must call g_variant_type_get_string_length().
717 * To get a nul-terminated string, see g_variant_type_dup_string().
719 * Returns: the corresponding type string (not nul-terminated)
724 g_variant_type_peek_string (const GVariantType *type)
726 g_return_val_if_fail (g_variant_type_check (type), NULL);
728 return (const gchar *) type;
732 * g_variant_type_dup_string:
733 * @type: a #GVariantType
735 * Returns a newly-allocated copy of the type string corresponding to
736 * @type. The returned string is nul-terminated. It is appropriate to
737 * call g_free() on the return value.
739 * Returns: (transfer full): the corresponding type string
744 g_variant_type_dup_string (const GVariantType *type)
746 g_return_val_if_fail (g_variant_type_check (type), NULL);
748 return g_strndup (g_variant_type_peek_string (type),
749 g_variant_type_get_string_length (type));
753 * g_variant_type_is_definite:
754 * @type: a #GVariantType
756 * Determines if the given @type is definite (ie: not indefinite).
758 * A type is definite if its type string does not contain any indefinite
759 * type characters ('*', '?', or 'r').
761 * A #GVariant instance may not have an indefinite type, so calling
762 * this function on the result of g_variant_get_type() will always
763 * result in %TRUE being returned. Calling this function on an
764 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
765 * %FALSE being returned.
767 * Returns: %TRUE if @type is definite
772 g_variant_type_is_definite (const GVariantType *type)
774 const gchar *type_string;
778 g_return_val_if_fail (g_variant_type_check (type), FALSE);
780 type_length = g_variant_type_get_string_length (type);
781 type_string = g_variant_type_peek_string (type);
783 for (i = 0; i < type_length; i++)
784 if (type_string[i] == '*' ||
785 type_string[i] == '?' ||
786 type_string[i] == 'r')
793 * g_variant_type_is_container:
794 * @type: a #GVariantType
796 * Determines if the given @type is a container type.
798 * Container types are any array, maybe, tuple, or dictionary
799 * entry types plus the variant type.
801 * This function returns %TRUE for any indefinite type for which every
802 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
805 * Returns: %TRUE if @type is a container type
810 g_variant_type_is_container (const GVariantType *type)
814 g_return_val_if_fail (g_variant_type_check (type), FALSE);
816 first_char = g_variant_type_peek_string (type)[0];
833 * g_variant_type_is_basic:
834 * @type: a #GVariantType
836 * Determines if the given @type is a basic type.
838 * Basic types are booleans, bytes, integers, doubles, strings, object
839 * paths and signatures.
841 * Only a basic type may be used as the key of a dictionary entry.
843 * This function returns %FALSE for all indefinite types except
844 * %G_VARIANT_TYPE_BASIC.
846 * Returns: %TRUE if @type is a basic type
851 g_variant_type_is_basic (const GVariantType *type)
855 g_return_val_if_fail (g_variant_type_check (type), FALSE);
857 first_char = g_variant_type_peek_string (type)[0];
882 * g_variant_type_is_maybe:
883 * @type: a #GVariantType
885 * Determines if the given @type is a maybe type. This is true if the
886 * type string for @type starts with an 'm'.
888 * This function returns %TRUE for any indefinite type for which every
889 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
892 * Returns: %TRUE if @type is a maybe type
897 g_variant_type_is_maybe (const GVariantType *type)
899 g_return_val_if_fail (g_variant_type_check (type), FALSE);
901 return g_variant_type_peek_string (type)[0] == 'm';
905 * g_variant_type_is_array:
906 * @type: a #GVariantType
908 * Determines if the given @type is an array type. This is true if the
909 * type string for @type starts with an 'a'.
911 * This function returns %TRUE for any indefinite type for which every
912 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
915 * Returns: %TRUE if @type is an array type
920 g_variant_type_is_array (const GVariantType *type)
922 g_return_val_if_fail (g_variant_type_check (type), FALSE);
924 return g_variant_type_peek_string (type)[0] == 'a';
928 * g_variant_type_is_tuple:
929 * @type: a #GVariantType
931 * Determines if the given @type is a tuple type. This is true if the
932 * type string for @type starts with a '(' or if @type is
933 * %G_VARIANT_TYPE_TUPLE.
935 * This function returns %TRUE for any indefinite type for which every
936 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
939 * Returns: %TRUE if @type is a tuple type
944 g_variant_type_is_tuple (const GVariantType *type)
948 g_return_val_if_fail (g_variant_type_check (type), FALSE);
950 type_char = g_variant_type_peek_string (type)[0];
951 return type_char == 'r' || type_char == '(';
955 * g_variant_type_is_dict_entry:
956 * @type: a #GVariantType
958 * Determines if the given @type is a dictionary entry type. This is
959 * true if the type string for @type starts with a '{'.
961 * This function returns %TRUE for any indefinite type for which every
962 * definite subtype is a dictionary entry type --
963 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
965 * Returns: %TRUE if @type is a dictionary entry type
970 g_variant_type_is_dict_entry (const GVariantType *type)
972 g_return_val_if_fail (g_variant_type_check (type), FALSE);
974 return g_variant_type_peek_string (type)[0] == '{';
978 * g_variant_type_is_variant:
979 * @type: a #GVariantType
981 * Determines if the given @type is the variant type.
983 * Returns: %TRUE if @type is the variant type
988 g_variant_type_is_variant (const GVariantType *type)
990 g_return_val_if_fail (g_variant_type_check (type), FALSE);
992 return g_variant_type_peek_string (type)[0] == 'v';
996 * g_variant_type_hash:
997 * @type: (type GVariantType): a #GVariantType
1001 * The argument type of @type is only #gconstpointer to allow use with
1002 * #GHashTable without function pointer casting. A valid
1003 * #GVariantType must be provided.
1005 * Returns: the hash value
1010 g_variant_type_hash (gconstpointer type)
1012 const gchar *type_string;
1017 g_return_val_if_fail (g_variant_type_check (type), 0);
1019 type_string = g_variant_type_peek_string (type);
1020 length = g_variant_type_get_string_length (type);
1022 for (i = 0; i < length; i++)
1023 value = (value << 5) - value + type_string[i];
1029 * g_variant_type_equal:
1030 * @type1: (type GVariantType): a #GVariantType
1031 * @type2: (type GVariantType): a #GVariantType
1033 * Compares @type1 and @type2 for equality.
1035 * Only returns %TRUE if the types are exactly equal. Even if one type
1036 * is an indefinite type and the other is a subtype of it, %FALSE will
1037 * be returned if they are not exactly equal. If you want to check for
1038 * subtypes, use g_variant_type_is_subtype_of().
1040 * The argument types of @type1 and @type2 are only #gconstpointer to
1041 * allow use with #GHashTable without function pointer casting. For
1042 * both arguments, a valid #GVariantType must be provided.
1044 * Returns: %TRUE if @type1 and @type2 are exactly equal
1049 g_variant_type_equal (gconstpointer type1,
1050 gconstpointer type2)
1052 const gchar *string1, *string2;
1055 g_return_val_if_fail (g_variant_type_check (type1), FALSE);
1056 g_return_val_if_fail (g_variant_type_check (type2), FALSE);
1061 size1 = g_variant_type_get_string_length (type1);
1062 size2 = g_variant_type_get_string_length (type2);
1067 string1 = g_variant_type_peek_string (type1);
1068 string2 = g_variant_type_peek_string (type2);
1070 return memcmp (string1, string2, size1) == 0;
1074 * g_variant_type_is_subtype_of:
1075 * @type: a #GVariantType
1076 * @supertype: a #GVariantType
1078 * Checks if @type is a subtype of @supertype.
1080 * This function returns %TRUE if @type is a subtype of @supertype. All
1081 * types are considered to be subtypes of themselves. Aside from that,
1082 * only indefinite types can have subtypes.
1084 * Returns: %TRUE if @type is a subtype of @supertype
1089 g_variant_type_is_subtype_of (const GVariantType *type,
1090 const GVariantType *supertype)
1092 const gchar *supertype_string;
1093 const gchar *supertype_end;
1094 const gchar *type_string;
1096 g_return_val_if_fail (g_variant_type_check (type), FALSE);
1097 g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
1099 supertype_string = g_variant_type_peek_string (supertype);
1100 type_string = g_variant_type_peek_string (type);
1102 supertype_end = supertype_string +
1103 g_variant_type_get_string_length (supertype);
1105 /* we know that type and supertype are both well-formed, so it's
1106 * safe to treat this merely as a text processing problem.
1108 while (supertype_string < supertype_end)
1110 char supertype_char = *supertype_string++;
1112 if (supertype_char == *type_string)
1115 else if (*type_string == ')')
1120 const GVariantType *target_type = (GVariantType *) type_string;
1122 switch (supertype_char)
1125 if (!g_variant_type_is_tuple (target_type))
1133 if (!g_variant_type_is_basic (target_type))
1141 type_string += g_variant_type_get_string_length (target_type);
1149 * g_variant_type_element:
1150 * @type: an array or maybe #GVariantType
1152 * Determines the element type of an array or maybe type.
1154 * This function may only be used with array or maybe types.
1156 * Returns: (transfer none): the element type of @type
1160 const GVariantType *
1161 g_variant_type_element (const GVariantType *type)
1163 const gchar *type_string;
1165 g_return_val_if_fail (g_variant_type_check (type), NULL);
1167 type_string = g_variant_type_peek_string (type);
1169 g_assert (type_string[0] == 'a' || type_string[0] == 'm');
1171 return (const GVariantType *) &type_string[1];
1175 * g_variant_type_first:
1176 * @type: a tuple or dictionary entry #GVariantType
1178 * Determines the first item type of a tuple or dictionary entry
1181 * This function may only be used with tuple or dictionary entry types,
1182 * but must not be used with the generic tuple type
1183 * %G_VARIANT_TYPE_TUPLE.
1185 * In the case of a dictionary entry type, this returns the type of
1188 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
1190 * This call, together with g_variant_type_next() provides an iterator
1191 * interface over tuple and dictionary entry types.
1193 * Returns: (transfer none): the first item type of @type, or %NULL
1197 const GVariantType *
1198 g_variant_type_first (const GVariantType *type)
1200 const gchar *type_string;
1202 g_return_val_if_fail (g_variant_type_check (type), NULL);
1204 type_string = g_variant_type_peek_string (type);
1205 g_assert (type_string[0] == '(' || type_string[0] == '{');
1207 if (type_string[1] == ')')
1210 return (const GVariantType *) &type_string[1];
1214 * g_variant_type_next:
1215 * @type: a #GVariantType from a previous call
1217 * Determines the next item type of a tuple or dictionary entry
1220 * @type must be the result of a previous call to
1221 * g_variant_type_first() or g_variant_type_next().
1223 * If called on the key type of a dictionary entry then this call
1224 * returns the value type. If called on the value type of a dictionary
1225 * entry then this call returns %NULL.
1227 * For tuples, %NULL is returned when @type is the last item in a tuple.
1229 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
1233 const GVariantType *
1234 g_variant_type_next (const GVariantType *type)
1236 const gchar *type_string;
1238 g_return_val_if_fail (g_variant_type_check (type), NULL);
1240 type_string = g_variant_type_peek_string (type);
1241 type_string += g_variant_type_get_string_length (type);
1243 if (*type_string == ')' || *type_string == '}')
1246 return (const GVariantType *) type_string;
1250 * g_variant_type_n_items:
1251 * @type: a tuple or dictionary entry #GVariantType
1253 * Determines the number of items contained in a tuple or
1254 * dictionary entry type.
1256 * This function may only be used with tuple or dictionary entry types,
1257 * but must not be used with the generic tuple type
1258 * %G_VARIANT_TYPE_TUPLE.
1260 * In the case of a dictionary entry type, this function will always
1263 * Returns: the number of items in @type
1268 g_variant_type_n_items (const GVariantType *type)
1272 g_return_val_if_fail (g_variant_type_check (type), 0);
1274 for (type = g_variant_type_first (type);
1276 type = g_variant_type_next (type))
1283 * g_variant_type_key:
1284 * @type: a dictionary entry #GVariantType
1286 * Determines the key type of a dictionary entry type.
1288 * This function may only be used with a dictionary entry type. Other
1289 * than the additional restriction, this call is equivalent to
1290 * g_variant_type_first().
1292 * Returns: (transfer none): the key type of the dictionary entry
1296 const GVariantType *
1297 g_variant_type_key (const GVariantType *type)
1299 const gchar *type_string;
1301 g_return_val_if_fail (g_variant_type_check (type), NULL);
1303 type_string = g_variant_type_peek_string (type);
1304 g_assert (type_string[0] == '{');
1306 return (const GVariantType *) &type_string[1];
1310 * g_variant_type_value:
1311 * @type: a dictionary entry #GVariantType
1313 * Determines the value type of a dictionary entry type.
1315 * This function may only be used with a dictionary entry type.
1317 * Returns: (transfer none): the value type of the dictionary entry
1321 const GVariantType *
1322 g_variant_type_value (const GVariantType *type)
1324 const gchar *type_string;
1326 g_return_val_if_fail (g_variant_type_check (type), NULL);
1328 type_string = g_variant_type_peek_string (type);
1329 g_assert (type_string[0] == '{');
1331 return g_variant_type_next (g_variant_type_key (type));
1335 * g_variant_type_new_tuple:
1336 * @items: (array length=length): an array of #GVariantTypes, one for each item
1337 * @length: the length of @items, or -1
1339 * Constructs a new tuple type, from @items.
1341 * @length is the number of items in @items, or -1 to indicate that
1342 * @items is %NULL-terminated.
1344 * It is appropriate to call g_variant_type_free() on the return value.
1346 * Returns: (transfer full): a new tuple #GVariantType
1350 static GVariantType *
1351 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1354 /* the "slow" version is needed in case the static buffer of 1024
1355 * bytes is exceeded when running the normal version. this will
1356 * happen only in truly insane code, so it can be slow.
1361 string = g_string_new ("(");
1362 for (i = 0; i < length; i++)
1364 const GVariantType *type;
1367 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1370 size = g_variant_type_get_string_length (type);
1371 g_string_append_len (string, (const gchar *) type, size);
1373 g_string_append_c (string, ')');
1375 return (GVariantType *) g_string_free (string, FALSE);
1379 g_variant_type_new_tuple (const GVariantType * const *items,
1386 g_return_val_if_fail (length == 0 || items != NULL, NULL);
1389 for (length = 0; items[length] != NULL; length++);
1392 buffer[offset++] = '(';
1394 for (i = 0; i < length; i++)
1396 const GVariantType *type;
1399 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1402 size = g_variant_type_get_string_length (type);
1404 if (offset + size >= sizeof buffer) /* leave room for ')' */
1405 return g_variant_type_new_tuple_slow (items, length);
1407 memcpy (&buffer[offset], type, size);
1411 g_assert (offset < sizeof buffer);
1412 buffer[offset++] = ')';
1414 return (GVariantType *) g_memdup (buffer, offset);
1418 * g_variant_type_new_array: (constructor)
1419 * @element: a #GVariantType
1421 * Constructs the type corresponding to an array of elements of the
1424 * It is appropriate to call g_variant_type_free() on the return value.
1426 * Returns: (transfer full): a new array #GVariantType
1431 g_variant_type_new_array (const GVariantType *element)
1436 g_return_val_if_fail (g_variant_type_check (element), NULL);
1438 size = g_variant_type_get_string_length (element);
1439 new = g_malloc (size + 1);
1442 memcpy (new + 1, element, size);
1444 return (GVariantType *) new;
1448 * g_variant_type_new_maybe: (constructor)
1449 * @element: a #GVariantType
1451 * Constructs the type corresponding to a maybe instance containing
1452 * type @type or Nothing.
1454 * It is appropriate to call g_variant_type_free() on the return value.
1456 * Returns: (transfer full): a new maybe #GVariantType
1461 g_variant_type_new_maybe (const GVariantType *element)
1466 g_return_val_if_fail (g_variant_type_check (element), NULL);
1468 size = g_variant_type_get_string_length (element);
1469 new = g_malloc (size + 1);
1472 memcpy (new + 1, element, size);
1474 return (GVariantType *) new;
1478 * g_variant_type_new_dict_entry: (constructor)
1479 * @key: a basic #GVariantType
1480 * @value: a #GVariantType
1482 * Constructs the type corresponding to a dictionary entry with a key
1483 * of type @key and a value of type @value.
1485 * It is appropriate to call g_variant_type_free() on the return value.
1487 * Returns: (transfer full): a new dictionary entry #GVariantType
1492 g_variant_type_new_dict_entry (const GVariantType *key,
1493 const GVariantType *value)
1495 gsize keysize, valsize;
1498 g_return_val_if_fail (g_variant_type_check (key), NULL);
1499 g_return_val_if_fail (g_variant_type_check (value), NULL);
1501 keysize = g_variant_type_get_string_length (key);
1502 valsize = g_variant_type_get_string_length (value);
1504 new = g_malloc (1 + keysize + valsize + 1);
1507 memcpy (new + 1, key, keysize);
1508 memcpy (new + 1 + keysize, value, valsize);
1509 new[1 + keysize + valsize] = '}';
1511 return (GVariantType *) new;
1515 const GVariantType *
1516 g_variant_type_checked_ (const gchar *type_string)
1518 g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1519 return (const GVariantType *) type_string;
projects / platform / upstream / glib.git / blob