ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251
							<!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;GVariantBuilder&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="re83.html" title="&lt;GVariant&gt;">
<link rel="next" href="re85.html" title="&lt;%GLibVariantClass&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="re83.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re85.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.85"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GVariantBuilder&gt;</h2>
<p>&lt;GVariantBuilder&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.85.2"></a><h2>Description</h2>
<p>A utility type for constructing container-type <span class="type">GVariant</span> instances.
</p>
<p>This is an opaque structure and may only be accessed using the
following functions.
</p>
<p><span class="type">GVariantBuilder</span> is not threadsafe in any way.  Do not attempt to
access it from more than one thread.</p>
</div>
<div class="refsect1">
<a name="id-1.1.85.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.85.3.2"></a><h3>add-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-builder:add-value self value))
</pre></div>
<p>Adds <em class="parameter"><code>value</code></em> to <em class="parameter"><code>builder</code></em>.
</p>
<p>It is an error to call this function in any way that would create an
inconsistent value to be constructed.  Some examples of this are
putting different types of items into an array, putting the wrong
types or number of items in a tuple, putting more than one value into
a variant, etc.
</p>
<p>If <em class="parameter"><code>value</code></em> is a floating reference (see <code class="function">g_variant_ref_sink()</code>),
the <em class="parameter"><code>builder</code></em> instance takes ownership of <em class="parameter"><code>value</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.85.3.2.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariant</span></p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.85.3.3"></a><h3>close</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-builder:close self))
</pre></div>
<p>Closes the subcontainer inside the given <em class="parameter"><code>builder</code></em> that was opened by
the most recent call to <code class="function">g_variant_builder_open()</code>.
</p>
<p>It is an error to call this function in any way that would create an
inconsistent value to be constructed (ie: too few values added to the
subcontainer).</p>
<div class="refsect3">
<a name="id-1.1.85.3.3.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</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.85.3.4"></a><h3>end</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-builder:end self))
</pre></div>
<p>Ends the builder process and returns the constructed value.
</p>
<p>It is not permissible to use <em class="parameter"><code>builder</code></em> in any way after this call
except for reference counting operations (in the case of a
heap-allocated <span class="type">GVariantBuilder</span>) or by reinitialising it with
<code class="function">g_variant_builder_init()</code> (in the case of stack-allocated). This
means that for the stack-allocated builders there is no need to
call <code class="function">g_variant_builder_clear()</code> after the call to
<code class="function">g_variant_builder_end()</code>.
</p>
<p>It is an error to call this function in any way that would create an
inconsistent value to be constructed (ie: insufficient number of
items added to a container with a specific number of children
required).  It is also an error to call this function if the builder
was created with an indefinite array or maybe type and no children
have been added; in this case it is impossible to infer the type of
the empty array.</p>
<div class="refsect3">
<a name="id-1.1.85.3.4.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</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.85.3.5"></a><h3>open</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-builder:open self type))
</pre></div>
<p>Opens a subcontainer inside the given <em class="parameter"><code>builder</code></em>.  When done adding
items to the subcontainer, <code class="function">g_variant_builder_close()</code> must be called. <em class="parameter"><code>type</code></em>
is the type of the container: so to build a tuple of several values, <em class="parameter"><code>type</code></em>
must include the tuple itself.
</p>
<p>It is an error to call this function in any way that would cause an
inconsistent value to be constructed (ie: adding too many values or
a value of an incorrect type).
</p>
<p>Example of building a nested variant:
</p>
<div class="informalexample"><pre class="programlisting">
GVariantBuilder builder;
guint32 some_number = get_number ();
g_autoptr (GHashTable) some_dict = get_dict ();
GHashTableIter iter;
const gchar *key;
const GVariant *value;
g_autoptr (GVariant) output = NULL;

g_variant_builder_init (&amp;builder, G_VARIANT_TYPE ("(ua{sv})"));
g_variant_builder_add (&amp;builder, "u", some_number);
g_variant_builder_open (&amp;builder, G_VARIANT_TYPE ("a{sv}"));

g_hash_table_iter_init (&amp;iter, some_dict);
while (g_hash_table_iter_next (&amp;iter, (gpointer *) &amp;key, (gpointer *) &amp;value))
  {
    g_variant_builder_open (&amp;builder, G_VARIANT_TYPE ("{sv}"));
    g_variant_builder_add (&amp;builder, "s", key);
    g_variant_builder_add (&amp;builder, "v", value);
    g_variant_builder_close (&amp;builder);
  }

g_variant_builder_close (&amp;builder);

output = g_variant_builder_end (&amp;builder);
</pre></div>
<div class="refsect3">
<a name="id-1.1.85.3.5.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description">
<p>the <span class="type">GVariantType</span> of the container</p>
<p>Passed as <code class="code">type</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.85.3.6"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-builder:ref self))
</pre></div>
<p>Increases the reference count on <em class="parameter"><code>builder</code></em>.
</p>
<p>Don't call this on stack-allocated <span class="type">GVariantBuilder</span> instances or bad
things will happen.</p>
<div class="refsect3">
<a name="id-1.1.85.3.6.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</span> allocated by <code class="function">g_variant_builder_new()</code></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.85.3.7"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (variant-builder:unref self))
</pre></div>
<p>Decreases the reference count on <em class="parameter"><code>builder</code></em>.
</p>
<p>In the event that there are no more references, releases all memory
associated with the <span class="type">GVariantBuilder</span>.
</p>
<p>Don't call this on stack-allocated <span class="type">GVariantBuilder</span> instances or bad
things will happen.</p>
<div class="refsect3">
<a name="id-1.1.85.3.7.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>builder</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantBuilder</span> allocated by <code class="function">g_variant_builder_new()</code></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.85.3.8"></a><h3>variant-builder:new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-builder:new type))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.85.3.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">type</code></p>
</td>
</tr></table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>