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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Ryan Lortie <desrt@desrt.ca>
  21  */
  22
  23 #include "config.h"
  24
  25 #include "gvarianttype.h"
  26
  27 #include <glib/gtestutils.h>
  28 #include <glib/gstrfuncs.h>
  29
  30 #include <string.h>
  31
  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 DBus 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.
  45  *
  46  * The first major change with respect to the DBus 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.
  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 DBus.  For example, it is possible to speak
  55  * of "an array of any type" in GVariant, where the DBus 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.
  60  *
  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.
  64  *
  65  * Just as in DBus, 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: DBus
  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 DBus 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.
  76  *
  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_a() with an indefinite type may return %TRUE.
  83  * For example, you can not have a value that represents "an array of no
  84  * particular type", but you can have an "array of integers" which
  85  * certainly matches the type of "an array of no particular type", since
  86  * "array of integers" is a subtype of "array of no particular 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  * A detailed description of GVariant type strings is given here:
  97  *
  98  * <refsect2 id='gvariant-typestrings'>
  99  *  <title>GVariant Type Strings</title>
 100  *  <para>
 101  *   A GVariant type string can be any of the following:
 102  *  </para>
 103  *  <itemizedlist>
 104  *   <listitem>
 105  *    <para>
 106  *     any basic type string (listed below)
 107  *    </para>
 108  *   </listitem>
 109  *   <listitem>
 110  *    <para>
 111  *     "<literal>v</literal>", "<literal>r</literal>" or
 112  *     "<literal>*</literal>"
 113  *    </para>
 114  *   </listitem>
 115  *   <listitem>
 116  *    <para>
 117  *     one of the characters '<literal>a</literal>' or
 118  *     '<literal>m</literal>', followed by another type string
 119  *    </para>
 120  *   </listitem>
 121  *   <listitem>
 122  *    <para>
 123  *     the character '<literal>(</literal>', followed by a concatenation
 124  *     of zero or more other type strings, followed by the character
 125  *     '<literal>)</literal>'
 126  *    </para>
 127  *   </listitem>
 128  *   <listitem>
 129  *    <para>
 130  *     the character '<literal>{</literal>', followed by a basic type
 131  *     string (see below), followed by another type string, followed by
 132  *     the character '<literal>}</literal>'
 133  *    </para>
 134  *   </listitem>
 135  *  </itemizedlist>
 136  *  <para>
 137  *   A basic type string describes a basic type (as per
 138  *   g_variant_type_is_basic()) and is always a single
 139  *   character in length.  The valid basic type strings are
 140  *   "<literal>b</literal>", "<literal>y</literal>",
 141  *   "<literal>n</literal>", "<literal>q</literal>",
 142  *   "<literal>i</literal>", "<literal>u</literal>",
 143  *   "<literal>x</literal>", "<literal>t</literal>",
 144  *   "<literal>h</literal>", "<literal>d</literal>",
 145  *   "<literal>s</literal>", "<literal>o</literal>",
 146  *   "<literal>g</literal>" and "<literal>?</literal>".
 147  *  </para>
 148  *  <para>
 149  *   The above definition is recursive to arbitrary depth.
 150  *   "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
 151  *   are both valid type strings, as is
 152  *   "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
 153  *  </para>
 154  *  <para>
 155  *   The meaning of each of the characters is as follows:
 156  *  </para>
 157  *  <informaltable>
 158  *   <tgroup cols='2'>
 159  *    <tbody>
 160  *     <row>
 161  *      <entry>
 162  *       <para>
 163  *        <emphasis role='strong'>Character</emphasis>
 164  *       </para>
 165  *      </entry>
 166  *      <entry>
 167  *       <para>
 168  *        <emphasis role='strong'>Meaning</emphasis>
 169  *       </para>
 170  *      </entry>
 171  *     </row>
 172  *     <row>
 173  *      <entry>
 174  *       <para>
 175  *        <literal>b</literal>
 176  *       </para>
 177  *      </entry>
 178  *      <entry>
 179  *       <para>
 180  *        the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
 181  *       </para>
 182  *      </entry>
 183  *     </row>
 184  *     <row>
 185  *      <entry>
 186  *       <para>
 187  *        <literal>y</literal>
 188  *       </para>
 189  *      </entry>
 190  *      <entry>
 191  *       <para>
 192  *        the type string of %G_VARIANT_TYPE_BYTE; a byte.
 193  *       </para>
 194  *      </entry>
 195  *     </row>
 196  *     <row>
 197  *      <entry>
 198  *       <para>
 199  *        <literal>n</literal>
 200  *       </para>
 201  *      </entry>
 202  *      <entry>
 203  *       <para>
 204  *        the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
 205  *        integer.
 206  *       </para>
 207  *      </entry>
 208  *     </row>
 209  *     <row>
 210  *      <entry>
 211  *       <para>
 212  *        <literal>q</literal>
 213  *       </para>
 214  *      </entry>
 215  *      <entry>
 216  *       <para>
 217  *        the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
 218  *        integer.
 219  *       </para>
 220  *      </entry>
 221  *     </row>
 222  *     <row>
 223  *      <entry>
 224  *       <para>
 225  *        <literal>i</literal>
 226  *       </para>
 227  *      </entry>
 228  *      <entry>
 229  *       <para>
 230  *        the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
 231  *        integer.
 232  *       </para>
 233  *      </entry>
 234  *     </row>
 235  *     <row>
 236  *      <entry>
 237  *       <para>
 238  *        <literal>u</literal>
 239  *       </para>
 240  *      </entry>
 241  *      <entry>
 242  *       <para>
 243  *        the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
 244  *        integer.
 245  *       </para>
 246  *      </entry>
 247  *     </row>
 248  *     <row>
 249  *      <entry>
 250  *       <para>
 251  *        <literal>x</literal>
 252  *       </para>
 253  *      </entry>
 254  *      <entry>
 255  *       <para>
 256  *        the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
 257  *        integer.
 258  *       </para>
 259  *      </entry>
 260  *     </row>
 261  *     <row>
 262  *      <entry>
 263  *       <para>
 264  *        <literal>t</literal>
 265  *       </para>
 266  *      </entry>
 267  *      <entry>
 268  *       <para>
 269  *        the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
 270  *        integer.
 271  *       </para>
 272  *      </entry>
 273  *     </row>
 274  *     <row>
 275  *      <entry>
 276  *       <para>
 277  *        <literal>h</literal>
 278  *       </para>
 279  *      </entry>
 280  *      <entry>
 281  *       <para>
 282  *        the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
 283  *        value that, by convention, is used as an index into an array
 284  *        of file descriptors that are sent alongside a DBus message.
 285  *       </para>
 286  *      </entry>
 287  *     </row>
 288  *     <row>
 289  *      <entry>
 290  *       <para>
 291  *        <literal>d</literal>
 292  *       </para>
 293  *      </entry>
 294  *      <entry>
 295  *       <para>
 296  *        the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
 297  *        floating point value.
 298  *       </para>
 299  *      </entry>
 300  *     </row>
 301  *     <row>
 302  *      <entry>
 303  *       <para>
 304  *        <literal>s</literal>
 305  *       </para>
 306  *      </entry>
 307  *      <entry>
 308  *       <para>
 309  *        the type string of %G_VARIANT_TYPE_STRING; a string.
 310  *       </para>
 311  *      </entry>
 312  *     </row>
 313  *     <row>
 314  *      <entry>
 315  *       <para>
 316  *        <literal>o</literal>
 317  *       </para>
 318  *      </entry>
 319  *      <entry>
 320  *       <para>
 321  *        the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
 322  *        the form of a DBus object path.
 323  *       </para>
 324  *      </entry>
 325  *     </row>
 326  *     <row>
 327  *      <entry>
 328  *       <para>
 329  *        <literal>g</literal>
 330  *       </para>
 331  *      </entry>
 332  *      <entry>
 333  *       <para>
 334  *        the type string of %G_VARIANT_TYPE_STRING; a string in the
 335  *        form of a DBus type signature.
 336  *       </para>
 337  *      </entry>
 338  *     </row>
 339  *     <row>
 340  *      <entry>
 341  *       <para>
 342  *        <literal>?</literal>
 343  *       </para>
 344  *      </entry>
 345  *      <entry>
 346  *       <para>
 347  *        the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
 348  *        that is a supertype of any of the basic types.
 349  *       </para>
 350  *      </entry>
 351  *     </row>
 352  *     <row>
 353  *      <entry>
 354  *       <para>
 355  *        <literal>v</literal>
 356  *       </para>
 357  *      </entry>
 358  *      <entry>
 359  *       <para>
 360  *        the type string of %G_VARIANT_TYPE_VARIANT; a container type
 361  *        that contain any other type of value.
 362  *       </para>
 363  *      </entry>
 364  *     </row>
 365  *     <row>
 366  *      <entry>
 367  *       <para>
 368  *        <literal>a</literal>
 369  *       </para>
 370  *      </entry>
 371  *      <entry>
 372  *       <para>
 373  *        used as a prefix on another type string to mean an array of
 374  *        that type; the type string "<literal>ai</literal>", for
 375  *        example, is the type of an array of 32 bit signed integers.
 376  *       </para>
 377  *      </entry>
 378  *     </row>
 379  *     <row>
 380  *      <entry>
 381  *       <para>
 382  *        <literal>m</literal>
 383  *       </para>
 384  *      </entry>
 385  *      <entry>
 386  *       <para>
 387  *        used as a prefix on another type string to mean a "maybe", or
 388  *        "nullable", version of that type; the type string
 389  *        "<literal>ms</literal>", for example, is the type of a value
 390  *        that maybe contains a string, or maybe contains nothing.
 391  *       </para>
 392  *      </entry>
 393  *     </row>
 394  *     <row>
 395  *      <entry>
 396  *       <para>
 397  *        <literal>()</literal>
 398  *       </para>
 399  *      </entry>
 400  *      <entry>
 401  *       <para>
 402  *        used to enclose zero or more other concatenated type strings
 403  *        to create a tuple type; the type string
 404  *        "<literal>(is)</literal>", for example, is the type of a pair
 405  *        of an integer and a string.
 406  *       </para>
 407  *      </entry>
 408  *     </row>
 409  *     <row>
 410  *      <entry>
 411  *       <para>
 412  *        <literal>r</literal>
 413  *       </para>
 414  *      </entry>
 415  *      <entry>
 416  *       <para>
 417  *        the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
 418  *        that is a supertype of any tuple type, regardless of the
 419  *        number of items.
 420  *       </para>
 421  *      </entry>
 422  *     </row>
 423  *     <row>
 424  *      <entry>
 425  *       <para>
 426  *        <literal>{}</literal>
 427  *       </para>
 428  *      </entry>
 429  *      <entry>
 430  *       <para>
 431  *        used to enclose a basic type string concatenated with another
 432  *        type string to create a dictionary entry type, which usually
 433  *        appears inside of an array to form a dictionary; the type
 434  *        string "<literal>a{sd}</literal>", for example, is the type of
 435  *        a dictionary that maps strings to double precision floating
 436  *        point values.
 437  *       </para>
 438  *       <para>
 439  *        The first type (the basic type) is the key type and the second
 440  *        type is the value type.  The reason that the first type is
 441  *        restricted to being a basic type is so that it can easily be
 442  *        hashed.
 443  *       </para>
 444  *      </entry>
 445  *     </row>
 446  *     <row>
 447  *      <entry>
 448  *       <para>
 449  *        <literal>*</literal>
 450  *       </para>
 451  *      </entry>
 452  *      <entry>
 453  *       <para>
 454  *        the type string of %G_VARIANT_TYPE_ANY; the indefinite type
 455  *        that is a supertype of all types.  Note that, as with all type
 456  *        strings, this character represents exactly one type.  It
 457  *        cannot be used inside of tuples to mean "any number of items".
 458  *       </para>
 459  *      </entry>
 460  *     </row>
 461  *    </tbody>
 462  *   </tgroup>
 463  *  </informaltable>
 464  *  <para>
 465  *   Any type string of a container that contains an indefinite type is,
 466  *   itself, an indefinite type.  For example, the type string
 467  *   "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
 468  *   an indefinite type that is a supertype of every array type.
 469  *   "<literal>(*s)</literal>" is a supertype of all tuples that
 470  *   contain exactly two items where the second item is a string.
 471  *  </para>
 472  *  <para>
 473  *   "<literal>a{?*}</literal>" is an indefinite type that is a
 474  *   supertype of all arrays containing dictionary entries where the key
 475  *   is any basic type and the value is any type at all.  This is, by
 476  *   definition, a dictionary, so this type string corresponds to
 477  *   %G_VARIANT_TYPE_DICTIONARY.  Note that, due to the restriction that
 478  *   the key of a dictionary entry must be a basic type,
 479  *   "<literal>{**}</literal>" is not a valid type string.
 480  *  </para>
 481  * </refsect2>
 482  */
 483
 484
 485 static gboolean
 486 g_variant_type_check (const GVariantType *type)
 487 {
 488   const gchar *type_string;
 489
 490   if (type == NULL)
 491     return FALSE;
 492
 493   type_string = (const gchar *) type;
 494 #ifndef G_DISABLE_CHECKS
 495   return g_variant_type_string_scan (type_string, NULL, NULL);
 496 #else
 497   return TRUE;
 498 #endif
 499 }
 500
 501 /**
 502  * g_variant_type_string_scan:
 503  * @string: a pointer to any string
 504  * @limit: the end of @string, or %NULL
 505  * @endptr: location to store the end pointer, or %NULL
 506  * @returns: %TRUE if a valid type string was found
 507  *
 508  * Scan for a single complete and valid GVariant type string in @string.
 509  * The memory pointed to by @limit (or bytes beyond it) is never
 510  * accessed.
 511  *
 512  * If a valid type string is found, @endptr is updated to point to the
 513  * first character past the end of the string that was found and %TRUE
 514  * is returned.
 515  *
 516  * If there is no valid type string starting at @string, or if the type
 517  * string does not end before @limit then %FALSE is returned.
 518  *
 519  * For the simple case of checking if a string is a valid type string,
 520  * see g_variant_type_string_is_valid().
 521  *
 522  * Since: 2.24
 523  **/
 524 gboolean
 525 g_variant_type_string_scan (const gchar  *string,
 526                             const gchar  *limit,
 527                             const gchar **endptr)
 528 {
 529   g_return_val_if_fail (string != NULL, FALSE);
 530
 531   if (string == limit || *string == '\0')
 532     return FALSE;
 533
 534   switch (*string++)
 535     {
 536     case '(':
 537       while (string == limit || *string != ')')
 538         if (!g_variant_type_string_scan (string, limit, &string))
 539           return FALSE;
 540
 541       string++;
 542       break;
 543
 544     case '{':
 545       if (string == limit || *string == '\0' ||                    /* { */
 546           !strchr ("bynqihuxtdsog?", *string++) ||                 /* key */
 547           !g_variant_type_string_scan (string, limit, &string) ||  /* value */
 548           string == limit || *string++ != '}')                     /* } */
 549         return FALSE;
 550
 551       break;
 552
 553     case 'm': case 'a':
 554       return g_variant_type_string_scan (string, limit, endptr);
 555
 556     case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
 557     case 'x': case 't': case 'd': case 's': case 'o': case 'g':
 558     case 'v': case 'r': case '*': case '?': case 'h':
 559       break;
 560
 561     default:
 562       return FALSE;
 563     }
 564
 565   if (endptr != NULL)
 566     *endptr = string;
 567
 568   return TRUE;
 569 }
 570
 571 /**
 572  * g_variant_type_string_is_valid:
 573  * @type_string: a pointer to any string
 574  * @returns: %TRUE if @type_string is exactly one valid type string
 575  *
 576  * Checks if @type_string is a valid GVariant type string.  This call is
 577  * equivalent to calling g_variant_type_string_scan() and confirming
 578  * that the following character is a nul terminator.
 579  *
 580  * Since 2.24
 581  **/
 582 gboolean
 583 g_variant_type_string_is_valid (const gchar *type_string)
 584 {
 585   const gchar *endptr;
 586
 587   g_return_val_if_fail (type_string != NULL, FALSE);
 588
 589   if (!g_variant_type_string_scan (type_string, NULL, &endptr))
 590     return FALSE;
 591
 592   return *endptr == '\0';
 593 }
 594
 595 /**
 596  * g_variant_type_free:
 597  * @type: a #GVariantType, or %NULL
 598  *
 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.
 602  *
 603  * In the case that @type is %NULL, this function does nothing.
 604  *
 605  * Since 2.24
 606  **/
 607 void
 608 g_variant_type_free (GVariantType *type)
 609 {
 610   g_return_if_fail (type == NULL || g_variant_type_check (type));
 611
 612   g_free (type);
 613 }
 614
 615 /**
 616  * g_variant_type_copy:
 617  * @type: a #GVariantType
 618  * @returns: a new #GVariantType
 619  *
 620  * Makes a copy of a #GVariantType.  It is appropriate to call
 621  * g_variant_type_free() on the return value.  @type may not be %NULL.
 622  *
 623  * Since 2.24
 624  **/
 625 GVariantType *
 626 g_variant_type_copy (const GVariantType *type)
 627 {
 628   gsize length;
 629   gchar *new;
 630
 631   g_return_val_if_fail (g_variant_type_check (type), NULL);
 632
 633   length = g_variant_type_get_string_length (type);
 634   new = g_malloc (length + 1);
 635
 636   memcpy (new, type, length);
 637   new[length] = '\0';
 638
 639   return (GVariantType *) new;
 640 }
 641
 642 /**
 643  * g_variant_type_new:
 644  * @type_string: a valid GVariant type string
 645  * @returns: a new #GVariantType
 646  *
 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
 649  * the return value.
 650  *
 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.
 653  *
 654  * Since: 2.24
 655  */
 656 GVariantType *
 657 g_variant_type_new (const gchar *type_string)
 658 {
 659   g_return_val_if_fail (type_string != NULL, NULL);
 660
 661   return g_variant_type_copy (G_VARIANT_TYPE (type_string));
 662 }
 663
 664 /**
 665  * g_variant_type_get_string_length:
 666  * @type: a #GVariantType
 667  * @returns: the length of the corresponding type string
 668  *
 669  * Returns the length of the type string corresponding to the given
 670  * @type.  This function must be used to determine the valid extent of
 671  * the memory region returned by g_variant_type_peek_string().
 672  *
 673  * Since 2.24
 674  **/
 675 gsize
 676 g_variant_type_get_string_length (const GVariantType *type)
 677 {
 678   const gchar *type_string = (const gchar *) type;
 679   gint brackets = 0;
 680   gsize index = 0;
 681
 682   g_return_val_if_fail (g_variant_type_check (type), 0);
 683
 684   do
 685     {
 686       while (type_string[index] == 'a' || type_string[index] == 'm')
 687         index++;
 688
 689       if (type_string[index] == '(' || type_string[index] == '{')
 690         brackets++;
 691
 692       else if (type_string[index] == ')' || type_string[index] == '}')
 693         brackets--;
 694
 695       index++;
 696     }
 697   while (brackets);
 698
 699   return index;
 700 }
 701
 702 /**
 703  * g_variant_type_peek_string:
 704  * @type: a #GVariantType
 705  * @returns: the corresponding type string (not nul-terminated)
 706  *
 707  * Returns the type string corresponding to the given @type.  The
 708  * result is not nul-terminated; in order to determine its length you
 709  * must call g_variant_type_get_string_length().
 710  *
 711  * To get a nul-terminated string, see g_variant_type_dup_string().
 712  *
 713  * Since 2.24
 714  **/
 715 const gchar *
 716 g_variant_type_peek_string (const GVariantType *type)
 717 {
 718   g_return_val_if_fail (g_variant_type_check (type), NULL);
 719
 720   return (const gchar *) type;
 721 }
 722
 723 /**
 724  * g_variant_type_dup_string:
 725  * @type: a #GVariantType
 726  * @returns: the corresponding type string
 727  *
 728  * Returns a newly-allocated copy of the type string corresponding to
 729  * @type.  The returned string is nul-terminated.  It is appropriate to
 730  * call g_free() on the return value.
 731  *
 732  * Since 2.24
 733  **/
 734 gchar *
 735 g_variant_type_dup_string (const GVariantType *type)
 736 {
 737   g_return_val_if_fail (g_variant_type_check (type), NULL);
 738
 739   return g_strndup (g_variant_type_peek_string (type),
 740                     g_variant_type_get_string_length (type));
 741 }
 742
 743 /**
 744  * g_variant_type_is_definite:
 745  * @type: a #GVariantType
 746  * @returns: %TRUE if @type is definite
 747  *
 748  * Determines if the given @type is definite (ie: not indefinite).
 749  *
 750  * A type is definite if its type string does not contain any indefinite
 751  * type characters ('*', '?', or 'r').
 752  *
 753  * A #GVariant instance may not have an indefinite type, so calling
 754  * this function on the result of g_variant_get_type() will always
 755  * result in %TRUE being returned.  Calling this function on an
 756  * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
 757  * %FALSE being returned.
 758  *
 759  * Since 2.24
 760  **/
 761 gboolean
 762 g_variant_type_is_definite (const GVariantType *type)
 763 {
 764   const gchar *type_string;
 765   gsize type_length;
 766   gsize i;
 767
 768   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 769
 770   type_length = g_variant_type_get_string_length (type);
 771   type_string = g_variant_type_peek_string (type);
 772
 773   for (i = 0; i < type_length; i++)
 774     if (type_string[i] == '*' ||
 775         type_string[i] == '?' ||
 776         type_string[i] == 'r')
 777       return FALSE;
 778
 779   return TRUE;
 780 }
 781
 782 /**
 783  * g_variant_type_is_container:
 784  * @type: a #GVariantType
 785  * @returns: %TRUE if @type is a container type
 786  *
 787  * Determines if the given @type is a container type.
 788  *
 789  * Container types are any array, maybe, tuple, or dictionary
 790  * entry types plus the variant type.
 791  *
 792  * This function returns %TRUE for any indefinite type for which every
 793  * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
 794  * example.
 795  *
 796  * Since 2.24
 797  **/
 798 gboolean
 799 g_variant_type_is_container (const GVariantType *type)
 800 {
 801   gchar first_char;
 802
 803   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 804
 805   first_char = g_variant_type_peek_string (type)[0];
 806   switch (first_char)
 807   {
 808     case 'a':
 809     case 'm':
 810     case 'r':
 811     case '(':
 812     case '{':
 813     case 'v':
 814       return TRUE;
 815
 816     default:
 817       return FALSE;
 818   }
 819 }
 820
 821 /**
 822  * g_variant_type_is_basic:
 823  * @type: a #GVariantType
 824  * @returns: %TRUE if @type is a basic type
 825  *
 826  * Determines if the given @type is a basic type.
 827  *
 828  * Basic types are booleans, bytes, integers, doubles, strings, object
 829  * paths and signatures.
 830  *
 831  * Only a basic type may be used as the key of a dictionary entry.
 832  *
 833  * This function returns %FALSE for all indefinite types except
 834  * %G_VARIANT_TYPE_BASIC.
 835  *
 836  * Since 2.24
 837  **/
 838 gboolean
 839 g_variant_type_is_basic (const GVariantType *type)
 840 {
 841   gchar first_char;
 842
 843   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 844
 845   first_char = g_variant_type_peek_string (type)[0];
 846   switch (first_char)
 847   {
 848     case 'b':
 849     case 'y':
 850     case 'n':
 851     case 'q':
 852     case 'i':
 853     case 'h':
 854     case 'u':
 855     case 't':
 856     case 'x':
 857     case 'd':
 858     case 's':
 859     case 'o':
 860     case 'g':
 861     case '?':
 862       return TRUE;
 863
 864     default:
 865       return FALSE;
 866   }
 867 }
 868
 869 /**
 870  * g_variant_type_is_maybe:
 871  * @type: a #GVariantType
 872  * @returns: %TRUE if @type is a maybe type
 873  *
 874  * Determines if the given @type is a maybe type.  This is true if the
 875  * type string for @type starts with an 'm'.
 876  *
 877  * This function returns %TRUE for any indefinite type for which every
 878  * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
 879  * example.
 880  *
 881  * Since 2.24
 882  **/
 883 gboolean
 884 g_variant_type_is_maybe (const GVariantType *type)
 885 {
 886   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 887
 888   return g_variant_type_peek_string (type)[0] == 'm';
 889 }
 890
 891 /**
 892  * g_variant_type_is_array:
 893  * @type: a #GVariantType
 894  * @returns: %TRUE if @type is an array type
 895  *
 896  * Determines if the given @type is an array type.  This is true if the
 897  * type string for @type starts with an 'a'.
 898  *
 899  * This function returns %TRUE for any indefinite type for which every
 900  * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
 901  * example.
 902  *
 903  * Since 2.24
 904  **/
 905 gboolean
 906 g_variant_type_is_array (const GVariantType *type)
 907 {
 908   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 909
 910   return g_variant_type_peek_string (type)[0] == 'a';
 911 }
 912
 913 /**
 914  * g_variant_type_is_tuple:
 915  * @type: a #GVariantType
 916  * @returns: %TRUE if @type is a tuple type
 917  *
 918  * Determines if the given @type is a tuple type.  This is true if the
 919  * type string for @type starts with a '(' or if @type is
 920  * %G_VARIANT_TYPE_TUPLE.
 921  *
 922  * This function returns %TRUE for any indefinite type for which every
 923  * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
 924  * example.
 925  *
 926  * Since 2.24
 927  **/
 928 gboolean
 929 g_variant_type_is_tuple (const GVariantType *type)
 930 {
 931   gchar type_char;
 932
 933   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 934
 935   type_char = g_variant_type_peek_string (type)[0];
 936   return type_char == 'r' || type_char == '(';
 937 }
 938
 939 /**
 940  * g_variant_type_is_dict_entry:
 941  * @type: a #GVariantType
 942  * @returns: %TRUE if @type is a dictionary entry type
 943  *
 944  * Determines if the given @type is a dictionary entry type.  This is
 945  * true if the type string for @type starts with a '{'.
 946  *
 947  * This function returns %TRUE for any indefinite type for which every
 948  * definite subtype is a dictionary entry type --
 949  * %G_VARIANT_TYPE_DICT_ENTRY, for example.
 950  *
 951  * Since 2.24
 952  **/
 953 gboolean
 954 g_variant_type_is_dict_entry (const GVariantType *type)
 955 {
 956   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 957
 958   return g_variant_type_peek_string (type)[0] == '{';
 959 }
 960
 961 /**
 962  * g_variant_type_is_variant:
 963  * @type: a #GVariantType
 964  * @returns: %TRUE if @type is the variant type
 965  *
 966  * Determines if the given @type is the variant type.
 967  *
 968  * Since 2.24
 969  **/
 970 gboolean
 971 g_variant_type_is_variant (const GVariantType *type)
 972 {
 973   g_return_val_if_fail (g_variant_type_check (type), FALSE);
 974
 975   return g_variant_type_peek_string (type)[0] == 'v';
 976 }
 977
 978 /**
 979  * g_variant_type_hash:
 980  * @type: a #GVariantType
 981  * @returns: the hash value
 982  *
 983  * Hashes @type.
 984  *
 985  * The argument type of @type is only #gconstpointer to allow use with
 986  * #GHashTable without function pointer casting.  A valid
 987  * #GVariantType must be provided.
 988  *
 989  * Since 2.24
 990  **/
 991 guint
 992 g_variant_type_hash (gconstpointer type)
 993 {
 994   const gchar *type_string;
 995   guint value = 0;
 996   gsize length;
 997   gsize i;
 998
 999   g_return_val_if_fail (g_variant_type_check (type), 0);
1000
1001   type_string = g_variant_type_peek_string (type);
1002   length = g_variant_type_get_string_length (type);
1003
1004   for (i = 0; i < length; i++)
1005     value = (value << 5) - value + type_string[i];
1006
1007   return value;
1008 }
1009
1010 /**
1011  * g_variant_type_equal:
1012  * @type1: a #GVariantType
1013  * @type2: a #GVariantType
1014  * @returns: %TRUE if @type1 and @type2 are exactly equal
1015  *
1016  * Compares @type1 and @type2 for equality.
1017  *
1018  * Only returns %TRUE if the types are exactly equal.  Even if one type
1019  * is an indefinite type and the other is a subtype of it, %FALSE will
1020  * be returned if they are not exactly equal.  If you want to check for
1021  * subtypes, use g_variant_type_is_subtype_of().
1022  *
1023  * The argument types of @type1 and @type2 are only #gconstpointer to
1024  * allow use with #GHashTable without function pointer casting.  For
1025  * both arguments, a valid #GVariantType must be provided.
1026  *
1027  * Since 2.24
1028  **/
1029 gboolean
1030 g_variant_type_equal (gconstpointer type1,
1031                       gconstpointer type2)
1032 {
1033   const gchar *string1, *string2;
1034   gsize size1, size2;
1035
1036   g_return_val_if_fail (g_variant_type_check (type1), FALSE);
1037   g_return_val_if_fail (g_variant_type_check (type2), FALSE);
1038
1039   if (type1 == type2)
1040     return TRUE;
1041
1042   size1 = g_variant_type_get_string_length (type1);
1043   size2 = g_variant_type_get_string_length (type2);
1044
1045   if (size1 != size2)
1046     return FALSE;
1047
1048   string1 = g_variant_type_peek_string (type1);
1049   string2 = g_variant_type_peek_string (type2);
1050
1051   return memcmp (string1, string2, size1) == 0;
1052 }
1053
1054 /**
1055  * g_variant_type_is_subtype_of:
1056  * @type: a #GVariantType
1057  * @supertype: a #GVariantType
1058  * @returns: %TRUE if @type is a subtype of @supertype
1059  *
1060  * Checks if @type is a subtype of @supertype.
1061  *
1062  * This function returns %TRUE if @type is a subtype of @supertype.  All
1063  * types are considered to be subtypes of themselves.  Aside from that,
1064  * only indefinite types can have subtypes.
1065  *
1066  * Since 2.24
1067  **/
1068 gboolean
1069 g_variant_type_is_subtype_of (const GVariantType *type,
1070                               const GVariantType *supertype)
1071 {
1072   const gchar *supertype_string;
1073   const gchar *supertype_end;
1074   const gchar *type_string;
1075
1076   g_return_val_if_fail (g_variant_type_check (type), FALSE);
1077   g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
1078
1079   supertype_string = g_variant_type_peek_string (supertype);
1080   type_string = g_variant_type_peek_string (type);
1081
1082   supertype_end = supertype_string +
1083                   g_variant_type_get_string_length (supertype);
1084
1085   /* we know that type and supertype are both well-formed, so it's
1086    * safe to treat this merely as a text processing problem.
1087    */
1088   while (supertype_string < supertype_end)
1089     {
1090       char supertype_char = *supertype_string++;
1091
1092       if (supertype_char == *type_string)
1093         type_string++;
1094
1095       else if (*type_string == ')')
1096         return FALSE;
1097
1098       else
1099         {
1100           const GVariantType *target_type = (GVariantType *) type_string;
1101
1102           switch (supertype_char)
1103             {
1104             case 'r':
1105               if (!g_variant_type_is_tuple (target_type))
1106                 return FALSE;
1107               break;
1108
1109             case '*':
1110               break;
1111
1112             case '?':
1113               if (!g_variant_type_is_basic (target_type))
1114                 return FALSE;
1115               break;
1116
1117             default:
1118               return FALSE;
1119             }
1120
1121           type_string += g_variant_type_get_string_length (target_type);
1122         }
1123     }
1124
1125   return TRUE;
1126 }
1127
1128 /**
1129  * g_variant_type_element:
1130  * @type: an array or maybe #GVariantType
1131  * @returns: the element type of @type
1132  *
1133  * Determines the element type of an array or maybe type.
1134  *
1135  * This function may only be used with array or maybe types.
1136  *
1137  * Since 2.24
1138  **/
1139 const GVariantType *
1140 g_variant_type_element (const GVariantType *type)
1141 {
1142   const gchar *type_string;
1143
1144   g_return_val_if_fail (g_variant_type_check (type), NULL);
1145
1146   type_string = g_variant_type_peek_string (type);
1147
1148   g_assert (type_string[0] == 'a' || type_string[0] == 'm');
1149
1150   return (const GVariantType *) &type_string[1];
1151 }
1152
1153 /**
1154  * g_variant_type_first:
1155  * @type: a tuple or dictionary entry #GVariantType
1156  * @returns: the first item type of @type, or %NULL
1157  *
1158  * Determines the first item type of a tuple or dictionary entry
1159  * type.
1160  *
1161  * This function may only be used with tuple or dictionary entry types,
1162  * but must not be used with the generic tuple type
1163  * %G_VARIANT_TYPE_TUPLE.
1164  *
1165  * In the case of a dictionary entry type, this returns the type of
1166  * the key.
1167  *
1168  * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
1169  *
1170  * This call, together with g_variant_type_next() provides an iterator
1171  * interface over tuple and dictionary entry types.
1172  *
1173  * Since 2.24
1174  **/
1175 const GVariantType *
1176 g_variant_type_first (const GVariantType *type)
1177 {
1178   const gchar *type_string;
1179
1180   g_return_val_if_fail (g_variant_type_check (type), NULL);
1181
1182   type_string = g_variant_type_peek_string (type);
1183   g_assert (type_string[0] == '(' || type_string[0] == '{');
1184
1185   if (type_string[1] == ')')
1186     return NULL;
1187
1188   return (const GVariantType *) &type_string[1];
1189 }
1190
1191 /**
1192  * g_variant_type_next:
1193  * @type: a #GVariantType from a previous call
1194  * @returns: the next #GVariantType after @type, or %NULL
1195  *
1196  * Determines the next item type of a tuple or dictionary entry
1197  * type.
1198  *
1199  * @type must be the result of a previous call to
1200  * g_variant_type_first() or g_variant_type_next().
1201  *
1202  * If called on the key type of a dictionary entry then this call
1203  * returns the value type.  If called on the value type of a dictionary
1204  * entry then this call returns %NULL.
1205  *
1206  * For tuples, %NULL is returned when @type is the last item in a tuple.
1207  *
1208  * Since 2.24
1209  **/
1210 const GVariantType *
1211 g_variant_type_next (const GVariantType *type)
1212 {
1213   const gchar *type_string;
1214
1215   g_return_val_if_fail (g_variant_type_check (type), NULL);
1216
1217   type_string = g_variant_type_peek_string (type);
1218   type_string += g_variant_type_get_string_length (type);
1219
1220   if (*type_string == ')' || *type_string == '}')
1221     return NULL;
1222
1223   return (const GVariantType *) type_string;
1224 }
1225
1226 /**
1227  * g_variant_type_n_items:
1228  * @type: a tuple or dictionary entry #GVariantType
1229  * @returns: the number of items in @type
1230  *
1231  * Determines the number of items contained in a tuple or
1232  * dictionary entry type.
1233  *
1234  * This function may only be used with tuple or dictionary entry types,
1235  * but must not be used with the generic tuple type
1236  * %G_VARIANT_TYPE_TUPLE.
1237  *
1238  * In the case of a dictionary entry type, this function will always
1239  * return 2.
1240  *
1241  * Since 2.24
1242  **/
1243 gsize
1244 g_variant_type_n_items (const GVariantType *type)
1245 {
1246   gsize count = 0;
1247
1248   g_return_val_if_fail (g_variant_type_check (type), 0);
1249
1250   for (type = g_variant_type_first (type);
1251        type;
1252        type = g_variant_type_next (type))
1253     count++;
1254
1255   return count;
1256 }
1257
1258 /**
1259  * g_variant_type_key:
1260  * @type: a dictionary entry #GVariantType
1261  * @returns: the key type of the dictionary entry
1262  *
1263  * Determines the key type of a dictionary entry type.
1264  *
1265  * This function may only be used with a dictionary entry type.  Other
1266  * than the additional restriction, this call is equivalent to
1267  * g_variant_type_first().
1268  *
1269  * Since 2.24
1270  **/
1271 const GVariantType *
1272 g_variant_type_key (const GVariantType *type)
1273 {
1274   const gchar *type_string;
1275
1276   g_return_val_if_fail (g_variant_type_check (type), NULL);
1277
1278   type_string = g_variant_type_peek_string (type);
1279   g_assert (type_string[0] == '{');
1280
1281   return (const GVariantType *) &type_string[1];
1282 }
1283
1284 /**
1285  * g_variant_type_value:
1286  * @type: a dictionary entry #GVariantType
1287  * @returns: the value type of the dictionary entry
1288  *
1289  * Determines the value type of a dictionary entry type.
1290  *
1291  * This function may only be used with a dictionary entry type.
1292  *
1293  * Since 2.24
1294  **/
1295 const GVariantType *
1296 g_variant_type_value (const GVariantType *type)
1297 {
1298   const gchar *type_string;
1299
1300   g_return_val_if_fail (g_variant_type_check (type), NULL);
1301
1302   type_string = g_variant_type_peek_string (type);
1303   g_assert (type_string[0] == '{');
1304
1305   return g_variant_type_next (g_variant_type_key (type));
1306 }
1307
1308 /**
1309  * g_variant_type_new_tuple:
1310  * @items: an array of #GVariantTypes, one for each item
1311  * @length: the length of @items, or -1
1312  * @returns: a new tuple #GVariantType
1313  *
1314  * Constructs a new tuple type, from @items.
1315  *
1316  * @length is the number of items in @items, or -1 to indicate that
1317  * @items is %NULL-terminated.
1318  *
1319  * It is appropriate to call g_variant_type_free() on the return value.
1320  *
1321  * Since 2.24
1322  **/
1323 static GVariantType *
1324 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1325                                gint                        length)
1326 {
1327   /* the "slow" version is needed in case the static buffer of 1024
1328    * bytes is exceeded when running the normal version.  this will
1329    * happen only in truly insane code, so it can be slow.
1330    */
1331   GString *string;
1332   gsize i;
1333
1334   string = g_string_new ("(");
1335   for (i = 0; i < length; i++)
1336     {
1337       const GVariantType *type;
1338       gsize size;
1339
1340       g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1341
1342       type = items[i];
1343       size = g_variant_type_get_string_length (type);
1344       g_string_append_len (string, (const gchar *) type, size);
1345     }
1346   g_string_append_c (string, ')');
1347
1348   return (GVariantType *) g_string_free (string, FALSE);
1349 }
1350
1351 GVariantType *
1352 g_variant_type_new_tuple (const GVariantType * const *items,
1353                           gint                        length)
1354 {
1355   char buffer[1024];
1356   gsize offset;
1357   gsize i;
1358
1359   g_return_val_if_fail (length == 0 || items != NULL, NULL);
1360
1361   if (length < 0)
1362     for (length = 0; items[length] != NULL; length++);
1363
1364   offset = 0;
1365   buffer[offset++] = '(';
1366
1367   for (i = 0; i < length; i++)
1368     {
1369       const GVariantType *type;
1370       gsize size;
1371
1372       g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1373
1374       type = items[i];
1375       size = g_variant_type_get_string_length (type);
1376
1377       if (offset + size >= sizeof buffer) /* leave room for ')' */
1378         return g_variant_type_new_tuple_slow (items, length);
1379
1380       memcpy (&buffer[offset], type, size);
1381       offset += size;
1382     }
1383
1384   g_assert (offset < sizeof buffer);
1385   buffer[offset++] = ')';
1386
1387   return (GVariantType *) g_memdup (buffer, offset);
1388 }
1389
1390 /**
1391  * g_variant_type_new_array:
1392  * @element: a #GVariantType
1393  * @returns: a new array #GVariantType
1394  *
1395  * Constructs the type corresponding to an array of elements of the
1396  * type @type.
1397  *
1398  * It is appropriate to call g_variant_type_free() on the return value.
1399  *
1400  * Since 2.24
1401  **/
1402 GVariantType *
1403 g_variant_type_new_array (const GVariantType *element)
1404 {
1405   gsize size;
1406   gchar *new;
1407
1408   g_return_val_if_fail (g_variant_type_check (element), NULL);
1409
1410   size = g_variant_type_get_string_length (element);
1411   new = g_malloc (size + 1);
1412
1413   new[0] = 'a';
1414   memcpy (new + 1, element, size);
1415
1416   return (GVariantType *) new;
1417 }
1418
1419 /**
1420  * g_variant_type_new_maybe:
1421  * @element: a #GVariantType
1422  * @returns: a new maybe #GVariantType
1423  *
1424  * Constructs the type corresponding to a maybe instance containing
1425  * type @type or Nothing.
1426  *
1427  * It is appropriate to call g_variant_type_free() on the return value.
1428  *
1429  * Since 2.24
1430  **/
1431 GVariantType *
1432 g_variant_type_new_maybe (const GVariantType *element)
1433 {
1434   gsize size;
1435   gchar *new;
1436
1437   g_return_val_if_fail (g_variant_type_check (element), NULL);
1438
1439   size = g_variant_type_get_string_length (element);
1440   new = g_malloc (size + 1);
1441
1442   new[0] = 'm';
1443   memcpy (new + 1, element, size);
1444
1445   return (GVariantType *) new;
1446 }
1447
1448 /**
1449  * g_variant_type_new_dict_entry:
1450  * @key: a basic #GVariantType
1451  * @value: a #GVariantType
1452  * @returns: a new dictionary entry #GVariantType
1453  *
1454  * Constructs the type corresponding to a dictionary entry with a key
1455  * of type @key and a value of type @value.
1456  *
1457  * It is appropriate to call g_variant_type_free() on the return value.
1458  *
1459  * Since 2.24
1460  **/
1461 GVariantType *
1462 g_variant_type_new_dict_entry (const GVariantType *key,
1463                                const GVariantType *value)
1464 {
1465   gsize keysize, valsize;
1466   gchar *new;
1467
1468   g_return_val_if_fail (g_variant_type_check (key), NULL);
1469   g_return_val_if_fail (g_variant_type_check (value), NULL);
1470
1471   keysize = g_variant_type_get_string_length (key);
1472   valsize = g_variant_type_get_string_length (value);
1473
1474   new = g_malloc (1 + keysize + valsize + 1);
1475
1476   new[0] = '{';
1477   memcpy (new + 1, key, keysize);
1478   memcpy (new + 1 + keysize, value, valsize);
1479   new[1 + keysize + valsize] = '}';
1480
1481   return (GVariantType *) new;
1482 }
1483
1484 /* private */
1485 const GVariantType *
1486 g_variant_type_checked_ (const gchar *type_string)
1487 {
1488   g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1489   return (const GVariantType *) type_string;
1490 }