glib/gvarianttype.c

   1 /*
   2  * Copyright © 2007, 2008 Ryan Lortie
   3  * Copyright © 2009, 2010 Codethink Limited
   4  *
   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.1 of the License, or (at your option) any later version.
   9  *
  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.
  14  *
  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/>.
  17  *
  18  * Author: Ryan Lortie <desrt@desrt.ca>
  19  */
  20
  21 #include "config.h"
  22
  23 #include "gvarianttype.h"
  24
  25 #include <glib/gtestutils.h>
  26 #include <glib/gstrfuncs.h>
  27 #include <glib/gvariant-internal.h>
  28
  29 #include <string.h>
  30
  31 #include "gstrfuncsprivate.h"
  32
  33 /**
  34  * SECTION:gvarianttype
  35  * @title: GVariantType
  36  * @short_description: introduction to the GVariant type system
  37  * @see_also: #GVariantType, #GVariant
  38  *
  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
  41  * some minor lifting of restrictions. The
  42  * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
  43  * therefore, provides a significant amount of
  44  * information that is useful when working with GVariant.
  45  *
  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 "m" to type strings.
  51  *
  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 "*", "?" and "r" to type strings.
  59  *
  60  * Finally, all arbitrary restrictions relating to the complexity of
  61  * types are lifted along with the restriction that dictionary entries
  62  * may only appear nested inside of arrays.
  63  *
  64  * Just as in D-Bus, GVariant types are described with strings ("type
  65  * strings").  Subject to the differences mentioned above, these strings
  66  * are of the same form as those found in DBus.  Note, however: D-Bus
  67  * always works in terms of messages and therefore individual type
  68  * strings appear nowhere in its interface.  Instead, "signatures"
  69  * are a concatenation of the strings of the type of each argument in a
  70  * message.  GVariant deals with single values directly so GVariant type
  71  * strings always describe the type of exactly one value.  This means
  72  * that a D-Bus signature string is generally not a valid GVariant type
  73  * string -- except in the case that it is the signature of a message
  74  * containing exactly one argument.
  75  *
  76  * An indefinite type is similar in spirit to what may be called an
  77  * abstract type in other type systems.  No value can exist that has an
  78  * indefinite type as its type, but values can exist that have types
  79  * that are subtypes of indefinite types.  That is to say,
  80  * g_variant_get_type() will never return an indefinite type, but
  81  * calling g_variant_is_of_type() with an indefinite type may return
  82  * %TRUE.  For example, you cannot have a value that represents "an
  83  * array of no particular type", but you can have an "array of integers"
  84  * which certainly matches the type of "an array of no particular type",
  85  * since "array of integers" is a subtype of "array of no particular
  86  * type".
  87  *
  88  * This is similar to how instances of abstract classes may not
  89  * directly exist in other type systems, but instances of their
  90  * non-abstract subtypes may.  For example, in GTK, no object that has
  91  * the type of #GtkBin can exist (since #GtkBin is an abstract class),
  92  * but a #GtkWindow can certainly be instantiated, and you would say
  93  * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
  94  * #GtkBin).
  95  *
  96  * ## GVariant Type Strings
  97  *
  98  * A GVariant type string can be any of the following:
  99  *
 100  * - any basic type string (listed below)
 101  *
 102  * - "v", "r" or "*"
 103  *
 104  * - one of the characters 'a' or 'm', followed by another type string
 105  *
 106  * - the character '(', followed by a concatenation of zero or more other
 107  *   type strings, followed by the character ')'
 108  *
 109  * - the character '{', followed by a basic type string (see below),
 110  *   followed by another type string, followed by the character '}'
 111  *
 112  * A basic type string describes a basic type (as per
 113  * g_variant_type_is_basic()) and is always a single character in length.
 114  * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
 115  * "h", "d", "s", "o", "g" and "?".
 116  *
 117  * The above definition is recursive to arbitrary depth. "aaaaai" and
 118  * "(ui(nq((y)))s)" are both valid type strings, as is
 119  * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
 120  * imposes a limit on recursion depth of 65 nested containers. This is the
 121  * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
 122  * be nested in a top-level tuple.
 123  *
 124  * The meaning of each of the characters is as follows:
 125  * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
 126  * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
 127  * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
 128  * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
 129  * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
 130  * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
 131  * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
 132  * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
 133  * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
 134  *   that, by convention, is used as an index into an array of file
 135  *   descriptors that are sent alongside a D-Bus message.
 136  * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
 137  *   floating point value.
 138  * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
 139  * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
 140  *   of a D-Bus object path.
 141  * - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of
 142  *   a D-Bus type signature.
 143  * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
 144  *   is a supertype of any of the basic types.
 145  * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
 146  *   contain any other type of value.
 147  * - `a`: used as a prefix on another type string to mean an array of that
 148  *   type; the type string "ai", for example, is the type of an array of
 149  *   signed 32-bit integers.
 150  * - `m`: used as a prefix on another type string to mean a "maybe", or
 151  *   "nullable", version of that type; the type string "ms", for example,
 152  *   is the type of a value that maybe contains a string, or maybe contains
 153  *   nothing.
 154  * - `()`: used to enclose zero or more other concatenated type strings to
 155  *   create a tuple type; the type string "(is)", for example, is the type of
 156  *   a pair of an integer and a string.
 157  * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
 158  *   a supertype of any tuple type, regardless of the number of items.
 159  * - `{}`: used to enclose a basic type string concatenated with another type
 160  *   string to create a dictionary entry type, which usually appears inside of
 161  *   an array to form a dictionary; the type string "a{sd}", for example, is
 162  *   the type of a dictionary that maps strings to double precision floating
 163  *   point values.
 164  *
 165  *   The first type (the basic type) is the key type and the second type is
 166  *   the value type. The reason that the first type is restricted to being a
 167  *   basic type is so that it can easily be hashed.
 168  * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
 169  *   a supertype of all types.  Note that, as with all type strings, this
 170  *   character represents exactly one type. It cannot be used inside of tuples
 171  *   to mean "any number of items".
 172  *
 173  * Any type string of a container that contains an indefinite type is,
 174  * itself, an indefinite type. For example, the type string "a*"
 175  * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
 176  * that is a supertype of every array type. "(*s)" is a supertype
 177  * of all tuples that contain exactly two items where the second
 178  * item is a string.
 179  *
 180  * "a{?*}" is an indefinite type that is a supertype of all arrays
 181  * containing dictionary entries where the key is any basic type and
 182  * the value is any type at all.  This is, by definition, a dictionary,
 183  * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
 184  * that, due to the restriction that the key of a dictionary entry must
 185  * be a basic type, "{**}" is not a valid type string.
 186  */
 187
 188
 189 static gboolean
 190 g_variant_type_check (const GVariantType *type)
 191 {
 192   if (type == NULL)
 193     return FALSE;
 194
 195 #if 0
 196   return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
 197 #else
 198   return TRUE;
 199 #endif
 200 }
 201
 202 static gboolean
 203 variant_type_string_scan_internal (const gchar  *string,
 204                                    const gchar  *limit,
 205                                    const gchar **endptr,
 206                                    gsize        *depth,
 207                                    gsize         depth_limit)
 208 {
 209   gsize max_depth = 0, child_depth;
 210
 211   g_return_val_if_fail (string != NULL, FALSE);
 212
 213   if (string == limit || *string == '\0')
 214     return FALSE;
 215
 216   switch (*string++)
 217     {
 218     case '(':
 219       while (string == limit || *string != ')')
 220         {
 221           if (depth_limit == 0 ||
 222               !variant_type_string_scan_internal (string, limit, &string,
 223                                                   &child_depth,
 224                                                   depth_limit - 1))
 225             return FALSE;
 226
 227           max_depth = MAX (max_depth, child_depth + 1);
 228         }
 229
 230       string++;
 231       break;
 232
 233     case '{':
 234       if (depth_limit == 0 ||
 235           string == limit || *string == '\0' ||                                  /* { */
 236           !strchr ("bynqihuxtdsog?", *string++) ||                               /* key */
 237           !variant_type_string_scan_internal (string, limit, &string,
 238                                               &child_depth, depth_limit - 1) ||  /* value */
 239           string == limit || *string++ != '}')                                   /* } */
 240         return FALSE;
 241
 242       max_depth = MAX (max_depth, child_depth + 1);
 243       break;
 244
 245     case 'm': case 'a':
 246       if (depth_limit == 0 ||
 247           !variant_type_string_scan_internal (string, limit, &string,
 248                                               &child_depth, depth_limit - 1))
 249         return FALSE;
 250
 251       max_depth = MAX (max_depth, child_depth + 1);
 252       break;
 253
 254     case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
 255     case 'x': case 't': case 'd': case 's': case 'o': case 'g':
 256     case 'v': case 'r': case '*': case '?': case 'h':
 257       max_depth = MAX (max_depth, 1);
 258       break;
 259
 260     default:
 261       return FALSE;
 262     }
 263
 264   if (endptr != NULL)
 265     *endptr = string;
 266   if (depth != NULL)
 267     *depth = max_depth;
 268
 269   return TRUE;
 270 }
 271
 272 /**
 273  * g_variant_type_string_scan:
 274  * @string: a pointer to any string
 275  * @limit: (nullable): the end of @string, or %NULL
 276  * @endptr: (out) (optional): location to store the end pointer, or %NULL
 277  *
 278  * Scan for a single complete and valid GVariant type string in @string.
 279  * The memory pointed to by @limit (or bytes beyond it) is never
 280  * accessed.
 281  *
 282  * If a valid type string is found, @endptr is updated to point to the
 283  * first character past the end of the string that was found and %TRUE
 284  * is returned.
 285  *
 286  * If there is no valid type string starting at @string, or if the type
 287  * string does not end before @limit then %FALSE is returned.
 288  *
 289  * For the simple case of checking if a string is a valid type string,
 290  * see g_variant_type_string_is_valid().
 291  *
 292  * Returns: %TRUE if a valid type string was found
 293  *
 294  * Since: 2.24
 295  **/
 296 gboolean
 297 g_variant_type_string_scan (const gchar  *string,
 298                             const gchar  *limit,
 299                             const gchar **endptr)
 300 {
 301   return variant_type_string_scan_internal (string, limit, endptr, NULL,
 302                                             G_VARIANT_MAX_RECURSION_DEPTH);
 303 }
 304
 305 /* < private >
 306  * g_variant_type_string_get_depth_:
 307  * @type_string: a pointer to any string
 308  *
 309  * Get the maximum depth of the nested types in @type_string. A basic type will
 310  * return depth 1, and a container type will return a greater value. The depth
 311  * of a tuple is 1 plus the depth of its deepest child type.
 312  *
 313  * If @type_string is not a valid #GVariant type string, 0 will be returned.
 314  *
 315  * Returns: depth of @type_string, or 0 on error
 316  * Since: 2.60
 317  */
 318 gsize
 319 g_variant_type_string_get_depth_ (const gchar *type_string)
 320 {
 321   const gchar *endptr;
 322   gsize depth = 0;
 323
 324   g_return_val_if_fail (type_string != NULL, 0);
 325
 326   if (!variant_type_string_scan_internal (type_string, NULL, &endptr, &depth,
 327                                           G_VARIANT_MAX_RECURSION_DEPTH) ||
 328       *endptr != '\0')
 329     return 0;
 330
 331   return depth;
 332 }
 333
 334 /**
 335  * g_variant_type_string_is_valid:
 336  * @type_string: a pointer to any string
 337  *
 338  * Checks if @type_string is a valid GVariant type string.  This call is
 339  * equivalent to calling g_variant_type_string_scan() and confirming
 340  * that the following character is a nul terminator.
 341  *
 342  * Returns: %TRUE if @type_string is exactly one valid type string
 343  *
 344  * Since 2.24
 345  **/
 346 gboolean
 347 g_variant_type_string_is_valid (const gchar *type_string)
 348 {
 349   const gchar *endptr;
 350
 351   g_return_val_if_fail (type_string != NULL, FALSE);
 352
 353   if (!g_variant_type_string_scan (type_string, NULL, &endptr))
 354     return FALSE;
 355
 356   return *endptr == '\0';
 357 }
 358
 359 /**
 360  * g_variant_type_free:
 361  * @type: (nullable): a #GVariantType, or %NULL
 362  *
 363  * Frees a #GVariantType that was allocated with
 364  * g_variant_type_copy(), g_variant_type_new() or one of the container
 365  * type constructor functions.
 366  *
 367  * In the case that @type is %NULL, this function does nothing.
 368  *
 369  * Since 2.24
 370  **/
 371 void
 372 g_variant_type_free (GVariantType *type)
 373 {
 374   g_return_if_fail (type == NULL || g_variant_type_check (type));
 375
 376   g_free (type);
 377 }
 378
 379 /**
 380  * g_variant_type_copy:
 381  * @type: a #GVariantType
 382  *
 383  * Makes a copy of a #GVariantType.  It is appropriate to call
 384  * g_variant_type_free() on the return value.  @type may not be %NULL.
 385  *
 386  * Returns: (transfer full): a new #GVariantType
 387  *
 388  * Since 2.24
 389  **/
 390 GVariantType *
 391 g_variant_type_copy (const GVariantType *type)
 392 {
 393   gsize length;
 394   gchar *new;
 395
 396   g_return_val_if_fail (g_variant_type_check (type), NULL);
 397
 398   length = g_variant_type_get_string_length (type);
 399   new = g_malloc (length + 1);
 400
 401   memcpy (new, type, length);
 402   new[length] = '\0';
 403
 404   return (GVariantType *) new;
 405 }
 406
 407 /**
 408  * g_variant_type_new:
 409  * @type_string: a valid GVariant type string
 410  *
 411  * Creates a new #GVariantType corresponding to the type string given
 412  * by @type_string.  It is appropriate to call g_variant_type_free() on
 413  * the return value.
 414  *
 415  * It is a programmer error to call this function with an invalid type
 416  * string.  Use g_variant_type_string_is_valid() if you are unsure.
 417  *
 418  * Returns: (transfer full): a new #GVariantType
 419  *
 420  * Since: 2.24
 421  */
 422 GVariantType *
 423 g_variant_type_new (const gchar *type_string)
 424 {
 425   g_return_val_if_fail (type_string != NULL, NULL);
 426
 427   return g_variant_type_copy (G_VARIANT_TYPE (type_string));
 428 }
 429
 430 /**
 431  * g_variant_type_get_string_length:
 432  * @type: a #GVariantType
 433  *
 434  * Returns the length of the type string corresponding to the given
 435  * @type.  This function must be used to determine the valid extent of
 436  * the memory region returned by g_variant_type_peek_string().
 437  *
 438  * Returns: the length of the corresponding type string
 439  *
 440  * Since 2.24
 441  **/
 442 gsize
 443 g_variant_type_get_string_length (const GVariantType *type)
 444 {
 445   const gchar *type_string = (const gchar *) type;
 446   gint brackets = 0;
 447   gsize index = 0;
 448
 449   g_return_val_if_fail (g_variant_type_check (type), 0);
 450
 451   do
 452     {
 453       while (type_string[index] == 'a' || type_string[index] == 'm')
 454         index++;
 455
 456       if (type_string[index] == '(' || type_string[index] == '{')
 457         brackets++;
 458
 459       else if (type_string[index] == ')' || type_string[index] == '}')
 460         brackets--;
 461
 462       index++;
 463     }
 464   while (brackets);
 465
 466   return index;
 467 }
 468
 469 /*
 470   This function is not introspectable, it returns something that
 471   is not an array and neither a string
 472 */
 473 /**
 474  * g_variant_type_peek_string: (skip)
 475  * @type: a #GVariantType
 476  *
 477  * Returns the type string corresponding to the given @type.  The
 478  * result is not nul-terminated; in order to determine its length you
 479  * must call g_variant_type_get_string_length().
 480  *
 481  * To get a nul-terminated string, see g_variant_type_dup_string().
 482  *
 483  * Returns: the corresponding type string (not nul-terminated)
 484  *
 485  * Since 2.24
 486  **/
 487 const gchar *
 488 g_variant_type_peek_string (const GVariantType *type)
 489 {
 490   g_return_val_if_fail (g_variant_type_check (type), NULL);
 491
 492   return (const gchar *) type;
 493 }
 494
 495 /**
 496  * g_variant_type_dup_string:
 497  * @type: a #GVariantType
 498  *
 499  * Returns a newly-allocated copy of the type string corresponding to
 500  * @type.  The returned string is nul-terminated.  It is appropriate to
 501  * call g_free() on the return value.
 502  *
 503  * Returns: (transfer full): the corresponding type string
 504  *
 505  * Since 2.24
 506  **/
 507 gchar *
 508 g_variant_type_dup_string (const GVariantType *type)
 509 {
 510   g_return_val_if_fail (g_variant_type_check (type), NULL);
 511
 512   return g_strndup (g_variant_type_peek_string (type),
 513                     g_variant_type_get_string_length (type));
 514 }
 515
 516 /**
 517  * g_variant_type_is_definite:
 518  * @type: a #GVariantType
 519  *
 520  * Determines if the given @type is definite (ie: not indefinite).
 521  *
 522  * A type is definite if its type string does not contain any indefinite
 523  * type characters ('*', '?', or 'r').
 524  *
 525  * A #GVariant instance may not have an indefinite type, so calling
 526  * this function on the result of g_variant_get_type() will always
 527  * result in %TRUE being returned.  Calling this function on an
 528  * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
 529  * %FALSE being returned.
 530  *
 531  * Returns: %TRUE if @type is definite
 532  *
 533  * Since 2.24
 534  **/
 535 gboolean
 536 g_variant_type_is_definite (const GVariantType *type)
 537 {
 538   const gchar *type_string;
 539   gsize type_length;
 540   gsize i;
 541
 542   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 543
 544   type_length = g_variant_type_get_string_length (type);
 545   type_string = g_variant_type_peek_string (type);
 546
 547   for (i = 0; i < type_length; i++)
 548     if (type_string[i] == '*' ||
 549         type_string[i] == '?' ||
 550         type_string[i] == 'r')
 551       return FALSE;
 552
 553   return TRUE;
 554 }
 555
 556 /**
 557  * g_variant_type_is_container:
 558  * @type: a #GVariantType
 559  *
 560  * Determines if the given @type is a container type.
 561  *
 562  * Container types are any array, maybe, tuple, or dictionary
 563  * entry types plus the variant type.
 564  *
 565  * This function returns %TRUE for any indefinite type for which every
 566  * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
 567  * example.
 568  *
 569  * Returns: %TRUE if @type is a container type
 570  *
 571  * Since 2.24
 572  **/
 573 gboolean
 574 g_variant_type_is_container (const GVariantType *type)
 575 {
 576   gchar first_char;
 577
 578   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 579
 580   first_char = g_variant_type_peek_string (type)[0];
 581   switch (first_char)
 582   {
 583     case 'a':
 584     case 'm':
 585     case 'r':
 586     case '(':
 587     case '{':
 588     case 'v':
 589       return TRUE;
 590
 591     default:
 592       return FALSE;
 593   }
 594 }
 595
 596 /**
 597  * g_variant_type_is_basic:
 598  * @type: a #GVariantType
 599  *
 600  * Determines if the given @type is a basic type.
 601  *
 602  * Basic types are booleans, bytes, integers, doubles, strings, object
 603  * paths and signatures.
 604  *
 605  * Only a basic type may be used as the key of a dictionary entry.
 606  *
 607  * This function returns %FALSE for all indefinite types except
 608  * %G_VARIANT_TYPE_BASIC.
 609  *
 610  * Returns: %TRUE if @type is a basic type
 611  *
 612  * Since 2.24
 613  **/
 614 gboolean
 615 g_variant_type_is_basic (const GVariantType *type)
 616 {
 617   gchar first_char;
 618
 619   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 620
 621   first_char = g_variant_type_peek_string (type)[0];
 622   switch (first_char)
 623   {
 624     case 'b':
 625     case 'y':
 626     case 'n':
 627     case 'q':
 628     case 'i':
 629     case 'h':
 630     case 'u':
 631     case 't':
 632     case 'x':
 633     case 'd':
 634     case 's':
 635     case 'o':
 636     case 'g':
 637     case '?':
 638       return TRUE;
 639
 640     default:
 641       return FALSE;
 642   }
 643 }
 644
 645 /**
 646  * g_variant_type_is_maybe:
 647  * @type: a #GVariantType
 648  *
 649  * Determines if the given @type is a maybe type.  This is true if the
 650  * type string for @type starts with an 'm'.
 651  *
 652  * This function returns %TRUE for any indefinite type for which every
 653  * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
 654  * example.
 655  *
 656  * Returns: %TRUE if @type is a maybe type
 657  *
 658  * Since 2.24
 659  **/
 660 gboolean
 661 g_variant_type_is_maybe (const GVariantType *type)
 662 {
 663   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 664
 665   return g_variant_type_peek_string (type)[0] == 'm';
 666 }
 667
 668 /**
 669  * g_variant_type_is_array:
 670  * @type: a #GVariantType
 671  *
 672  * Determines if the given @type is an array type.  This is true if the
 673  * type string for @type starts with an 'a'.
 674  *
 675  * This function returns %TRUE for any indefinite type for which every
 676  * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
 677  * example.
 678  *
 679  * Returns: %TRUE if @type is an array type
 680  *
 681  * Since 2.24
 682  **/
 683 gboolean
 684 g_variant_type_is_array (const GVariantType *type)
 685 {
 686   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 687
 688   return g_variant_type_peek_string (type)[0] == 'a';
 689 }
 690
 691 /**
 692  * g_variant_type_is_tuple:
 693  * @type: a #GVariantType
 694  *
 695  * Determines if the given @type is a tuple type.  This is true if the
 696  * type string for @type starts with a '(' or if @type is
 697  * %G_VARIANT_TYPE_TUPLE.
 698  *
 699  * This function returns %TRUE for any indefinite type for which every
 700  * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
 701  * example.
 702  *
 703  * Returns: %TRUE if @type is a tuple type
 704  *
 705  * Since 2.24
 706  **/
 707 gboolean
 708 g_variant_type_is_tuple (const GVariantType *type)
 709 {
 710   gchar type_char;
 711
 712   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 713
 714   type_char = g_variant_type_peek_string (type)[0];
 715   return type_char == 'r' || type_char == '(';
 716 }
 717
 718 /**
 719  * g_variant_type_is_dict_entry:
 720  * @type: a #GVariantType
 721  *
 722  * Determines if the given @type is a dictionary entry type.  This is
 723  * true if the type string for @type starts with a '{'.
 724  *
 725  * This function returns %TRUE for any indefinite type for which every
 726  * definite subtype is a dictionary entry type --
 727  * %G_VARIANT_TYPE_DICT_ENTRY, for example.
 728  *
 729  * Returns: %TRUE if @type is a dictionary entry type
 730  *
 731  * Since 2.24
 732  **/
 733 gboolean
 734 g_variant_type_is_dict_entry (const GVariantType *type)
 735 {
 736   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 737
 738   return g_variant_type_peek_string (type)[0] == '{';
 739 }
 740
 741 /**
 742  * g_variant_type_is_variant:
 743  * @type: a #GVariantType
 744  *
 745  * Determines if the given @type is the variant type.
 746  *
 747  * Returns: %TRUE if @type is the variant type
 748  *
 749  * Since 2.24
 750  **/
 751 gboolean
 752 g_variant_type_is_variant (const GVariantType *type)
 753 {
 754   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 755
 756   return g_variant_type_peek_string (type)[0] == 'v';
 757 }
 758
 759 /**
 760  * g_variant_type_hash:
 761  * @type: (type GVariantType): a #GVariantType
 762  *
 763  * Hashes @type.
 764  *
 765  * The argument type of @type is only #gconstpointer to allow use with
 766  * #GHashTable without function pointer casting.  A valid
 767  * #GVariantType must be provided.
 768  *
 769  * Returns: the hash value
 770  *
 771  * Since 2.24
 772  **/
 773 guint
 774 g_variant_type_hash (gconstpointer type)
 775 {
 776   const gchar *type_string;
 777   guint value = 0;
 778   gsize length;
 779   gsize i;
 780
 781   g_return_val_if_fail (g_variant_type_check (type), 0);
 782
 783   type_string = g_variant_type_peek_string (type);
 784   length = g_variant_type_get_string_length (type);
 785
 786   for (i = 0; i < length; i++)
 787     value = (value << 5) - value + type_string[i];
 788
 789   return value;
 790 }
 791
 792 /**
 793  * g_variant_type_equal:
 794  * @type1: (type GVariantType): a #GVariantType
 795  * @type2: (type GVariantType): a #GVariantType
 796  *
 797  * Compares @type1 and @type2 for equality.
 798  *
 799  * Only returns %TRUE if the types are exactly equal.  Even if one type
 800  * is an indefinite type and the other is a subtype of it, %FALSE will
 801  * be returned if they are not exactly equal.  If you want to check for
 802  * subtypes, use g_variant_type_is_subtype_of().
 803  *
 804  * The argument types of @type1 and @type2 are only #gconstpointer to
 805  * allow use with #GHashTable without function pointer casting.  For
 806  * both arguments, a valid #GVariantType must be provided.
 807  *
 808  * Returns: %TRUE if @type1 and @type2 are exactly equal
 809  *
 810  * Since 2.24
 811  **/
 812 gboolean
 813 g_variant_type_equal (gconstpointer type1,
 814                       gconstpointer type2)
 815 {
 816   const gchar *string1, *string2;
 817   gsize size1, size2;
 818
 819   g_return_val_if_fail (g_variant_type_check (type1), FALSE);
 820   g_return_val_if_fail (g_variant_type_check (type2), FALSE);
 821
 822   if (type1 == type2)
 823     return TRUE;
 824
 825   size1 = g_variant_type_get_string_length (type1);
 826   size2 = g_variant_type_get_string_length (type2);
 827
 828   if (size1 != size2)
 829     return FALSE;
 830
 831   string1 = g_variant_type_peek_string (type1);
 832   string2 = g_variant_type_peek_string (type2);
 833
 834   return memcmp (string1, string2, size1) == 0;
 835 }
 836
 837 /**
 838  * g_variant_type_is_subtype_of:
 839  * @type: a #GVariantType
 840  * @supertype: a #GVariantType
 841  *
 842  * Checks if @type is a subtype of @supertype.
 843  *
 844  * This function returns %TRUE if @type is a subtype of @supertype.  All
 845  * types are considered to be subtypes of themselves.  Aside from that,
 846  * only indefinite types can have subtypes.
 847  *
 848  * Returns: %TRUE if @type is a subtype of @supertype
 849  *
 850  * Since 2.24
 851  **/
 852 gboolean
 853 g_variant_type_is_subtype_of (const GVariantType *type,
 854                               const GVariantType *supertype)
 855 {
 856   const gchar *supertype_string;
 857   const gchar *supertype_end;
 858   const gchar *type_string;
 859
 860   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 861   g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
 862
 863   supertype_string = g_variant_type_peek_string (supertype);
 864   type_string = g_variant_type_peek_string (type);
 865
 866   supertype_end = supertype_string +
 867                   g_variant_type_get_string_length (supertype);
 868
 869   /* we know that type and supertype are both well-formed, so it's
 870    * safe to treat this merely as a text processing problem.
 871    */
 872   while (supertype_string < supertype_end)
 873     {
 874       char supertype_char = *supertype_string++;
 875
 876       if (supertype_char == *type_string)
 877         type_string++;
 878
 879       else if (*type_string == ')')
 880         return FALSE;
 881
 882       else
 883         {
 884           const GVariantType *target_type = (GVariantType *) type_string;
 885
 886           switch (supertype_char)
 887             {
 888             case 'r':
 889               if (!g_variant_type_is_tuple (target_type))
 890                 return FALSE;
 891               break;
 892
 893             case '*':
 894               break;
 895
 896             case '?':
 897               if (!g_variant_type_is_basic (target_type))
 898                 return FALSE;
 899               break;
 900
 901             default:
 902               return FALSE;
 903             }
 904
 905           type_string += g_variant_type_get_string_length (target_type);
 906         }
 907     }
 908
 909   return TRUE;
 910 }
 911
 912 /**
 913  * g_variant_type_element:
 914  * @type: an array or maybe #GVariantType
 915  *
 916  * Determines the element type of an array or maybe type.
 917  *
 918  * This function may only be used with array or maybe types.
 919  *
 920  * Returns: (transfer none): the element type of @type
 921  *
 922  * Since 2.24
 923  **/
 924 const GVariantType *
 925 g_variant_type_element (const GVariantType *type)
 926 {
 927   const gchar *type_string;
 928
 929   g_return_val_if_fail (g_variant_type_check (type), NULL);
 930
 931   type_string = g_variant_type_peek_string (type);
 932
 933   g_assert (type_string[0] == 'a' || type_string[0] == 'm');
 934
 935   return (const GVariantType *) &type_string[1];
 936 }
 937
 938 /**
 939  * g_variant_type_first:
 940  * @type: a tuple or dictionary entry #GVariantType
 941  *
 942  * Determines the first item type of a tuple or dictionary entry
 943  * type.
 944  *
 945  * This function may only be used with tuple or dictionary entry types,
 946  * but must not be used with the generic tuple type
 947  * %G_VARIANT_TYPE_TUPLE.
 948  *
 949  * In the case of a dictionary entry type, this returns the type of
 950  * the key.
 951  *
 952  * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
 953  *
 954  * This call, together with g_variant_type_next() provides an iterator
 955  * interface over tuple and dictionary entry types.
 956  *
 957  * Returns: (transfer none): the first item type of @type, or %NULL
 958  *
 959  * Since 2.24
 960  **/
 961 const GVariantType *
 962 g_variant_type_first (const GVariantType *type)
 963 {
 964   const gchar *type_string;
 965
 966   g_return_val_if_fail (g_variant_type_check (type), NULL);
 967
 968   type_string = g_variant_type_peek_string (type);
 969   g_assert (type_string[0] == '(' || type_string[0] == '{');
 970
 971   if (type_string[1] == ')')
 972     return NULL;
 973
 974   return (const GVariantType *) &type_string[1];
 975 }
 976
 977 /**
 978  * g_variant_type_next:
 979  * @type: a #GVariantType from a previous call
 980  *
 981  * Determines the next item type of a tuple or dictionary entry
 982  * type.
 983  *
 984  * @type must be the result of a previous call to
 985  * g_variant_type_first() or g_variant_type_next().
 986  *
 987  * If called on the key type of a dictionary entry then this call
 988  * returns the value type.  If called on the value type of a dictionary
 989  * entry then this call returns %NULL.
 990  *
 991  * For tuples, %NULL is returned when @type is the last item in a tuple.
 992  *
 993  * Returns: (transfer none): the next #GVariantType after @type, or %NULL
 994  *
 995  * Since 2.24
 996  **/
 997 const GVariantType *
 998 g_variant_type_next (const GVariantType *type)
 999 {
1000   const gchar *type_string;
1001
1002   g_return_val_if_fail (g_variant_type_check (type), NULL);
1003
1004   type_string = g_variant_type_peek_string (type);
1005   type_string += g_variant_type_get_string_length (type);
1006
1007   if (*type_string == ')' || *type_string == '}')
1008     return NULL;
1009
1010   return (const GVariantType *) type_string;
1011 }
1012
1013 /**
1014  * g_variant_type_n_items:
1015  * @type: a tuple or dictionary entry #GVariantType
1016  *
1017  * Determines the number of items contained in a tuple or
1018  * dictionary entry type.
1019  *
1020  * This function may only be used with tuple or dictionary entry types,
1021  * but must not be used with the generic tuple type
1022  * %G_VARIANT_TYPE_TUPLE.
1023  *
1024  * In the case of a dictionary entry type, this function will always
1025  * return 2.
1026  *
1027  * Returns: the number of items in @type
1028  *
1029  * Since 2.24
1030  **/
1031 gsize
1032 g_variant_type_n_items (const GVariantType *type)
1033 {
1034   gsize count = 0;
1035
1036   g_return_val_if_fail (g_variant_type_check (type), 0);
1037
1038   for (type = g_variant_type_first (type);
1039        type;
1040        type = g_variant_type_next (type))
1041     count++;
1042
1043   return count;
1044 }
1045
1046 /**
1047  * g_variant_type_key:
1048  * @type: a dictionary entry #GVariantType
1049  *
1050  * Determines the key type of a dictionary entry type.
1051  *
1052  * This function may only be used with a dictionary entry type.  Other
1053  * than the additional restriction, this call is equivalent to
1054  * g_variant_type_first().
1055  *
1056  * Returns: (transfer none): the key type of the dictionary entry
1057  *
1058  * Since 2.24
1059  **/
1060 const GVariantType *
1061 g_variant_type_key (const GVariantType *type)
1062 {
1063   const gchar *type_string;
1064
1065   g_return_val_if_fail (g_variant_type_check (type), NULL);
1066
1067   type_string = g_variant_type_peek_string (type);
1068   g_assert (type_string[0] == '{');
1069
1070   return (const GVariantType *) &type_string[1];
1071 }
1072
1073 /**
1074  * g_variant_type_value:
1075  * @type: a dictionary entry #GVariantType
1076  *
1077  * Determines the value type of a dictionary entry type.
1078  *
1079  * This function may only be used with a dictionary entry type.
1080  *
1081  * Returns: (transfer none): the value type of the dictionary entry
1082  *
1083  * Since 2.24
1084  **/
1085 const GVariantType *
1086 g_variant_type_value (const GVariantType *type)
1087 {
1088 #ifndef G_DISABLE_ASSERT
1089   const gchar *type_string;
1090 #endif
1091
1092   g_return_val_if_fail (g_variant_type_check (type), NULL);
1093
1094 #ifndef G_DISABLE_ASSERT
1095   type_string = g_variant_type_peek_string (type);
1096   g_assert (type_string[0] == '{');
1097 #endif
1098
1099   return g_variant_type_next (g_variant_type_key (type));
1100 }
1101
1102 /**
1103  * g_variant_type_new_tuple:
1104  * @items: (array length=length): an array of #GVariantTypes, one for each item
1105  * @length: the length of @items, or -1
1106  *
1107  * Constructs a new tuple type, from @items.
1108  *
1109  * @length is the number of items in @items, or -1 to indicate that
1110  * @items is %NULL-terminated.
1111  *
1112  * It is appropriate to call g_variant_type_free() on the return value.
1113  *
1114  * Returns: (transfer full): a new tuple #GVariantType
1115  *
1116  * Since 2.24
1117  **/
1118 static GVariantType *
1119 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1120                                gint                        length)
1121 {
1122   /* the "slow" version is needed in case the static buffer of 1024
1123    * bytes is exceeded when running the normal version.  this will
1124    * happen only with very unusually large types, so it can be slow.
1125    */
1126   GString *string;
1127   gint i;
1128
1129   string = g_string_new ("(");
1130   for (i = 0; i < length; i++)
1131     {
1132       const GVariantType *type;
1133       gsize size;
1134
1135       g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1136
1137       type = items[i];
1138       size = g_variant_type_get_string_length (type);
1139       g_string_append_len (string, (const gchar *) type, size);
1140     }
1141   g_string_append_c (string, ')');
1142
1143   return (GVariantType *) g_string_free (string, FALSE);
1144 }
1145
1146 GVariantType *
1147 g_variant_type_new_tuple (const GVariantType * const *items,
1148                           gint                        length)
1149 {
1150   char buffer[1024];
1151   gsize offset;
1152   gsize i;
1153   gsize length_unsigned;
1154
1155   g_return_val_if_fail (length == 0 || items != NULL, NULL);
1156
1157   if (length < 0)
1158     for (length_unsigned = 0; items[length_unsigned] != NULL; length_unsigned++);
1159   else
1160     length_unsigned = (gsize) length;
1161
1162   offset = 0;
1163   buffer[offset++] = '(';
1164
1165   for (i = 0; i < length_unsigned; i++)
1166     {
1167       const GVariantType *type;
1168       gsize size;
1169
1170       g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1171
1172       type = items[i];
1173       size = g_variant_type_get_string_length (type);
1174
1175       if (offset + size >= sizeof buffer) /* leave room for ')' */
1176         return g_variant_type_new_tuple_slow (items, length_unsigned);
1177
1178       memcpy (&buffer[offset], type, size);
1179       offset += size;
1180     }
1181
1182   g_assert (offset < sizeof buffer);
1183   buffer[offset++] = ')';
1184
1185   return (GVariantType *) g_memdup2 (buffer, offset);
1186 }
1187
1188 /**
1189  * g_variant_type_new_array: (constructor)
1190  * @element: a #GVariantType
1191  *
1192  * Constructs the type corresponding to an array of elements of the
1193  * type @type.
1194  *
1195  * It is appropriate to call g_variant_type_free() on the return value.
1196  *
1197  * Returns: (transfer full): a new array #GVariantType
1198  *
1199  * Since 2.24
1200  **/
1201 GVariantType *
1202 g_variant_type_new_array (const GVariantType *element)
1203 {
1204   gsize size;
1205   gchar *new;
1206
1207   g_return_val_if_fail (g_variant_type_check (element), NULL);
1208
1209   size = g_variant_type_get_string_length (element);
1210   new = g_malloc (size + 1);
1211
1212   new[0] = 'a';
1213   memcpy (new + 1, element, size);
1214
1215   return (GVariantType *) new;
1216 }
1217
1218 /**
1219  * g_variant_type_new_maybe: (constructor)
1220  * @element: a #GVariantType
1221  *
1222  * Constructs the type corresponding to a maybe instance containing
1223  * type @type or Nothing.
1224  *
1225  * It is appropriate to call g_variant_type_free() on the return value.
1226  *
1227  * Returns: (transfer full): a new maybe #GVariantType
1228  *
1229  * Since 2.24
1230  **/
1231 GVariantType *
1232 g_variant_type_new_maybe (const GVariantType *element)
1233 {
1234   gsize size;
1235   gchar *new;
1236
1237   g_return_val_if_fail (g_variant_type_check (element), NULL);
1238
1239   size = g_variant_type_get_string_length (element);
1240   new = g_malloc (size + 1);
1241
1242   new[0] = 'm';
1243   memcpy (new + 1, element, size);
1244
1245   return (GVariantType *) new;
1246 }
1247
1248 /**
1249  * g_variant_type_new_dict_entry: (constructor)
1250  * @key: a basic #GVariantType
1251  * @value: a #GVariantType
1252  *
1253  * Constructs the type corresponding to a dictionary entry with a key
1254  * of type @key and a value of type @value.
1255  *
1256  * It is appropriate to call g_variant_type_free() on the return value.
1257  *
1258  * Returns: (transfer full): a new dictionary entry #GVariantType
1259  *
1260  * Since 2.24
1261  **/
1262 GVariantType *
1263 g_variant_type_new_dict_entry (const GVariantType *key,
1264                                const GVariantType *value)
1265 {
1266   gsize keysize, valsize;
1267   gchar *new;
1268
1269   g_return_val_if_fail (g_variant_type_check (key), NULL);
1270   g_return_val_if_fail (g_variant_type_check (value), NULL);
1271
1272   keysize = g_variant_type_get_string_length (key);
1273   valsize = g_variant_type_get_string_length (value);
1274
1275   new = g_malloc (1 + keysize + valsize + 1);
1276
1277   new[0] = '{';
1278   memcpy (new + 1, key, keysize);
1279   memcpy (new + 1 + keysize, value, valsize);
1280   new[1 + keysize + valsize] = '}';
1281
1282   return (GVariantType *) new;
1283 }
1284
1285 /* private */
1286 const GVariantType *
1287 g_variant_type_checked_ (const gchar *type_string)
1288 {
1289   g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1290   return (const GVariantType *) type_string;
1291 }