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 <para> 29 Another use for the string pool maintained for the quark functions is string 30 interning, using g_intern_string() or g_intern_static_string(). An interned string 31 is a canonical representation for a string. One important advantage of interned strings 32 is that they can be compared for equality by a simple pointer comparision, rather than 33 using strcmp(). 34 </para> 35 36 <!-- ##### SECTION See_Also ##### --> 37 <para> 38 39 </para> 40 41 <!-- ##### SECTION Stability_Level ##### --> 42 43 44 <!-- ##### TYPEDEF GQuark ##### --> 45 <para> 46 A GQuark is a non-zero integer which uniquely identifies a particular string. 47 A GQuark value of zero is associated to %NULL. 48 </para> 49 50 51 <!-- ##### FUNCTION g_quark_from_string ##### --> 52 <para> 53 Gets the #GQuark identifying the given string. 54 If the string does not currently have an associated #GQuark, a new 55 #GQuark is created, using a copy of the string. 56 </para> 57 58 @string: a string. 59 @Returns: the #GQuark identifying the string, or 0 if @string is %NULL. 60 61 62 <!-- ##### FUNCTION g_quark_from_static_string ##### --> 63 <para> 64 Gets the #GQuark identifying the given (static) string. 65 If the string does not currently have an associated #GQuark, a new 66 #GQuark is created, linked to the given string. 67 </para> 68 <para> 69 Note that this function is identical to g_quark_from_string() except 70 that if a new #GQuark is created the string itself is used rather than 71 a copy. This saves memory, but can only be used if the string will 72 <emphasis>always</emphasis> exist. It can be used with statically 73 allocated strings in the main program, but not with statically 74 allocated memory in dynamically loaded modules, if you expect to 75 ever unload the module again (e.g. do not use this function in 76 GTK+ theme engines). 77 </para> 78 79 @string: a string. 80 @Returns: the #GQuark identifying the string, or 0 if @string is %NULL. 81 82 83 <!-- ##### FUNCTION g_quark_to_string ##### --> 84 <para> 85 Gets the string associated with the given #GQuark. 86 </para> 87 88 @quark: a #GQuark. 89 @Returns: the string associated with the #GQuark. 90 91 92 <!-- ##### FUNCTION g_quark_try_string ##### --> 93 <para> 94 Gets the #GQuark associated with the given string, or 0 if string is 95 %NULL or it has no associated #GQuark. 96 </para> 97 <para> 98 If you want the GQuark to be created if it doesn't already exist, use 99 g_quark_from_string() or g_quark_from_static_string(). 100 </para> 101 102 @string: a string. 103 @Returns: the #GQuark associated with the string, or 0 if @string is 104 %NULL or there is no #GQuark associated with it. 105 106 107 <!-- ##### FUNCTION g_intern_string ##### --> 108 <para> 109 110 </para> 111 112 @string: 113 @Returns: 114 115 116 <!-- ##### FUNCTION g_intern_static_string ##### --> 117 <para> 118 119 </para> 120 121 @string: 122 @Returns: 123 124 125
