ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GVariantDict&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re85.html" title="&lt;%GLibVariantClass&gt;">
<link rel="next" href="re87.html" title="&lt;%GLibVariantParseError&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re85.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re87.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.87"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GVariantDict&gt;</h2>
<p>&lt;GVariantDict&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.87.2"></a><h2>Description</h2>
<p><span class="type">GVariantDict</span> is a mutable interface to <span class="type">GVariant</span> dictionaries.
</p>
<p>It can be used for doing a sequence of dictionary lookups in an
efficient way on an existing <span class="type">GVariant</span> dictionary or it can be used
to construct new dictionaries with a hashtable-like interface.  It
can also be used for taking existing dictionaries and modifying them
in order to create new ones.
</p>
<p><span class="type">GVariantDict</span> can only be used with <code class="constant">G_VARIANT_TYPE_VARDICT</code>
dictionaries.
</p>
<p>It is possible to use <span class="type">GVariantDict</span> allocated on the stack or on the
heap.  When using a stack-allocated <span class="type">GVariantDict</span>, you begin with a
call to <code class="function">g_variant_dict_init()</code> and free the resources with a call to
<code class="function">g_variant_dict_clear()</code>.
</p>
<p>Heap-allocated <span class="type">GVariantDict</span> follows normal refcounting rules: you
allocate it with <code class="function">g_variant_dict_new()</code> and use <code class="function">g_variant_dict_ref()</code>
and <code class="function">g_variant_dict_unref()</code>.
</p>
<p><code class="function">g_variant_dict_end()</code> is used to convert the <span class="type">GVariantDict</span> back into a
dictionary-type <span class="type">GVariant</span>.  When used with stack-allocated instances,
this also implicitly frees all associated memory, but for
heap-allocated instances, you must still call <code class="function">g_variant_dict_unref()</code>
afterwards.
</p>
<p>You will typically want to use a heap-allocated <span class="type">GVariantDict</span> when
you expose it as part of an API.  For most other uses, the
stack-allocated form will be more convenient.
</p>
<p>Consider the following two examples that do the same thing in each
style: take an existing dictionary and look up the "count" uint32
key, adding 1 to it if it is found, or returning an error if the
key is not found.  Each returns the new dictionary as a floating
<span class="type">GVariant</span>.
</p>
<div class="refsect2">
<a name="id-1.1.87.2.10"></a><h3>Using a stack-allocated GVariantDict</h3>
<div class="informalexample"><pre class="programlisting">
  GVariant *
  add_to_count (GVariant  *orig,
                GError   **error)
  {
    GVariantDict dict;
    guint32 count;

    g_variant_dict_init (&amp;dict, orig);
    if (!g_variant_dict_lookup (&amp;dict, "count", "u", &amp;count))
      {
        g_set_error (...);
        g_variant_dict_clear (&amp;dict);
        return NULL;
      }

    g_variant_dict_insert (&amp;dict, "count", "u", count + 1);

    return g_variant_dict_end (&amp;dict);
  }
</pre></div>

</div>
<div class="refsect2">
<a name="id-1.1.87.2.11"></a><h3>Using heap-allocated GVariantDict</h3>
<div class="informalexample"><pre class="programlisting">
  GVariant *
  add_to_count (GVariant  *orig,
                GError   **error)
  {
    GVariantDict *dict;
    GVariant *result;
    guint32 count;

    dict = g_variant_dict_new (orig);

    if (g_variant_dict_lookup (dict, "count", "u", &amp;count))
      {
        g_variant_dict_insert (dict, "count", "u", count + 1);
        result = g_variant_dict_end (dict);
      }
    else
      {
        g_set_error (...);
        result = NULL;
      }

    g_variant_dict_unref (dict);

    return result;
  }
</pre></div>
</div>
</div>
<div class="refsect1">
<a name="id-1.1.87.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.87.3.2"></a><h3>clear</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-dict:clear self))
</pre></div>
<p>Releases all memory associated with a <span class="type">GVariantDict</span> without freeing
the <span class="type">GVariantDict</span> structure itself.
</p>
<p>It typically only makes sense to do this on a stack-allocated
<span class="type">GVariantDict</span> if you want to abort building the value part-way
through.  This function need not be called if you call
<code class="function">g_variant_dict_end()</code> and it also doesn't need to be called on dicts
allocated with g_variant_dict_new (see <code class="function">g_variant_dict_unref()</code> for
that).
</p>
<p>It is valid to call this function on either an initialised
<span class="type">GVariantDict</span> or one that was previously cleared by an earlier call
to <code class="function">g_variant_dict_clear()</code> but it is not valid to call this function
on uninitialised memory.</p>
<div class="refsect3">
<a name="id-1.1.87.3.2.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.3"></a><h3>contains?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:contains? self key))
</pre></div>
<p>Checks if <em class="parameter"><code>key</code></em> exists in <em class="parameter"><code>dict</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.87.3.3.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to look up in the dictionary</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.4"></a><h3>end</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:end self))
</pre></div>
<p>Returns the current value of <em class="parameter"><code>dict</code></em> as a <span class="type">GVariant</span> of type
<code class="constant">G_VARIANT_TYPE_VARDICT</code>, clearing it in the process.
</p>
<p>It is not permissible to use <em class="parameter"><code>dict</code></em> in any way after this call except
for reference counting operations (in the case of a heap-allocated
<span class="type">GVariantDict</span>) or by reinitialising it with <code class="function">g_variant_dict_init()</code> (in
the case of stack-allocated).</p>
<div class="refsect3">
<a name="id-1.1.87.3.4.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.5"></a><h3>insert-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-dict:insert-value self key value))
</pre></div>
<p>Inserts (or replaces) a key in a <span class="type">GVariantDict</span>.
</p>
<p><em class="parameter"><code>value</code></em> is consumed if it is floating.</p>
<div class="refsect3">
<a name="id-1.1.87.3.5.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to insert a value for</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value to insert</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.6"></a><h3>lookup-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:lookup-value self key expected-type))
</pre></div>
<p>Looks up a value in a <span class="type">GVariantDict</span>.
</p>
<p>If <em class="parameter"><code>key</code></em> is not found in <em class="parameter"><code>dictionary</code></em>, <code class="constant">NULL</code> is returned.
</p>
<p>The <em class="parameter"><code>expected_type</code></em> string specifies what type of value is expected.
If the value associated with <em class="parameter"><code>key</code></em> has a different type then <code class="constant">NULL</code> is
returned.
</p>
<p>If the key is found and the value has the correct type, it is
returned.  If <em class="parameter"><code>expected_type</code></em> was specified then any non-<code class="constant">NULL</code> return
value will have this type.</p>
<div class="refsect3">
<a name="id-1.1.87.3.6.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to look up in the dictionary</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>expected_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantType</span>, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">expected-type</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.7"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:ref self))
</pre></div>
<p>Increases the reference count on <em class="parameter"><code>dict</code></em>.
</p>
<p>Don't call this on stack-allocated <span class="type">GVariantDict</span> instances or bad
things will happen.</p>
<div class="refsect3">
<a name="id-1.1.87.3.7.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a heap-allocated <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.8"></a><h3>remove?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:remove? self key))
</pre></div>
<p>Removes a key and its associated value from a <span class="type">GVariantDict</span>.</p>
<div class="refsect3">
<a name="id-1.1.87.3.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to remove</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.9"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-dict:unref self))
</pre></div>
<p>Decreases the reference count on <em class="parameter"><code>dict</code></em>.
</p>
<p>In the event that there are no more references, releases all memory
associated with the <span class="type">GVariantDict</span>.
</p>
<p>Don't call this on stack-allocated <span class="type">GVariantDict</span> instances or bad
things will happen.</p>
<div class="refsect3">
<a name="id-1.1.87.3.9.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dict</p></td>
<td class="parameter_description">
<p>a heap-allocated <span class="type">GVariantDict</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.87.3.10"></a><h3>variant-dict:new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-dict:new from-asv))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.87.3.10.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>from_asv</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">from-asv</code></p>
</td>
</tr></table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>