<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-Keyed-Data-Lists">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Keyed-Data-Lists.top_of_page">Keyed Data Lists</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Keyed Data Lists</refname>
<refpurpose>lists of data elements which are accessible by a
string or GQuark identifier</refpurpose>
</refnamediv>

<refsect1 id="glib-Keyed-Data-Lists.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-init">g_datalist_init</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-id-set-data">g_datalist_id_set_data</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-id-set-data-full">g_datalist_id_set_data_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-id-get-data">g_datalist_id_get_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-id-remove-data">g_datalist_id_remove_data</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-id-remove-no-notify">g_datalist_id_remove_no_notify</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GDuplicateFunc">*GDuplicateFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-id-dup-data">g_datalist_id_dup_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-id-replace-data">g_datalist_id_replace_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-set-data">g_datalist_set_data</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-set-data-full">g_datalist_set_data_full</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-get-data">g_datalist_get_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-remove-data">g_datalist_remove_data</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-datalist-remove-no-notify">g_datalist_remove_no_notify</link><phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-foreach">g_datalist_foreach</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-clear">g_datalist_clear</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-set-flags">g_datalist_set_flags</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-unset-flags">g_datalist_unset_flags</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-datalist-get-flags">g_datalist_get_flags</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Keyed-Data-Lists.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GData">GData</link></entry></row>



<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-DATALIST-FLAGS-MASK:CAPS">G_DATALIST_FLAGS_MASK</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Keyed-Data-Lists.includes"><title>Includes</title><synopsis>#include &lt;gmodule.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Keyed-Data-Lists.description" role="desc">
<title role="desc.title">Description</title>
<para>Keyed data lists provide lists of arbitrary data elements which can
be accessed either with a string or with a <link linkend="GQuark"><type>GQuark</type></link> corresponding to
the string.</para>
<para>The <link linkend="GQuark"><type>GQuark</type></link> methods are quicker, since the strings have to be
converted to <link linkend="GQuarks"><type>GQuarks</type></link> anyway.</para>
<para>Data lists are used for associating arbitrary data with <link linkend="GObjects"><type>GObjects</type></link>,
using <link linkend="g-object-set-data"><function>g_object_set_data()</function></link> and related functions.</para>
<para>To create a datalist, use <link linkend="g-datalist-init"><function>g_datalist_init()</function></link>.</para>
<para>To add data elements to a datalist use <link linkend="g-datalist-id-set-data"><function>g_datalist_id_set_data()</function></link>,
<link linkend="g-datalist-id-set-data-full"><function>g_datalist_id_set_data_full()</function></link>, <link linkend="g-datalist-set-data"><function>g_datalist_set_data()</function></link> and
<link linkend="g-datalist-set-data-full"><function>g_datalist_set_data_full()</function></link>.</para>
<para>To get data elements from a datalist use <link linkend="g-datalist-id-get-data"><function>g_datalist_id_get_data()</function></link>
and <link linkend="g-datalist-get-data"><function>g_datalist_get_data()</function></link>.</para>
<para>To iterate over all data elements in a datalist use
<link linkend="g-datalist-foreach"><function>g_datalist_foreach()</function></link> (not thread-safe).</para>
<para>To remove data elements from a datalist use
<link linkend="g-datalist-id-remove-data"><function>g_datalist_id_remove_data()</function></link> and <link linkend="g-datalist-remove-data"><function>g_datalist_remove_data()</function></link>.</para>
<para>To remove all data elements from a datalist, use <link linkend="g-datalist-clear"><function>g_datalist_clear()</function></link>.</para>

</refsect1>
<refsect1 id="glib-Keyed-Data-Lists.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-datalist-init" role="function">
<title>g_datalist_init&#160;()</title>
<indexterm zone="g-datalist-init"><primary sortas="datalist_init">g_datalist_init</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_init (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>);</programlisting>
<para>Resets the datalist to <link linkend="NULL:CAPS"><literal>NULL</literal></link>. It does not free any memory or call
any destroy functions.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-init.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a pointer to a pointer to a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-set-data" role="macro">
<title>g_datalist_id_set_data()</title>
<indexterm zone="g-datalist-id-set-data"><primary sortas="datalist_id_set_data">g_datalist_id_set_data</primary></indexterm>
<programlisting language="C">#define             g_datalist_id_set_data(dl, q, d)</programlisting>
<para>Sets the data corresponding to the given <link linkend="GQuark"><type>GQuark</type></link> id. Any previous
data with the same key is removed, and its destroy function is
called.</para>
<refsect3 id="g-datalist-id-set-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>q</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> to identify the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>d</para></entry>
<entry role="parameter_description"><para>the data element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to remove any previous element
corresponding to <parameter>q</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-set-data-full" role="function">
<title>g_datalist_id_set_data_full&#160;()</title>
<indexterm zone="g-datalist-id-set-data-full"><primary sortas="datalist_id_set_data_full">g_datalist_id_set_data_full</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_id_set_data_full (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                             <parameter><link linkend="GQuark"><type>GQuark</type></link> key_id</parameter>,
                             <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                             <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy_func</parameter>);</programlisting>
<para>Sets the data corresponding to the given <link linkend="GQuark"><type>GQuark</type></link> id, and the
function to be called when the element is removed from the datalist.
Any previous data with the same key is removed, and its destroy
function is called.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-id-set-data-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key_id</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> to identify the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>the data element or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to remove any previous element
corresponding to <parameter>key_id</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>destroy_func</para></entry>
<entry role="parameter_description"><para>the function to call when the data element is
removed. This function will be called with the data
element and can be used to free any memory allocated
for it. If <parameter>data</parameter>
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, then <parameter>destroy_func</parameter>
must
also be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-get-data" role="function">
<title>g_datalist_id_get_data&#160;()</title>
<indexterm zone="g-datalist-id-get-data"><primary sortas="datalist_id_get_data">g_datalist_id_get_data</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_datalist_id_get_data (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                        <parameter><link linkend="GQuark"><type>GQuark</type></link> key_id</parameter>);</programlisting>
<para>Retrieves the data element corresponding to <parameter>key_id</parameter>
.</para>
<refsect3 id="g-datalist-id-get-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key_id</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> identifying a data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-id-get-data.returns" role="returns">
<title>Returns</title>
<para>the data element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
it is not found. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-remove-data" role="macro">
<title>g_datalist_id_remove_data()</title>
<indexterm zone="g-datalist-id-remove-data"><primary sortas="datalist_id_remove_data">g_datalist_id_remove_data</primary></indexterm>
<programlisting language="C">#define             g_datalist_id_remove_data(dl, q)</programlisting>
<para>Removes an element, using its <link linkend="GQuark"><type>GQuark</type></link> identifier.</para>
<refsect3 id="g-datalist-id-remove-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>q</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> identifying the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-remove-no-notify" role="function">
<title>g_datalist_id_remove_no_notify&#160;()</title>
<indexterm zone="g-datalist-id-remove-no-notify"><primary sortas="datalist_id_remove_no_notify">g_datalist_id_remove_no_notify</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_datalist_id_remove_no_notify (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                                <parameter><link linkend="GQuark"><type>GQuark</type></link> key_id</parameter>);</programlisting>
<para>Removes an element, without calling its destroy notification
function.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-id-remove-no-notify.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key_id</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> identifying a data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-id-remove-no-notify.returns" role="returns">
<title>Returns</title>
<para>the data previously stored at <parameter>key_id</parameter>
,
or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="GDuplicateFunc" role="function">
<title>GDuplicateFunc&#160;()</title>
<indexterm zone="GDuplicateFunc"><primary sortas="DuplicateFunc">GDuplicateFunc</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GDuplicateFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                   <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>The type of functions that are used to 'duplicate' an object.
What this means depends on the context, it could just be
incrementing the reference count, if <parameter>data</parameter>
 is a ref-counted
object.</para>
<refsect3 id="GDuplicateFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>the data to duplicate</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data that was specified in
<link linkend="g-datalist-id-dup-data"><function>g_datalist_id_dup_data()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GDuplicateFunc.returns" role="returns">
<title>Returns</title>
<para> a duplicate of data</para>
</refsect3></refsect2>
<refsect2 id="g-datalist-id-dup-data" role="function" condition="since:2.34">
<title>g_datalist_id_dup_data&#160;()</title>
<indexterm zone="g-datalist-id-dup-data" role="2.34"><primary sortas="datalist_id_dup_data">g_datalist_id_dup_data</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_datalist_id_dup_data (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                        <parameter><link linkend="GQuark"><type>GQuark</type></link> key_id</parameter>,
                        <parameter><link linkend="GDuplicateFunc"><type>GDuplicateFunc</type></link> dup_func</parameter>,
                        <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>This is a variant of <link linkend="g-datalist-id-get-data"><function>g_datalist_id_get_data()</function></link> which
returns a 'duplicate' of the value. <parameter>dup_func</parameter>
 defines the
meaning of 'duplicate' in this context, it could e.g.
take a reference on a ref-counted object.</para>
<para>If the <parameter>key_id</parameter>
 is not set in the datalist then <parameter>dup_func</parameter>

will be called with a <link linkend="NULL:CAPS"><literal>NULL</literal></link> argument.</para>
<para>Note that <parameter>dup_func</parameter>
 is called while the datalist is locked, so it
is not allowed to read or modify the datalist.</para>
<para>This function can be useful to avoid races when multiple
threads are using the same datalist and the same key.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-id-dup-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>location of a datalist</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key_id</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> identifying a data element</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dup_func</para></entry>
<entry role="parameter_description"><para>function to duplicate the old value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>scope call</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>passed as user_data to <parameter>dup_func</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-id-dup-data.returns" role="returns">
<title>Returns</title>
<para>the result of calling <parameter>dup_func</parameter>
on the value
associated with <parameter>key_id</parameter>
in <parameter>datalist</parameter>
, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if not set.
If <parameter>dup_func</parameter>
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the value is returned unmodified. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.34">2.34</link></para></refsect2>
<refsect2 id="g-datalist-id-replace-data" role="function" condition="since:2.34">
<title>g_datalist_id_replace_data&#160;()</title>
<indexterm zone="g-datalist-id-replace-data" role="2.34"><primary sortas="datalist_id_replace_data">g_datalist_id_replace_data</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_datalist_id_replace_data (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                            <parameter><link linkend="GQuark"><type>GQuark</type></link> key_id</parameter>,
                            <parameter><link linkend="gpointer"><type>gpointer</type></link> oldval</parameter>,
                            <parameter><link linkend="gpointer"><type>gpointer</type></link> newval</parameter>,
                            <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy</parameter>,
                            <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> *old_destroy</parameter>);</programlisting>
<para>Compares the member that is associated with <parameter>key_id</parameter>
 in
<parameter>datalist</parameter>
 to <parameter>oldval</parameter>
, and if they are the same, replace
<parameter>oldval</parameter>
 with <parameter>newval</parameter>
.</para>
<para>This is like a typical atomic compare-and-exchange
operation, for a member of <parameter>datalist</parameter>
.</para>
<para>If the previous value was replaced then ownership of the
old value (<parameter>oldval</parameter>
) is passed to the caller, including
the registered destroy notify for it (passed out in <parameter>old_destroy</parameter>
).
Its up to the caller to free this as he wishes, which may
or may not include using <parameter>old_destroy</parameter>
 as sometimes replacement
should not destroy the object in the normal way.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-id-replace-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>location of a datalist</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key_id</para></entry>
<entry role="parameter_description"><para>the <link linkend="GQuark"><type>GQuark</type></link> identifying a data element</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>oldval</para></entry>
<entry role="parameter_description"><para>the old value to compare against. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>newval</para></entry>
<entry role="parameter_description"><para>the new value to replace it with. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>destroy</para></entry>
<entry role="parameter_description"><para>destroy notify for the new value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>old_destroy</para></entry>
<entry role="parameter_description"><para>destroy notify for the existing value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-id-replace-data.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the existing value for <parameter>key_id</parameter>
was replaced
by <parameter>newval</parameter>
, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.34">2.34</link></para></refsect2>
<refsect2 id="g-datalist-set-data" role="macro">
<title>g_datalist_set_data()</title>
<indexterm zone="g-datalist-set-data"><primary sortas="datalist_set_data">g_datalist_set_data</primary></indexterm>
<programlisting language="C">#define             g_datalist_set_data(dl, k, d)</programlisting>
<para>Sets the data element corresponding to the given string identifier.</para>
<refsect3 id="g-datalist-set-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>k</para></entry>
<entry role="parameter_description"><para>the string to identify the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>d</para></entry>
<entry role="parameter_description"><para>the data element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to remove any previous element
corresponding to <parameter>k</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-set-data-full" role="macro">
<title>g_datalist_set_data_full()</title>
<indexterm zone="g-datalist-set-data-full"><primary sortas="datalist_set_data_full">g_datalist_set_data_full</primary></indexterm>
<programlisting language="C">#define             g_datalist_set_data_full(dl, k, d, f)</programlisting>
<para>Sets the data element corresponding to the given string identifier,
and the function to be called when the data element is removed.</para>
<refsect3 id="g-datalist-set-data-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>k</para></entry>
<entry role="parameter_description"><para>the string to identify the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>d</para></entry>
<entry role="parameter_description"><para>the data element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to remove any previous element
corresponding to <parameter>k</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>f</para></entry>
<entry role="parameter_description"><para>the function to call when the data element is removed.
This function will be called with the data element and can be used to
free any memory allocated for it. If <parameter>d</parameter>
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, then <parameter>f</parameter>
must
also be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-get-data" role="function">
<title>g_datalist_get_data&#160;()</title>
<indexterm zone="g-datalist-get-data"><primary sortas="datalist_get_data">g_datalist_get_data</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_datalist_get_data (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>);</programlisting>
<para>Gets a data element, using its string identifier. This is slower than
<link linkend="g-datalist-id-get-data"><function>g_datalist_id_get_data()</function></link> because it compares strings.</para>
<refsect3 id="g-datalist-get-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>key</para></entry>
<entry role="parameter_description"><para>the string identifying a data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-get-data.returns" role="returns">
<title>Returns</title>
<para>the data element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if it
is not found. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-datalist-remove-data" role="macro">
<title>g_datalist_remove_data()</title>
<indexterm zone="g-datalist-remove-data"><primary sortas="datalist_remove_data">g_datalist_remove_data</primary></indexterm>
<programlisting language="C">#define             g_datalist_remove_data(dl, k)</programlisting>
<para>Removes an element using its string identifier. The data element's
destroy function is called if it has been set.</para>
<refsect3 id="g-datalist-remove-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>k</para></entry>
<entry role="parameter_description"><para>the string identifying the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-remove-no-notify" role="macro">
<title>g_datalist_remove_no_notify()</title>
<indexterm zone="g-datalist-remove-no-notify"><primary sortas="datalist_remove_no_notify">g_datalist_remove_no_notify</primary></indexterm>
<programlisting language="C">#define             g_datalist_remove_no_notify(dl, k)</programlisting>
<para>Removes an element, without calling its destroy notifier.</para>
<refsect3 id="g-datalist-remove-no-notify.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dl</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>k</para></entry>
<entry role="parameter_description"><para>the string identifying the data element.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-foreach" role="function">
<title>g_datalist_foreach&#160;()</title>
<indexterm zone="g-datalist-foreach"><primary sortas="datalist_foreach">g_datalist_foreach</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_foreach (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                    <parameter><link linkend="GDataForeachFunc"><type>GDataForeachFunc</type></link> func</parameter>,
                    <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>Calls the given function for each data element of the datalist. The
function is called with each data element's <link linkend="GQuark"><type>GQuark</type></link> id and data,
together with the given <parameter>user_data</parameter>
 parameter. Note that this
function is NOT thread-safe. So unless <parameter>datalist</parameter>
 can be protected
from any modifications during invocation of this function, it should
not be called.</para>
<para><parameter>func</parameter>
 can make changes to <parameter>datalist</parameter>
, but the iteration will not
reflect changes made during the <link linkend="g-datalist-foreach"><function>g_datalist_foreach()</function></link> call, other
than skipping over elements that are removed.</para>
<refsect3 id="g-datalist-foreach.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>the function to call for each data element. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>scope call</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data to pass to the function. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-clear" role="function">
<title>g_datalist_clear&#160;()</title>
<indexterm zone="g-datalist-clear"><primary sortas="datalist_clear">g_datalist_clear</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_clear (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>);</programlisting>
<para>Frees all the data elements of the datalist.
The data elements' destroy functions are called
if they have been set.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-datalist-clear.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>a datalist.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-datalist-set-flags" role="function" condition="since:2.8">
<title>g_datalist_set_flags&#160;()</title>
<indexterm zone="g-datalist-set-flags" role="2.8"><primary sortas="datalist_set_flags">g_datalist_set_flags</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_set_flags (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> flags</parameter>);</programlisting>
<para>Turns on flag values for a data list. This function is used
to keep a small number of boolean flags in an object with
a data list without using any additional space. It is
not generally useful except in circumstances where space
is very tight. (It is used in the base <link linkend="GObject"><type>GObject</type></link> type, for
example.)</para>
<refsect3 id="g-datalist-set-flags.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>pointer to the location that holds a list</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>the flags to turn on. The values of the flags are
restricted by <link linkend="G-DATALIST-FLAGS-MASK:CAPS"><literal>G_DATALIST_FLAGS_MASK</literal></link> (currently
3; giving two possible boolean flags).
A value for <parameter>flags</parameter>
that doesn't fit within the mask is
an error.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-datalist-unset-flags" role="function" condition="since:2.8">
<title>g_datalist_unset_flags&#160;()</title>
<indexterm zone="g-datalist-unset-flags" role="2.8"><primary sortas="datalist_unset_flags">g_datalist_unset_flags</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_datalist_unset_flags (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>,
                        <parameter><link linkend="guint"><type>guint</type></link> flags</parameter>);</programlisting>
<para>Turns off flag values for a data list. See <link linkend="g-datalist-unset-flags"><function>g_datalist_unset_flags()</function></link></para>
<refsect3 id="g-datalist-unset-flags.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>pointer to the location that holds a list</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>the flags to turn off. The values of the flags are
restricted by <link linkend="G-DATALIST-FLAGS-MASK:CAPS"><literal>G_DATALIST_FLAGS_MASK</literal></link> (currently
3: giving two possible boolean flags).
A value for <parameter>flags</parameter>
that doesn't fit within the mask is
an error.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-datalist-get-flags" role="function" condition="since:2.8">
<title>g_datalist_get_flags&#160;()</title>
<indexterm zone="g-datalist-get-flags" role="2.8"><primary sortas="datalist_get_flags">g_datalist_get_flags</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_datalist_get_flags (<parameter><link linkend="GData"><type>GData</type></link> **datalist</parameter>);</programlisting>
<para>Gets flags values packed in together with the datalist.
See <link linkend="g-datalist-set-flags"><function>g_datalist_set_flags()</function></link>.</para>
<refsect3 id="g-datalist-get-flags.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>datalist</para></entry>
<entry role="parameter_description"><para>pointer to the location that holds a list</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-datalist-get-flags.returns" role="returns">
<title>Returns</title>
<para> the flags of the datalist</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>

</refsect1>
<refsect1 id="glib-Keyed-Data-Lists.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GData" role="struct">
<title>GData</title>
<indexterm zone="GData"><primary sortas="Data">GData</primary></indexterm>
<programlisting language="C">typedef struct _GData GData;</programlisting>
<para>The <link linkend="GData"><type>GData</type></link> struct is an opaque data structure to represent a
<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>. It should only be
accessed via the following functions.</para>
</refsect2>
<refsect2 id="G-DATALIST-FLAGS-MASK:CAPS" role="macro">
<title>G_DATALIST_FLAGS_MASK</title>
<indexterm zone="G-DATALIST-FLAGS-MASK:CAPS"><primary sortas="DATALIST_FLAGS_MASK">G_DATALIST_FLAGS_MASK</primary></indexterm>
<programlisting language="C">#define G_DATALIST_FLAGS_MASK 0x3
</programlisting>
<para>A bitmask that restricts the possible flags passed to
<link linkend="g-datalist-set-flags"><function>g_datalist_set_flags()</function></link>. Passing a flags value where
flags &amp; ~G_DATALIST_FLAGS_MASK != 0 is an error.</para>
</refsect2>

</refsect1>

</refentry>
