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