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