docs/reference/glib/tmpl/quarks.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Quarks
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a 2-way association between a string and a unique integer identifier.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Quarks are associations between strings and integer identifiers.
  10 Given either the string or the #GQuark identifier it is possible to
  11 retrieve the other.
  12 </para>
  13 <para>
  14 Quarks are used for both
  15 <link linkend="glib-datasets">Datasets</link> and
  16 <link linkend="glib-keyed-data-lists">Keyed Data Lists</link>.
  17 </para>
  18 <para>
  19 To create a new quark from a string, use g_quark_from_string() or
  20 g_quark_from_static_string().
  21 </para>
  22 <para>
  23 To find the string corresponding to a given #GQuark, use g_quark_to_string().
  24 </para>
  25 <para>
  26 To find the #GQuark corresponding to a given string, use g_quark_try_string().
  27 </para>
  28
  29 <!-- ##### SECTION See_Also ##### -->
  30 <para>
  31
  32 </para>
  33
  34 <!-- ##### TYPEDEF GQuark ##### -->
  35 <para>
  36 A GQuark is an integer which uniquely identifies a particular string.
  37 </para>
  38
  39
  40 <!-- ##### FUNCTION g_quark_from_string ##### -->
  41 <para>
  42 Gets the #GQuark identifying the given string.
  43 If the string does not currently have an associated #GQuark, a new
  44 #GQuark is created, using a copy of the string.
  45 </para>
  46
  47 @string: a string.
  48 @Returns: the #GQuark identifying the string.
  49
  50
  51 <!-- ##### FUNCTION g_quark_from_static_string ##### -->
  52 <para>
  53 Gets the #GQuark identifying the given (static) string.
  54 If the string does not currently have an associated #GQuark, a new
  55 #GQuark is created, linked to the given string.
  56 </para>
  57 <para>
  58 Note that this function is identical to g_quark_from_string() except
  59 that if a new #GQuark is created the string itself is used rather than
  60 a copy. This saves memory, but can only be used if the string will
  61 <emphasis>always</emphasis> exist. It can be used with statically
  62 allocated strings in the main program, but not with statically
  63 allocated memory in dynamically loaded modules, if you expect to
  64 ever unload the module again (e.g. do not use this function in
  65 GTK+ theme engines).
  66 </para>
  67
  68 @string: a string.
  69 @Returns: the #GQuark identifying the string.
  70
  71
  72 <!-- ##### FUNCTION g_quark_to_string ##### -->
  73 <para>
  74 Gets the string associated with the given #GQuark.
  75 </para>
  76
  77 @quark: a #GQuark.
  78 @Returns: the string associated with the #GQuark.
  79
  80
  81 <!-- ##### FUNCTION g_quark_try_string ##### -->
  82 <para>
  83 Gets the #GQuark associated with the given string, or 0 if the string has
  84 no associated #GQuark.
  85 </para>
  86 <para>
  87 If you want the GQuark to be created if it doesn't already exist, use
  88 g_quark_from_string() or g_quark_from_static_string().
  89 </para>
  90
  91 @string: a string.
  92 @Returns: the #GQuark associated with the string, or 0 if there is no
  93 #GQuark associated with the string.
  94
  95