docs/reference/glib/gvariant-varargs.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2
   3 <refentry id='gvariant-format-strings'>
   4  <refmeta>
   5   <refentrytitle>GVariant Format Strings</refentrytitle>
   6  </refmeta>
   7
   8  <refsect1>
   9   <title>Variable Argument Conversions</title>
  10
  11   <para>
  12    This page attempts to document how to perform variable argument conversions with GVariant.
  13   </para>
  14   <para>
  15    Conversions occur according to format strings.  A format string is a two-way mapping between a single
  16    <link linkend='GVariant'>GVariant</link> value and one or more C values.
  17   </para>
  18   <para>
  19    A conversion from C values into a <link linkend='GVariant'>GVariant</link> value is made using the
  20    <link linkend='g-variant-new'><function>g_variant_new()</function></link> function.  A conversion from a
  21    <link linkend='GVariant'>GVariant</link> into C values is made using the
  22    <link linkend='g-variant-get'><function>g_variant_get()</function></link> function.
  23   </para>
  24  </refsect1>
  25
  26  <refsect1>
  27   <title>Syntax</title>
  28
  29   <para>
  30    This section exhaustively describes all possibilities for GVariant format strings.  There are no valid forms of
  31    format strings other than those described here.  Please note that the format string syntax is likely to expand in the
  32    future.
  33   </para>
  34   <para>
  35    Valid format strings have one of the following forms:
  36   </para>
  37   <itemizedlist>
  38    <listitem>
  39     <para>any type string</para>
  40    </listitem>
  41    <listitem>
  42     <para>
  43      a type string prefixed with a '<literal>@</literal>'
  44     </para>
  45    </listitem>
  46    <listitem>
  47     <para>
  48      '<literal>&amp;s</literal>' '<literal>&amp;o</literal>', '<literal>&amp;g</literal>', '<literal>^as</literal>',
  49      '<literal>^ao</literal>', '<literal>^ag</literal>', '<literal>^a&amp;s</literal>', '<literal>^a&amp;o</literal>' or
  50      '<literal>^a&amp;g</literal>'
  51     </para>
  52    </listitem>
  53    <listitem>
  54     <para>
  55      any format string, prefixed with an '<literal>m</literal>'
  56     </para>
  57    </listitem>
  58    <listitem>
  59     <para>
  60      a sequence of zero or more format strings strings, concatenated and enclosed in parentheses
  61     </para>
  62    </listitem>
  63    <listitem>
  64     <para>
  65      an opening brace, followed by two format strings, followed by a closing brace (subject to the constraint that the
  66      first format string correspond to a type valid for use as the key type of a dictionary)
  67     </para>
  68    </listitem>
  69   </itemizedlist>
  70  </refsect1>
  71  <refsect1>
  72   <title>Symbols</title>
  73
  74    <para>
  75     The following table describes the rough meaning of symbols that may appear inside a GVariant format string.  Each
  76     symbol is described in detail in its own section, including usage examples.
  77   </para>
  78
  79   <informaltable>
  80    <tgroup cols='2'>
  81     <colspec colname='col_0'/>
  82     <colspec colname='col_1'/>
  83     <tbody>
  84
  85      <row rowsep='1'>
  86       <entry colsep='1' rowsep='1'>
  87        <para>
  88         <emphasis role='strong'>Symbol</emphasis>
  89        </para>
  90       </entry>
  91       <entry colsep='1' rowsep='1'>
  92        <para>
  93          <emphasis role='strong'>Meaning</emphasis>
  94        </para>
  95       </entry>
  96      </row>
  97
  98      <row rowsep='1'>
  99       <entry colsep='1' rowsep='1'>
 100        <para>
 101         <emphasis role='strong'>
 102          <literal>b</literal>, <literal>y</literal>, <literal>n</literal>, <literal>q</literal>, <literal>i</literal>,
 103          <literal>u</literal>, <literal>x</literal>, <literal>t</literal>, <literal>h</literal>, <literal>d</literal>
 104         </emphasis>
 105        </para>
 106       </entry>
 107       <entry colsep='1' rowsep='1'>
 108        <para>
 109         Used for building or deconstructing boolean, byte and numeric types.  See
 110         <link linkend='gvariant-format-strings-numeric-types'>Numeric Types</link> below.
 111        </para>
 112       </entry>
 113      </row>
 114
 115      <row rowsep='1'>
 116       <entry colsep='1' rowsep='1'>
 117        <para>
 118         <emphasis role='strong'>
 119          <literal>s</literal>, <literal>o</literal>, <literal>g</literal>
 120         </emphasis>
 121        </para>
 122       </entry>
 123       <entry colsep='1' rowsep='1'>
 124        <para>
 125         Used for building or deconstructing string types.  See
 126         <link linkend='gvariant-format-strings-strings'>Strings</link> below.
 127        </para>
 128       </entry>
 129      </row>
 130
 131      <row rowsep='1'>
 132       <entry colsep='1' rowsep='1'>
 133        <para>
 134         <emphasis role='strong'><literal>v</literal></emphasis>
 135        </para>
 136       </entry>
 137       <entry colsep='1' rowsep='1'>
 138        <para>
 139         Used for building or deconstructing variant types.  See
 140         <link linkend='gvariant-format-strings-variant'>Variants</link> below.
 141        </para>
 142       </entry>
 143      </row>
 144
 145      <row rowsep='1'>
 146       <entry colsep='1' rowsep='1'>
 147        <para>
 148         <emphasis role='strong'>
 149          <literal>a</literal>
 150         </emphasis>
 151        </para>
 152       </entry>
 153       <entry colsep='1' rowsep='1'>
 154        <para>
 155         Used for building or deconstructing arrays.  See
 156         <link linkend='gvariant-format-strings-arrays'>Arrays</link> below.
 157        </para>
 158       </entry>
 159      </row>
 160
 161      <row rowsep='1'>
 162       <entry colsep='1' rowsep='1'>
 163        <para>
 164         <emphasis role='strong'>
 165          <literal>m</literal>
 166         </emphasis>
 167        </para>
 168       </entry>
 169       <entry colsep='1' rowsep='1'>
 170        <para>
 171          Used for building or deconstructing maybe types.  See
 172          <link linkend='gvariant-format-strings-maybe-types'>Maybe Types</link> below.
 173        </para>
 174       </entry>
 175      </row>
 176
 177      <row rowsep='1'>
 178       <entry colsep='1' rowsep='1'>
 179        <para>
 180         <emphasis role='strong'>
 181          <literal>()</literal>
 182         </emphasis>
 183        </para>
 184       </entry>
 185       <entry colsep='1' rowsep='1'>
 186        <para>
 187          Used for building or deconstructing tuples.  See
 188          <link linkend='gvariant-format-strings-tuples'>Tuples</link> below.
 189        </para>
 190       </entry>
 191      </row>
 192
 193      <row rowsep='1'>
 194       <entry colsep='1' rowsep='1'>
 195        <para>
 196         <emphasis role='strong'>
 197          <literal>{}</literal>
 198         </emphasis>
 199        </para>
 200       </entry>
 201       <entry colsep='1' rowsep='1'>
 202        <para>
 203         Used for building or deconstructing dictionary entries. See
 204         <link linkend='gvariant-format-strings-dictionaries'>Dictionaries</link> below.
 205        </para>
 206       </entry>
 207      </row>
 208
 209      <row rowsep='1'>
 210       <entry colsep='1' rowsep='1'>
 211        <para>
 212         <emphasis role='strong'>
 213          <literal>@</literal>
 214         </emphasis>
 215        </para>
 216       </entry>
 217       <entry colsep='1' rowsep='1'>
 218        <para>
 219         Used as a prefix on a GVariant type string (not format string).  Denotes that a pointer to a
 220         <link linkend='GVariant'>GVariant</link> should be used in place of the normal C type or types.  For
 221         <link linkend='g-variant-new'><function>g_variant_new()</function></link> this means that you must pass a
 222         non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> <code>(<link linkend='GVariant'>GVariant</link>
 223         *)</code>.  For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
 224         must pass a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> for the value to be returned
 225         by reference or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value.  See
 226         <link linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
 227        </para>
 228       </entry>
 229      </row>
 230
 231      <row rowsep='1'>
 232       <entry colsep='1' rowsep='1'>
 233        <para>
 234         <emphasis role='strong'>
 235          <literal>*</literal>, <literal>?</literal>, <literal>r</literal>
 236         </emphasis>
 237        </para>
 238       </entry>
 239       <entry colsep='1' rowsep='1'>
 240        <para>
 241         Exactly equivalent to <literal>@*</literal>, <literal>@?</literal> and <literal>@r</literal>.  Provided only for
 242         completeness so that all GVariant type strings can be used also as format strings.  See <link
 243         linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
 244        </para>
 245       </entry>
 246      </row>
 247
 248      <row rowsep='1'>
 249       <entry colsep='1' rowsep='1'>
 250        <para>
 251         <emphasis role='strong'><literal>&amp;</literal></emphasis>
 252        </para>
 253       </entry>
 254       <entry colsep='1' rowsep='1'>
 255        <para>
 256         Used as a prefix on a GVariant type string (not format string).  Denotes that a C pointer to serialised data
 257         should be used in place of the normal C type.  See
 258         <link linkend='gvariant-format-strings-pointers'>Pointers</link> below.
 259        </para>
 260       </entry>
 261      </row>
 262
 263      <row rowsep='1'>
 264       <entry colsep='1' rowsep='1'>
 265        <para>
 266         <emphasis role='strong'><literal>^</literal></emphasis>
 267        </para>
 268       </entry>
 269       <entry colsep='1' rowsep='1'>
 270        <para>
 271         Used as a prefix on some specific types of format strings.  See
 272         <link linkend='gvariant-format-strings-convenience'>Convenience Conversions</link> below.
 273        </para>
 274       </entry>
 275      </row>
 276     </tbody>
 277    </tgroup>
 278   </informaltable>
 279
 280
 281   <refsect2 id='gvariant-format-strings-numeric-types'>
 282    <title>Numeric Types</title>
 283    <para>
 284     <emphasis role='strong'>
 285      Characters: <literal>b</literal>, <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
 286      <literal>i</literal>, <literal>u</literal>, <literal>x</literal>, <literal>t</literal>, <literal>h</literal>,
 287      <literal>d</literal>
 288     </emphasis>
 289    </para>
 290
 291    <para>
 292     Variable argument conversions from numeric types work in the most obvious way possible.  Upon encountering one of
 293     these characters, <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes the equivalent C
 294     type as an argument.  <link linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to
 295     the equivalent C type (or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value).
 296    </para>
 297
 298    <para>
 299     The equivalent C types are as follows:
 300    </para>
 301
 302    <informaltable>
 303     <tgroup cols='2'>
 304      <colspec colname='col_0'/><colspec colname='col_1'/>
 305      <tbody>
 306       <row rowsep='1'>
 307        <entry colsep='1' rowsep='1'>
 308         <para>
 309           <emphasis role='strong'>Character</emphasis>
 310         </para>
 311        </entry>
 312        <entry colsep='1' rowsep='1'>
 313         <para>
 314           <emphasis role='strong'>Equivalent C type</emphasis>
 315         </para>
 316        </entry>
 317       </row>
 318       <row rowsep='1'>
 319        <entry colsep='1' rowsep='1'>
 320         <para>
 321          <emphasis role='strong'>
 322           <literal>b</literal>
 323          </emphasis>
 324         </para>
 325        </entry>
 326        <entry colsep='1' rowsep='1'>
 327         <para>
 328          <link linkend='gboolean'><type>gboolean</type></link>
 329         </para>
 330        </entry>
 331       </row>
 332       <row rowsep='1'>
 333        <entry colsep='1' rowsep='1'>
 334         <para>
 335          <emphasis role='strong'>
 336           <literal>y</literal>
 337          </emphasis>
 338         </para>
 339        </entry>
 340        <entry colsep='1' rowsep='1'>
 341         <para>
 342          <link linkend='guchar'><type>guchar</type></link>
 343         </para>
 344        </entry>
 345       </row>
 346       <row rowsep='1'>
 347        <entry colsep='1' rowsep='1'>
 348         <para>
 349          <emphasis role='strong'>
 350           <literal>n</literal>
 351          </emphasis>
 352         </para>
 353        </entry>
 354        <entry colsep='1' rowsep='1'>
 355         <para>
 356          <link linkend='gint16'><type>gint16</type></link>
 357         </para>
 358        </entry>
 359       </row>
 360       <row rowsep='1'>
 361        <entry colsep='1' rowsep='1'>
 362         <para>
 363          <emphasis role='strong'>
 364           <literal>q</literal>
 365          </emphasis>
 366         </para>
 367        </entry>
 368        <entry colsep='1' rowsep='1'>
 369         <para>
 370          <link linkend='guint16'><type>guint16</type></link>
 371         </para>
 372        </entry>
 373       </row>
 374       <row rowsep='1'>
 375        <entry colsep='1' rowsep='1'>
 376         <para>
 377          <emphasis role='strong'>
 378           <literal>i</literal>
 379          </emphasis>
 380         </para>
 381        </entry>
 382        <entry colsep='1' rowsep='1'>
 383         <para>
 384          <link linkend='gint32'><type>gint32</type></link>
 385         </para>
 386        </entry>
 387       </row>
 388       <row rowsep='1'>
 389        <entry colsep='1' rowsep='1'>
 390         <para>
 391          <emphasis role='strong'>
 392           <literal>u</literal>
 393          </emphasis>
 394         </para>
 395        </entry>
 396        <entry colsep='1' rowsep='1'>
 397         <para>
 398          <link linkend='guint32'><type>guint32</type></link>
 399         </para>
 400        </entry>
 401       </row>
 402       <row rowsep='1'>
 403        <entry colsep='1' rowsep='1'>
 404         <para>
 405          <emphasis role='strong'>
 406           <literal>x</literal>
 407          </emphasis>
 408         </para>
 409        </entry>
 410        <entry colsep='1' rowsep='1'>
 411         <para>
 412          <link linkend='gint64'><type>gint64</type></link>
 413         </para>
 414        </entry>
 415       </row>
 416       <row rowsep='1'>
 417        <entry colsep='1' rowsep='1'>
 418         <para>
 419          <emphasis role='strong'>
 420           <literal>t</literal>
 421          </emphasis>
 422         </para>
 423        </entry>
 424        <entry colsep='1' rowsep='1'>
 425         <para>
 426          <link linkend='guint64'><type>guint64</type></link>
 427         </para>
 428        </entry>
 429       </row>
 430       <row rowsep='1'>
 431        <entry colsep='1' rowsep='1'>
 432         <para>
 433          <emphasis role='strong'>
 434           <literal>h</literal>
 435          </emphasis>
 436         </para>
 437        </entry>
 438        <entry colsep='1' rowsep='1'>
 439         <para>
 440          <link linkend='gint32'><type>gint32</type></link>
 441         </para>
 442        </entry>
 443       </row>
 444       <row rowsep='1'>
 445        <entry colsep='1' rowsep='1'>
 446         <para>
 447          <emphasis role='strong'>
 448           <literal>d</literal>
 449          </emphasis>
 450         </para>
 451        </entry>
 452        <entry colsep='1' rowsep='1'>
 453         <para>
 454          <link linkend='gdouble'><type>gdouble</type></link>
 455         </para>
 456        </entry>
 457       </row>
 458      </tbody>
 459     </tgroup>
 460    </informaltable>
 461
 462    <para>
 463     Note that in C, small integer types in variable argument lists are promoted up to <link
 464     linkend='gint'><type>int</type></link> or <link linkend='guint'><type>unsigned int</type></link> as appropriate, and
 465     read back accordingly.  <link linkend='gint'><type>int</type></link> is 32 bits on every platform on which GLib is
 466     currently suported.  This means that you can use C expressions of type <link linkend='gint'><type>int</type></link>
 467     with <link linkend='g-variant-new'><function>g_variant_new()</function></link> and format characters
 468     '<literal>b</literal>', '<literal>y</literal>', '<literal>n</literal>', '<literal>q</literal>',
 469     '<literal>i</literal>', '<literal>u</literal>' and '<literal>h</literal>'.  Specifically, you can use integer
 470     literals with these characters.
 471    </para>
 472
 473    <para>
 474     When using the '<literal>x</literal>' and '<literal>t</literal>' characters, you must ensure that the value that you
 475     provide is 64 bit.  This means that you should use a cast or make use of the
 476     <link linkend='G-GINT64-CONSTANT--CAPS'><literal>G_GINT64_CONSTANT</literal></link> or
 477     <link linkend='G-GUINT64-CONSTANT--CAPS'><literal>G_GUINT64_CONSTANT</literal></link> macros.
 478    </para>
 479
 480    <para>
 481     No type promotion occurs when using <link linkend='g-variant-get'><function>g_variant_get()</function></link> since
 482     it operates with pointers.  The pointers must always point to a memory region of exactly the correct size.
 483    </para>
 484
 485    <refsect3>
 486     <title>Examples</title>
 487     <informalexample><programlisting>
 488 <![CDATA[GVariant *value1, *value2, *value3, *value4;
 489
 490 value1 = g_variant_new ("y", 200);
 491 value2 = g_variant_new ("b", TRUE);
 492 value3 = g_variant_new ("d", 37.5):
 493 value4 = g_variant_new ("x", G_GINT64_CONSTANT (998877665544332211));
 494
 495 {
 496   gdouble floating;
 497   gboolean truth;
 498   gint64 bignum;
 499
 500
 501   g_variant_get (value1, "y", NULL);      /* ignore the value. */
 502   g_variant_get (value2, "b", &truth);
 503   g_variant_get (value3, "d", &floating);
 504   g_variant_get (value4, "x", &bignum);
 505 }]]></programlisting></informalexample>
 506    </refsect3>
 507   </refsect2>
 508
 509   <refsect2 id='gvariant-format-strings-strings'>
 510    <title>Strings</title>
 511    <para>
 512     <emphasis role='strong'>
 513      Characters: <literal>s</literal>, <literal>o</literal>, <literal>g</literal>
 514     </emphasis>
 515    </para>
 516
 517    <para>
 518     String conversions occur to and from standard nul-terminated C strings.  Upon encountering an
 519     '<literal>s</literal>', '<literal>o</literal>' or '<literal>g</literal>' in a format string,
 520     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a <code>(const
 521     <link linkend='gchar'>gchar</link> *)</code> and makes a copy of it.
 522     <link linkend='NULL--CAPS'><literal>NULL</literal></link> is not a valid string.  If the '<literal>o</literal>' or
 523     '<literal>g</literal>' characters are used, care must be taken to ensure that the passed string is a valid DBus
 524     object path or DBus type signature, respectively.
 525    </para>
 526    <para>
 527     Upon encounting '<literal>s</literal>', '<literal>o</literal>' or '<literal>g</literal>', <link
 528     linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to a
 529     <code>(<link linkend='gchar'>gchar</link> *)</code> (ie: <code>(<link linkend='gchar'>gchar</link> **)</code>) and
 530     sets it to a newly-allocated copy of the string.  It is appropriate to free this copy using
 531     <link linkend='g-free'><function>g_free()</function></link>.
 532     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be passed to indicate that the value of the
 533     string should be ignored (in which case no copy is made).
 534    </para>
 535
 536    <refsect3>
 537     <title>Examples</title>
 538     <informalexample><programlisting>
 539 <![CDATA[GVariant *value1, *value2, *value3;
 540
 541 value1 = g_variant_new ("s", "hello world!");
 542 value2 = g_variant_new ("o", "/must/be/a/valid/path");
 543 value3 = g_variant_new ("g", "iias");
 544
 545 #if 0
 546   g_variant_new ("s", NULL);      /* not valid: NULL is not a string. */
 547 #endif
 548
 549 {
 550   gchar *result;
 551
 552   g_variant_get (value1, "s", &result);
 553   g_print ("It was '%s'\n", result);
 554   g_free (result);
 555 }]]></programlisting></informalexample>
 556    </refsect3>
 557   </refsect2>
 558
 559   <refsect2 id='gvariant-format-strings-variants'>
 560    <title>Variants</title>
 561    <para>
 562     <emphasis role='strong'>
 563      Characters: <literal>v</literal>
 564     </emphasis>
 565    </para>
 566
 567    <para>
 568     Upon encountering a '<literal>v</literal>',
 569     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a <code>(<link
 570     linkend='GVariant'>GVariant</link> *)</code>.  The value of the
 571     <link linkend='GVariant'><type>GVariant</type></link> is used as the contents of the variant value.
 572    </para>
 573    <para>
 574     Upon encountering a '<literal>v</literal>', <link
 575     linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to a
 576     <code>(<link linkend='GVariant'>GVariant</link> *)</code> (ie: <code>(<link linkend='GVariant'>GVariant</link> **)
 577     </code>).  It is set to a new reference to a <link linkend='GVariant'><type>GVariant</type></link> instance
 578     containing the contents of the variant value.  It is appropriate to free this reference using
 579     <link linkend='g-variant-unref'><function>g_variant_unref()</function></link>.
 580     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be passed to indicate that the value should be
 581     ignored (in which case no new reference is created).
 582    </para>
 583
 584    <refsect3>
 585     <title>Examples</title>
 586     <informalexample><programlisting>
 587 <![CDATA[GVariant *x, *y;
 588
 589 /* the following two lines are equivalent: */
 590 x = g_variant_new ("v", y);
 591 x = g_variant_new_variant (y);
 592
 593 /* as are these: */
 594 g_variant_get (x, "v", &y);
 595 y = g_variant_get_variant (x);]]></programlisting></informalexample>
 596    </refsect3>
 597   </refsect2>
 598
 599
 600   <refsect2 id='gvariant-format-strings-arrays'>
 601    <title>Arrays</title>
 602    <para>
 603     <emphasis role='strong'>
 604      Characters: <literal>a</literal>
 605     </emphasis>
 606    </para>
 607
 608    <para>
 609     Upon encountering an '<literal>a</literal>' character followed by a type string,
 610     <link linkend='g-variant-new'><function>g_variant_new()</function></link> will take a
 611     <code>(<link linkend='GVariantBuilder'>GVariantBuilder</link> *)</code> that has been created as an array builder
 612     for an array of the type given in the type string.  The builder will have
 613     <link linkend='g-variant-builder-end'><function>g_variant_builder_end()</function></link> called on it and the
 614     result will be used as the value.  As a special exception, if the given type string is a definite type, then
 615     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may be given to mean an empty array of that type.
 616    </para>
 617
 618    <para>
 619     Upon encountering an '<literal>a</literal>' character followed by a type string,
 620     <link linkend='g-variant-get'><function>g_variant_get()</function></link> will take a pointer to a
 621     <code>(<link linkend='GVariantIter'>GVariantIter</link> *)</code> (ie:
 622     <code>(<link linkend='GVariantIter'>GVariantIter</link> **)</code>).
 623     A new heap-allocated iterator is created and returned, initialised for iterating over the elements of the array.
 624     This iterator should be freed when you are done with it, using
 625     <link linkend='g-variant-iter-unref'><function>g_variant_iter_unref()</function></link>.
 626     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be given to indicate that the value of the array
 627     should be ignored.
 628    </para>
 629
 630    <refsect3>
 631     <title>Examples</title>
 632     <informalexample><programlisting>
 633 <![CDATA[GVariantBuilder *builder;
 634 GVariant *value;
 635
 636 builder = g_variant_builder_new (G_VARIANT_TYPE_CLASS_ARRAY, NULL);
 637 g_variant_builder_add (builder, "s", "when");
 638 g_variant_builder_add (builder, "s", "in");
 639 g_variant_builder_add (builder, "s", "the");
 640 g_variant_builder_add (builder, "s", "course");
 641 value = g_variant_new ("as", builder);
 642
 643 {
 644   GVariantIter *iter;
 645   gchar *str;
 646
 647   g_variant_get (value, "as", &iter);
 648   while (g_variant_iter_loop (iter, "s", &str))
 649     g_print ("%s\n");
 650   g_variant_iter_unref (iter);
 651 }]]></programlisting></informalexample>
 652    </refsect3>
 653   </refsect2>
 654
 655   <refsect2 id='gvariant-format-strings-maybe-types'>
 656    <title>Maybe Types</title>
 657    <para>
 658     <emphasis role='strong'>
 659      Characters: <literal>m</literal>
 660     </emphasis>
 661    </para>
 662    <para>
 663     Maybe types are handled in two separate ways depending on the format string that follows the
 664     '<literal>m</literal>'.  The method that is used currently depends entirely on the character immediately following the
 665     '<literal>m</literal>'.
 666    </para>
 667
 668    <para>
 669     The first way is used with format strings starting with '<literal>s</literal>', '<literal>o</literal>',
 670     '<literal>g</literal>', '<literal>v</literal>', '<literal>@</literal>', '<literal>*</literal>',
 671     '<literal>?</literal>', '<literal>r</literal>', '<literal>&amp;</literal>', or '<literal>^</literal>'.  In all of
 672     these cases, for non-maybe types, <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes
 673     a pointer to a non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> value and
 674     <link linkend='g-variant-get'><function>g_variant_get()</function></link> returns (by reference) a
 675     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer.  When any of these format strings are
 676     prefixed with an '<literal>m</literal>', the type of arguments that are collected does not change in any way, but
 677     <link linkend='NULL--CAPS'><literal>NULL</literal></link> becomes a permissable value, to indicate the Nothing case.
 678    </para>
 679    <para>
 680     The second way is used with all other format strings.  For
 681     <link linkend='g-variant-new'><function>g_variant_new()</function></link> an additional
 682     <link linkend='gboolean'><type>gboolean</type></link> argument is collected and for
 683     <link linkend='g-variant-get'><function>g_variant_get()</function></link> an additional
 684     <code>(<link linkend='gboolean'>gboolean</link> *)</code>.  Following this argument, the arguments that are normally
 685     collected for the equivalent non-maybe type will be collected.
 686    </para>
 687    <para>
 688     If <link linkend='FALSE--CAPS'><literal>FALSE</literal></link> is given to
 689     <link linkend='g-variant-new'><function>g_variant_new()</function></link> then the Nothing value is constructed and
 690     the collected arguments are ignored.  Otherwise (if <link linkend='TRUE--CAPS'><literal>TRUE</literal></link> was
 691     given), the arguments are used in the normal way to create the Just value.
 692    </para>
 693    <para>
 694     If <link linkend='NULL--CAPS'><literal>NULL</literal></link> is given to
 695     <link linkend='g-variant-get'><function>g_variant_get()</function></link> then the value is ignored.  If a
 696     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer is given then it is used to return by reference
 697     whether the value was Just.  In the case that the value was Just, the
 698     <link linkend='gboolean'><type>gboolean</type></link> will be set to
 699     <link linkend='TRUE--CAPS'><literal>TRUE</literal></link> and the value will be stored in the arguments in the usual
 700     way.  In the case that the value was Nothing, the <link linkend='gboolean'><type>gboolean</type></link> will be set to
 701     <link linkend='FALSE--CAPS'><literal>FALSE</literal></link> and the arguments will be collected in the normal way
 702     but have their values set to binary zero.
 703    </para>
 704
 705    <refsect3>
 706     <title>Examples</title>
 707     <informalexample><programlisting>
 708 <![CDATA[GVariant *value1, *value2, *value3, *value4, *value5, *value6;
 709 value1 = g_variant_new ("ms", "Hello world");
 710 value2 = g_variant_new ("ms", NULL);
 711 value3 = g_variant_new ("(m(ii)s)", TRUE, 123, 456, "Done");
 712 value4 = g_variant_new ("(m(ii)s)", FALSE, -1, -1, "Done");          /* both '-1' are ignored. */
 713 value5 = g_variant_new ("(m@(ii)s)", NULL, "Done");
 714
 715 {
 716   GVariant *contents;
 717   const gchar *cstr;
 718   gboolean just;
 719   gint32 x, y;
 720   gchar *str;
 721
 722   g_variant_get (value1, "ms", &str);
 723   if (str != NULL)
 724     g_print ("str: %s\n", str);
 725   else
 726     g_print ("it was null\n");
 727   g_free (str);
 728
 729
 730   g_variant_get (value2, "m&s", &cstr);
 731   if (cstr != NULL)
 732     g_print ("str: %s\n", cstr);
 733   else
 734     g_print ("it was null\n");
 735   /* don't free 'cstr' */
 736
 737
 738   /* NULL passed for the gboolean *, but two 'gint32 *' still collected */
 739   g_variant_get (value3, "(m(ii)s)", NULL, NULL, NULL, &str);
 740   g_print ("string is %s\n", str);
 741   g_free (str);
 742
 743   /* note: &s used, so g_free() not needed */
 744   g_variant_get (value4, "(m(ii)&s)", &just, &x, &y, &cstr);
 745   if (just)
 746     g_print ("it was (%d, %d)\n", x, y);
 747   else
 748     g_print ("it was null\n");
 749   g_print ("string is %s\n", cstr);
 750   /* don't free 'cstr' */
 751
 752
 753   g_variant_get (value5, "(m*s)", &contents, NULL); /* ignore the string. */
 754   if (contents != NULL)
 755     {
 756       g_variant_get (contents, "(ii)", &x, &y);
 757       g_print ("it was (%d, %d)\n", x, y);
 758       g_variant_unref (contents);
 759     }
 760   else
 761     g_print ("it was null\n");
 762 }]]></programlisting></informalexample>
 763    </refsect3>
 764   </refsect2>
 765
 766   <refsect2 id='gvariant-format-strings-tuples'>
 767    <title>Tuples</title>
 768    <para>
 769     <emphasis role='strong'>
 770      Characters: <code>()</code>
 771     </emphasis>
 772    </para>
 773
 774    <para>
 775     Tuples are handled by handling each item in the tuple, in sequence.  Each item is handled in the usual way.
 776    </para>
 777
 778    <refsect3>
 779     <title>Examples</title>
 780     <informalexample><programlisting>
 781 <![CDATA[GVariant *value1, *value2;
 782
 783 value1 = g_variant_new ("(s(ii))", "Hello", 55, 77);
 784 value2 = g_variant_new ("()");
 785
 786 {
 787   gchar *string;
 788   gint x, y;
 789
 790   g_variant_get (value1, "(s(ii))", &string, &x, &y);
 791   g_print ("%s, %d, %d\n", string, x, y);
 792   g_free (string);
 793
 794   g_variant_get (value2, "()");   /* do nothing... */
 795 }]]></programlisting></informalexample>
 796    </refsect3>
 797   </refsect2>
 798
 799   <refsect2 id='gvariant-format-strings-dictionaries'>
 800    <title>Dictionaries</title>
 801    <para>
 802     <emphasis role='strong'>
 803      Characters: <code>{}</code>
 804     </emphasis>
 805    </para>
 806
 807    <para>
 808     Dictionary entries are handled by handling first the key, then the value.  Each is handled in the usual way.
 809    </para>
 810
 811    <refsect3>
 812     <title>Examples</title>
 813     <informalexample><programlisting>
 814 <![CDATA[GVariantBuilder *b;
 815 GVariant *dict;
 816
 817 b = g_variant_builder_new (G_VARIANT_TYPE_CLASS_ARRAY, G_VARIANT_TYPE ("a{sv}"));
 818 g_variant_builder_add (b, "{sv}", "name", g_variant_new_string ("foo"));
 819 g_variant_builder_add (b, "{sv}", "timeout", g_variant_new_int32 (10));
 820 dict = g_variant_builder_end (b);]]></programlisting></informalexample>
 821    </refsect3>
 822   </refsect2>
 823
 824   <refsect2 id='gvariant-format-strings-gvariant'>
 825    <title>GVariant *</title>
 826    <para>
 827     <emphasis role='strong'>
 828      Characters: <literal>@</literal>, <literal>*</literal>, <literal>?</literal>, <literal>r</literal>
 829     </emphasis>
 830
 831    </para>
 832    <para>
 833     Upon encountering a '<literal>@</literal>' in front of a type string,
 834     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a
 835     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer to a
 836     <link linkend='GVariant'><type>GVariant</type></link> and uses its value directly instead of collecting arguments to
 837     create the value.  The provided <link linkend='GVariant'><type>GVariant</type></link> must have a type that matches the
 838     type string following the '<literal>@</literal>'.  '<literal>*</literal>' is
 839     the same as '<literal>@*</literal>' (ie: take a <link linkend='GVariant'><type>GVariant</type></link> of any type).
 840     '<literal>?</literal>' is the same as '<literal>@?</literal>' (ie: take a
 841     <link linkend='GVariant'><type>GVariant</type></link> of any basic type).  '<literal>r</literal>' is the same as
 842     '<literal>@r</literal>' (ie: take a <link linkend='GVariant'><type>GVariant</type></link> of any tuple type).
 843    </para>
 844    <para>
 845     Upon encountering a '<literal>@</literal>' in front of a type string,
 846     <link linkend='g-variant-get'><function>g_variant_get()</function></link>
 847     takes a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> (ie: a
 848     <code>(<link linkend='GVariant'>GVariant</link> **)</code>) and sets it to a new reference to a
 849     <link linkend='GVariant'><type>GVariant</type></link> containing the value (instead of deconstructing the value into
 850     C types in the usual way).  <link linkend='NULL--CAPS'><literal>NULL</literal></link> can be given to ignore the
 851     value.  '<literal>*</literal>', '<literal>?</literal>' and '<literal>r</literal>' are handled in a way analogous to
 852     what is stated above.
 853    </para>
 854    <para>
 855     You can always use '<literal>*</literal>' as an alternative to '<literal>?</literal>', '<literal>r</literal>' or any
 856     use of '<literal>@</literal>'.  Using the other characters where possible is recommended, however, due to the
 857     improvements in type safety and code self-documentation.
 858    </para>
 859
 860    <refsect3>
 861     <title>Examples</title>
 862     <informalexample><programlisting>
 863 <![CDATA[GVariant *value1, *value2;
 864
 865 value1 = g_variant_new ("(i@ii)", 44, g_variant_new_int32 (55), 66);
 866
 867 /* note: consumes floating reference count on 'value1' */
 868 value2 = g_variant_new ("(@(iii)*)", value1, g_variant_new_string ("foo"));
 869
 870 {
 871   const gchar *string;
 872   GVariant *tmp;
 873   gsize length;
 874   gint x, y, z;
 875
 876   g_variant_get (value2, "((iii)*)", &x, &y, &z, &tmp);
 877   string = g_variant_get_string (tmp, &length);
 878   g_print ("it is %d %d %d %s (length=%d)\n", x, y, z, string, (int) length);
 879   g_variant_unref (tmp);
 880
 881   /* quick way to skip all the values in a tuple */
 882   g_variant_get (value2, "(rs)", NULL, &string); /* or "(@(iii)s)" */
 883   g_print ("i only got the string: %s\n", string);
 884   g_free (string);
 885 }]]></programlisting></informalexample>
 886    </refsect3>
 887   </refsect2>
 888
 889   <refsect2 id='gvariant-format-strings-pointers'>
 890    <title>Pointers</title>
 891    <para>
 892     <emphasis role='strong'>
 893      Characters: <code>&amp;</code>
 894     </emphasis>
 895    </para>
 896
 897    <para>
 898     The '<code>&amp;</code>' character is used to indicate that serialised data should be directly exchanged via a
 899     pointer.
 900    </para>
 901    <para>
 902     Currently, the only use for this character is when it is applied to a string (ie: '<literal>&amp;s</literal>',
 903     '<literal>&amp;o</literal>' or '<code>&amp;g</code>').  For
 904     <link linkend='g-variant-new'><function>g_variant_new()</function></link> this has absolutely no effect.  The string
 905     is collected and duplicated normally.  For <link linkend='g-variant-get'><function>g_variant_get()</function></link>
 906     it means that instead of creating a newly allocated copy of the string, a pointer to the serialised data is
 907     returned.  This pointer should not be freed.  Validity checks are performed to ensure that the string data will
 908     always be properly nul-terminated.
 909    </para>
 910
 911    <refsect3>
 912     <title>Examples</title>
 913     <informalexample><programlisting>
 914 <![CDATA[{
 915   const gchar *str;
 916   GVariant *value;
 917
 918   value = g_variant_new ("&s", "hello world");
 919   str = g_variant_get ("&s", &str);
 920   g_print ("string is: %s\n", str);
 921   /* no need to free str */
 922 }]]></programlisting></informalexample>
 923    </refsect3>
 924   </refsect2>
 925
 926   <refsect2 id='gvariant-format-strings-convenience'>
 927    <title>Convenience Conversions</title>
 928    <para>
 929     <emphasis role='strong'>
 930      Characters: <literal>^</literal>
 931     </emphasis>
 932    </para>
 933
 934    <para>
 935     The '<literal>^</literal>' character currently only has one purpose: to convert to and from
 936     <link linkend='G-TYPE-STRV'><literal>G_TYPE_STRV</literal></link> type arrays of strings.  It is always used with
 937     arrays of strings (or other string types).  It has two forms.
 938    </para>
 939    <itemizedlist>
 940     <listitem>
 941      <para>
 942       '<literal>^as</literal>' (or <literal>o</literal> or <literal>g</literal>)
 943      </para>
 944     </listitem>
 945     <listitem>
 946      <para>
 947       '<literal>^a&amp;s</literal>' (or <literal>o</literal> or <literal>g</literal>)
 948      </para>
 949     </listitem>
 950    </itemizedlist>
 951    <para>
 952     When used with <link linkend='g-variant-new'><function>g_variant_new()</function></link> both forms are equivalent.
 953     A <code>(const <link linkend='gchar'>gchar</link> * const *)</code> is collected.  This must be a pointer to the
 954     array of <link linkend='NULL--CAPS'><literal>NULL</literal></link>-terminated pointers to strings.  This array is
 955     converted to a <link linkend='GVariant'><type>GVariant</type></link> instance.  Copies are made, so the original
 956     array may be freed immediately.
 957    </para>
 958    <para>
 959     When used with <link linkend='g-variant-get'><function>g_variant_get()</function></link> the two forms have
 960     different meaning.  Both return a freshly allocated
 961     <link linkend='NULL--CAPS'><literal>NULL</literal></link>-terminated array of pointers to strings.  In the case of
 962     '<literal>^as</literal>', the strings are owned by the caller -- it is appropriate to free the array with
 963     <link linkend='g-strfreev'><function>g_strfreev()</function></link>.  In the case of '<literal>^a&amp;s</literal>',
 964     a shallow copy is made; the strings themselves are embedded in the serialised data and owned by the original
 965     <link linkend='GVariant'><type>GVariant</type></link> instance -- it is only appropriate to free the outer array
 966     with <link linkend='g-free'><function>g_free()</function></link>.
 967    </para>
 968   </refsect2>
 969  </refsect1>
 970 </refentry>