quarks.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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 &lt;glib.h&gt;


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">GQuark</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">g_quark_from_string</link>() or
<link linkend="g-quark-from-static-string">g_quark_from_static_string</link>().
</para>
<para>
To find the string corresponding to a given <link linkend="GQuark">GQuark</link>, use <link linkend="g-quark-to-string">g_quark_to_string</link>().
</para>
<para>
To find the <link linkend="GQuark">GQuark</link> corresponding to a given string, use <link linkend="g-quark-try-string">g_quark_try_string</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GQuark">GQuark</title>
<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>
<programlisting><link linkend="GQuark">GQuark</link>      g_quark_from_string             (const <link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Gets the <link linkend="GQuark">GQuark</link> identifying the given string.
If the string does not currently have an associated <link linkend="GQuark">GQuark</link>, a new
<link linkend="GQuark">GQuark</link> is created, using a copy of the string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GQuark">GQuark</link> identifying the string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-quark-from-static-string">g_quark_from_static_string ()</title>
<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">GQuark</link> identifying the given (static) string.
If the string does not currently have an associated <link linkend="GQuark">GQuark</link>, a new
<link linkend="GQuark">GQuark</link> is created, linked to the given string.
</para>
<para>
Note that this function is identical to <link linkend="g-quark-from-string">g_quark_from_string</link>() except
that if a new <link linkend="GQuark">GQuark</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GQuark">GQuark</link> identifying the string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-quark-to-string">g_quark_to_string ()</title>
<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">GQuark</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>quark</parameter>&nbsp;:</entry>
<entry>a <link linkend="GQuark">GQuark</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the string associated with the <link linkend="GQuark">GQuark</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-quark-try-string">g_quark_try_string ()</title>
<programlisting><link linkend="GQuark">GQuark</link>      g_quark_try_string              (const <link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Gets the <link linkend="GQuark">GQuark</link> associated with the given string, or 0 if the string has
no associated <link linkend="GQuark">GQuark</link>.
</para>
<para>
If you want the GQuark to be created if it doesn't already exist, use
<link linkend="g-quark-from-string">g_quark_from_string</link>() or <link linkend="g-quark-from-static-string">g_quark_from_static_string</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GQuark">GQuark</link> associated with the string, or 0 if there is no
<link linkend="GQuark">GQuark</link> associated with the string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>