<refentry id="glib-Quarks"> <refmeta> <refentrytitle>Quarks</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>GLIB Library</refmiscinfo> </refmeta> <refnamediv> <refname>Quarks</refname><refpurpose>a 2-way association between a string and a unique integer identifier.</refpurpose> </refnamediv> <refsynopsisdiv><title>Synopsis</title> <synopsis> #include <glib.h> typedef <link linkend="GQuark">GQuark</link>; <link linkend="GQuark">GQuark</link> <link linkend="g-quark-from-string">g_quark_from_string</link> (const <link linkend="gchar">gchar</link> *string); <link linkend="GQuark">GQuark</link> <link linkend="g-quark-from-static-string">g_quark_from_static_string</link> (const <link linkend="gchar">gchar</link> *string); G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-quark-to-string">g_quark_to_string</link> (<link linkend="GQuark">GQuark</link> quark); <link linkend="GQuark">GQuark</link> <link linkend="g-quark-try-string">g_quark_try_string</link> (const <link linkend="gchar">gchar</link> *string); </synopsis> </refsynopsisdiv> <refsect1> <title>Description</title> <para> Quarks are associations between strings and integer identifiers. Given either the string or the <link linkend="GQuark"><type>GQuark</type></link> identifier it is possible to retrieve the other. </para> <para> Quarks are used for both <link linkend="glib-datasets">Datasets</link> and <link linkend="glib-keyed-data-lists">Keyed Data Lists</link>. </para> <para> To create a new quark from a string, use <link linkend="g-quark-from-string"><function>g_quark_from_string()</function></link> or <link linkend="g-quark-from-static-string"><function>g_quark_from_static_string()</function></link>. </para> <para> To find the string corresponding to a given <link linkend="GQuark"><type>GQuark</type></link>, use <link linkend="g-quark-to-string"><function>g_quark_to_string()</function></link>. </para> <para> To find the <link linkend="GQuark"><type>GQuark</type></link> corresponding to a given string, use <link linkend="g-quark-try-string"><function>g_quark_try_string()</function></link>. </para> </refsect1> <refsect1> <title>Details</title> <refsect2> <title><anchor id="GQuark"/>GQuark</title> <indexterm><primary>GQuark</primary></indexterm><programlisting>typedef guint32 GQuark; </programlisting> <para> A GQuark is an integer which uniquely identifies a particular string. </para></refsect2> <refsect2> <title><anchor id="g-quark-from-string"/>g_quark_from_string ()</title> <indexterm><primary>g_quark_from_string</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link> g_quark_from_string (const <link linkend="gchar">gchar</link> *string);</programlisting> <para> Gets the <link linkend="GQuark"><type>GQuark</type></link> identifying the given string. If the string does not currently have an associated <link linkend="GQuark"><type>GQuark</type></link>, a new <link linkend="GQuark"><type>GQuark</type></link> is created, using a copy of the string. </para><variablelist role="params"> <varlistentry><term><parameter>string</parameter> :</term> <listitem><simpara>a string. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GQuark"><type>GQuark</type></link> identifying the string. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-quark-from-static-string"/>g_quark_from_static_string ()</title> <indexterm><primary>g_quark_from_static_string</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link> g_quark_from_static_string (const <link linkend="gchar">gchar</link> *string);</programlisting> <para> Gets the <link linkend="GQuark"><type>GQuark</type></link> identifying the given (static) string. If the string does not currently have an associated <link linkend="GQuark"><type>GQuark</type></link>, a new <link linkend="GQuark"><type>GQuark</type></link> is created, linked to the given string. </para> <para> Note that this function is identical to <link linkend="g-quark-from-string"><function>g_quark_from_string()</function></link> except that if a new <link linkend="GQuark"><type>GQuark</type></link> is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will always exist (if, for example, it is a statically-allocated string). </para><variablelist role="params"> <varlistentry><term><parameter>string</parameter> :</term> <listitem><simpara>a string. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GQuark"><type>GQuark</type></link> identifying the string. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-quark-to-string"/>g_quark_to_string ()</title> <indexterm><primary>g_quark_to_string</primary></indexterm><programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_quark_to_string (<link linkend="GQuark">GQuark</link> quark);</programlisting> <para> Gets the string associated with the given <link linkend="GQuark"><type>GQuark</type></link>. </para><variablelist role="params"> <varlistentry><term><parameter>quark</parameter> :</term> <listitem><simpara>a <link linkend="GQuark"><type>GQuark</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the string associated with the <link linkend="GQuark"><type>GQuark</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-quark-try-string"/>g_quark_try_string ()</title> <indexterm><primary>g_quark_try_string</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link> g_quark_try_string (const <link linkend="gchar">gchar</link> *string);</programlisting> <para> Gets the <link linkend="GQuark"><type>GQuark</type></link> associated with the given string, or 0 if the string has no associated <link linkend="GQuark"><type>GQuark</type></link>. </para> <para> If you want the GQuark to be created if it doesn't already exist, use <link linkend="g-quark-from-string"><function>g_quark_from_string()</function></link> or <link linkend="g-quark-from-static-string"><function>g_quark_from_static_string()</function></link>. </para><variablelist role="params"> <varlistentry><term><parameter>string</parameter> :</term> <listitem><simpara>a string. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GQuark"><type>GQuark</type></link> associated with the string, or 0 if there is no <link linkend="GQuark"><type>GQuark</type></link> associated with the string. </simpara></listitem></varlistentry> </variablelist></refsect2> </refsect1> </refentry>