mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-20 23:58:54 +02:00
data{list,sets}, quarks: move docs from tmpl to .c
This commit is contained in:
3
docs/reference/glib/tmpl/.gitignore
vendored
3
docs/reference/glib/tmpl/.gitignore
vendored
@@ -1,5 +1,7 @@
|
|||||||
allocators.sgml
|
allocators.sgml
|
||||||
base64.sgml
|
base64.sgml
|
||||||
|
datasets.sgml
|
||||||
|
datalist.sgml
|
||||||
ghostutils.sgml
|
ghostutils.sgml
|
||||||
gurifuncs.sgml
|
gurifuncs.sgml
|
||||||
gvarianttype.sgml
|
gvarianttype.sgml
|
||||||
@@ -7,6 +9,7 @@ hash_tables.sgml
|
|||||||
memory_chunks.sgml
|
memory_chunks.sgml
|
||||||
option.sgml
|
option.sgml
|
||||||
patterns.sgml
|
patterns.sgml
|
||||||
|
quarks.sgml
|
||||||
random_numbers.sgml
|
random_numbers.sgml
|
||||||
sequence.sgml
|
sequence.sgml
|
||||||
shell.sgml
|
shell.sgml
|
||||||
|
@@ -1,244 +0,0 @@
|
|||||||
<!-- ##### SECTION Title ##### -->
|
|
||||||
Keyed Data Lists
|
|
||||||
|
|
||||||
<!-- ##### SECTION Short_Description ##### -->
|
|
||||||
lists of data elements which are accessible by a string or GQuark identifier
|
|
||||||
|
|
||||||
<!-- ##### SECTION Long_Description ##### -->
|
|
||||||
<para>
|
|
||||||
Keyed data lists provide lists of arbitrary data elements which can be accessed
|
|
||||||
either with a string or with a #GQuark corresponding to the
|
|
||||||
string.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The #GQuark methods are quicker, since the strings have to be converted to
|
|
||||||
#GQuarks anyway.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Data lists are used for associating arbitrary data with
|
|
||||||
#GObjects, using g_object_set_data() and related functions.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
To create a datalist, use g_datalist_init().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To add data elements to a datalist use g_datalist_id_set_data(),
|
|
||||||
g_datalist_id_set_data_full(), g_datalist_set_data()
|
|
||||||
and g_datalist_set_data_full().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To get data elements from a datalist use g_datalist_id_get_data() and
|
|
||||||
g_datalist_get_data().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To iterate over all data elements in a datalist use g_datalist_foreach() (not thread-safe).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To remove data elements from a datalist use g_datalist_id_remove_data() and
|
|
||||||
g_datalist_remove_data().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To remove all data elements from a datalist, use g_datalist_clear().
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION See_Also ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION Stability_Level ##### -->
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### STRUCT GData ##### -->
|
|
||||||
<para>
|
|
||||||
The #GData 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>
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_init ##### -->
|
|
||||||
<para>
|
|
||||||
Resets the datalist to %NULL.
|
|
||||||
It does not free any memory or call any destroy functions.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist: a pointer to a pointer to a datalist.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_id_set_data ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data corresponding to the given #GQuark id.
|
|
||||||
Any previous data with the same key is removed, and its
|
|
||||||
destroy function is called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@q: the #GQuark to identify the data element.
|
|
||||||
@d: the data element, or %NULL to remove any previous element
|
|
||||||
corresponding to @q.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_id_set_data_full ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data corresponding to the given #GQuark 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>
|
|
||||||
|
|
||||||
@datalist: a datalist.
|
|
||||||
@key_id: the #GQuark to identify the data element.
|
|
||||||
@data: the data element or %NULL to remove any previous element
|
|
||||||
corresponding to @key_id.
|
|
||||||
@destroy_func: 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 @data is %NULL, then @destroy_func must
|
|
||||||
also be %NULL.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_id_get_data ##### -->
|
|
||||||
<para>
|
|
||||||
Retrieves the data element corresponding to @key_id.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist: a datalist.
|
|
||||||
@key_id: the #GQuark identifying a data element.
|
|
||||||
@Returns: the data element, or %NULL if it is not found.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_id_remove_data ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element, using its #GQuark identifier.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@q: the #GQuark identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element, without calling its destroy notification function.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist: a datalist.
|
|
||||||
@key_id: the #GQuark identifying a data element.
|
|
||||||
@Returns: the data previously stored at @key_id, or %NULL if none.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_set_data ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data element corresponding to the given string identifier.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@k: the string to identify the data element.
|
|
||||||
@d: the data element, or %NULL to remove any previous element
|
|
||||||
corresponding to @k.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_set_data_full ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data element corresponding to the given string identifier, and the
|
|
||||||
function to be called when the data element is removed.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@k: the string to identify the data element.
|
|
||||||
@d: the data element, or %NULL to remove any previous element corresponding to
|
|
||||||
@k.
|
|
||||||
@f: 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 @d is %NULL, then @f must also be %NULL.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_get_data ##### -->
|
|
||||||
<para>
|
|
||||||
Gets a data element, using its string identifer.
|
|
||||||
This is slower than g_datalist_id_get_data() because the string is first
|
|
||||||
converted to a #GQuark.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@k: the string identifying a data element.
|
|
||||||
@Returns: the data element, or %NULL if it is not found.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_remove_data ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element using its string identifier.
|
|
||||||
The data element's destroy function is called if it has been set.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@k: the string identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_datalist_remove_no_notify ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element, without calling its destroy notifier.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dl: a datalist.
|
|
||||||
@k: the string identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_foreach ##### -->
|
|
||||||
<para>
|
|
||||||
Calls the given function for each data element of the datalist.
|
|
||||||
The function is called with each data element's #GQuark id and data,
|
|
||||||
together with the given @user_data parameter.
|
|
||||||
Note that this function is NOT thread-safe. So unless @datalist
|
|
||||||
can be protected from any modifications during invocation of this
|
|
||||||
function, it should not be called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist: a datalist.
|
|
||||||
@func: the function to call for each data element.
|
|
||||||
@user_data: user data to pass to the function.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_clear ##### -->
|
|
||||||
<para>
|
|
||||||
Frees all the data elements of the datalist.
|
|
||||||
The data elements' destroy functions are called if they have been set.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist: a datalist.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_set_flags ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist:
|
|
||||||
@flags:
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_unset_flags ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist:
|
|
||||||
@flags:
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_datalist_get_flags ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@datalist:
|
|
||||||
@Returns:
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO G_DATALIST_FLAGS_MASK ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@@ -1,212 +0,0 @@
|
|||||||
<!-- ##### SECTION Title ##### -->
|
|
||||||
Datasets
|
|
||||||
|
|
||||||
<!-- ##### SECTION Short_Description ##### -->
|
|
||||||
associate groups of data elements with particular memory locations
|
|
||||||
|
|
||||||
<!-- ##### SECTION Long_Description ##### -->
|
|
||||||
<para>
|
|
||||||
Datasets associate groups of data elements with particular memory locations.
|
|
||||||
These are useful if you need to associate data with a structure returned
|
|
||||||
from an external library. Since you cannot modify the structure, you use
|
|
||||||
its location in memory as the key into a dataset, where you can associate
|
|
||||||
any number of data elements with it.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
There are two forms of most of the dataset functions.
|
|
||||||
The first form uses strings to identify the data elements associated with
|
|
||||||
a location. The second form uses #GQuark identifiers, which are created
|
|
||||||
with a call to g_quark_from_string() or g_quark_from_static_string().
|
|
||||||
The second form is quicker, since it does not require looking up the string
|
|
||||||
in the hash table of #GQuark identifiers.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
There is no function to create a dataset. It is automatically created as
|
|
||||||
soon as you add elements to it.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To add data elements to a dataset use g_dataset_id_set_data(),
|
|
||||||
g_dataset_id_set_data_full(), g_dataset_set_data()
|
|
||||||
and g_dataset_set_data_full().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To get data elements from a dataset use g_dataset_id_get_data() and
|
|
||||||
g_dataset_get_data().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To iterate over all data elements in a dataset use g_dataset_foreach() (not thread-safe).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To remove data elements from a dataset use g_dataset_id_remove_data() and
|
|
||||||
g_dataset_remove_data().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To destroy a dataset, use g_dataset_destroy().
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION See_Also ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION Stability_Level ##### -->
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_id_set_data ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data element associated with the given #GQuark id.
|
|
||||||
Any previous data with the same key is removed, and its destroy function
|
|
||||||
is called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the #GQuark id to identify the data element.
|
|
||||||
@d: the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_dataset_id_set_data_full ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data element associated with the given #GQuark id, and also the
|
|
||||||
function to call when the data element is destroyed.
|
|
||||||
Any previous data with the same key is removed, and its
|
|
||||||
destroy function is called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dataset_location: the location identifying the dataset.
|
|
||||||
@key_id: the #GQuark id to identify the data element.
|
|
||||||
@data: the data element.
|
|
||||||
@destroy_func: 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.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### USER_FUNCTION GDestroyNotify ##### -->
|
|
||||||
<para>
|
|
||||||
Specifies the type of function which is called when a data element is
|
|
||||||
destroyed. It is passed the pointer to the data element and should free
|
|
||||||
any memory and resources allocated for it.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@data: the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_dataset_id_get_data ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the data element corresponding to a #GQuark.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dataset_location: the location identifying the dataset.
|
|
||||||
@key_id: the #GQuark id to identify the data element.
|
|
||||||
@Returns: the data element corresponding to the #GQuark, or %NULL if it is
|
|
||||||
not found.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_id_remove_data ##### -->
|
|
||||||
<para>
|
|
||||||
Removes a data element from a dataset.
|
|
||||||
The data element's destroy function is called if it has been set.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the #GQuark id identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element, without calling its destroy notification function.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dataset_location: the location identifying the dataset.
|
|
||||||
@key_id: the #GQuark ID identifying the data element.
|
|
||||||
@Returns: the data previously stored at @key_id, or %NULL if none.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_set_data ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data corresponding to the given string identifier.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the string to identify the data element.
|
|
||||||
@d: the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_set_data_full ##### -->
|
|
||||||
<para>
|
|
||||||
Sets the data corresponding to the given string identifier, and the function
|
|
||||||
to call when the data element is destroyed.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the string to identify the data element.
|
|
||||||
@d: the data element.
|
|
||||||
@f: 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.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_get_data ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the data element corresponding to a string.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the string identifying the data element.
|
|
||||||
@Returns: the data element corresponding to the string, or %NULL if it is not
|
|
||||||
found.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_remove_data ##### -->
|
|
||||||
<para>
|
|
||||||
Removes a data element corresponding to a string.
|
|
||||||
Its destroy function is called if it has been set.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the string identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### MACRO g_dataset_remove_no_notify ##### -->
|
|
||||||
<para>
|
|
||||||
Removes an element, without calling its destroy notifier.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@l: the location identifying the dataset.
|
|
||||||
@k: the string identifying the data element.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_dataset_foreach ##### -->
|
|
||||||
<para>
|
|
||||||
Calls the given function for each data element which is associated with the
|
|
||||||
given location.
|
|
||||||
Note that this function is NOT thread-safe. So unless @datalist
|
|
||||||
can be protected from any modifications during invocation of this
|
|
||||||
function, it should not be called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dataset_location: the location identifying the dataset.
|
|
||||||
@func: the function to call for each data element.
|
|
||||||
@user_data: user data to pass to the function.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### USER_FUNCTION GDataForeachFunc ##### -->
|
|
||||||
<para>
|
|
||||||
Specifies the type of function passed to g_dataset_foreach().
|
|
||||||
It is called with each #GQuark id and associated data element,
|
|
||||||
together with the @user_data parameter supplied to g_dataset_foreach().
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@key_id: the #GQuark id to identifying the data element.
|
|
||||||
@data: the data element.
|
|
||||||
@user_data: user data passed to g_dataset_foreach().
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_dataset_destroy ##### -->
|
|
||||||
<para>
|
|
||||||
Destroys the dataset, freeing all memory allocated, and calling any
|
|
||||||
destroy functions set for data elements.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@dataset_location: the location identifying the dataset.
|
|
||||||
|
|
||||||
|
|
@@ -1,124 +0,0 @@
|
|||||||
<!-- ##### SECTION Title ##### -->
|
|
||||||
Quarks
|
|
||||||
|
|
||||||
<!-- ##### SECTION Short_Description ##### -->
|
|
||||||
a 2-way association between a string and a unique integer identifier
|
|
||||||
|
|
||||||
<!-- ##### SECTION Long_Description ##### -->
|
|
||||||
<para>
|
|
||||||
Quarks are associations between strings and integer identifiers.
|
|
||||||
Given either the string or the #GQuark 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 g_quark_from_string() or
|
|
||||||
g_quark_from_static_string().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To find the string corresponding to a given #GQuark, use g_quark_to_string().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To find the #GQuark corresponding to a given string, use g_quark_try_string().
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Another use for the string pool maintained for the quark functions is string
|
|
||||||
interning, using g_intern_string() or g_intern_static_string(). An interned string
|
|
||||||
is a canonical representation for a string. One important advantage of interned strings
|
|
||||||
is that they can be compared for equality by a simple pointer comparision, rather than
|
|
||||||
using strcmp().
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION See_Also ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION Stability_Level ##### -->
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### TYPEDEF GQuark ##### -->
|
|
||||||
<para>
|
|
||||||
A GQuark is a non-zero integer which uniquely identifies a particular string.
|
|
||||||
A GQuark value of zero is associated to %NULL.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_quark_from_string ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the #GQuark identifying the given string.
|
|
||||||
If the string does not currently have an associated #GQuark, a new
|
|
||||||
#GQuark is created, using a copy of the string.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@string: a string.
|
|
||||||
@Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_quark_from_static_string ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the #GQuark identifying the given (static) string.
|
|
||||||
If the string does not currently have an associated #GQuark, a new
|
|
||||||
#GQuark is created, linked to the given string.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Note that this function is identical to g_quark_from_string() except
|
|
||||||
that if a new #GQuark is created the string itself is used rather than
|
|
||||||
a copy. This saves memory, but can only be used if the string will
|
|
||||||
<emphasis>always</emphasis> exist. It can be used with statically
|
|
||||||
allocated strings in the main program, but not with statically
|
|
||||||
allocated memory in dynamically loaded modules, if you expect to
|
|
||||||
ever unload the module again (e.g. do not use this function in
|
|
||||||
GTK+ theme engines).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@string: a string.
|
|
||||||
@Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_quark_to_string ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the string associated with the given #GQuark.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@quark: a #GQuark.
|
|
||||||
@Returns: the string associated with the #GQuark.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_quark_try_string ##### -->
|
|
||||||
<para>
|
|
||||||
Gets the #GQuark associated with the given string, or 0 if string is
|
|
||||||
%NULL or it has no associated #GQuark.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If you want the GQuark to be created if it doesn't already exist, use
|
|
||||||
g_quark_from_string() or g_quark_from_static_string().
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@string: a string.
|
|
||||||
@Returns: the #GQuark associated with the string, or 0 if @string is
|
|
||||||
%NULL or there is no #GQuark associated with it.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_intern_string ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@string:
|
|
||||||
@Returns:
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION g_intern_static_string ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@string:
|
|
||||||
@Returns:
|
|
||||||
|
|
||||||
|
|
428
glib/gdataset.c
428
glib/gdataset.c
@@ -38,6 +38,95 @@
|
|||||||
#include "gdatasetprivate.h"
|
#include "gdatasetprivate.h"
|
||||||
#include "galias.h"
|
#include "galias.h"
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SECTION: datasets
|
||||||
|
* @title: Datasets
|
||||||
|
* @short_description: associate groups of data elements with
|
||||||
|
* particular memory locations
|
||||||
|
*
|
||||||
|
* Datasets associate groups of data elements with particular memory
|
||||||
|
* locations. These are useful if you need to associate data with a
|
||||||
|
* structure returned from an external library. Since you cannot modify
|
||||||
|
* the structure, you use its location in memory as the key into a
|
||||||
|
* dataset, where you can associate any number of data elements with it.
|
||||||
|
*
|
||||||
|
* There are two forms of most of the dataset functions. The first form
|
||||||
|
* uses strings to identify the data elements associated with a
|
||||||
|
* location. The second form uses #GQuark identifiers, which are
|
||||||
|
* created with a call to g_quark_from_string() or
|
||||||
|
* g_quark_from_static_string(). The second form is quicker, since it
|
||||||
|
* does not require looking up the string in the hash table of #GQuark
|
||||||
|
* identifiers.
|
||||||
|
*
|
||||||
|
* There is no function to create a dataset. It is automatically
|
||||||
|
* created as soon as you add elements to it.
|
||||||
|
*
|
||||||
|
* To add data elements to a dataset use g_dataset_id_set_data(),
|
||||||
|
* g_dataset_id_set_data_full(), g_dataset_set_data() and
|
||||||
|
* g_dataset_set_data_full().
|
||||||
|
*
|
||||||
|
* To get data elements from a dataset use g_dataset_id_get_data() and
|
||||||
|
* g_dataset_get_data().
|
||||||
|
*
|
||||||
|
* To iterate over all data elements in a dataset use
|
||||||
|
* g_dataset_foreach() (not thread-safe).
|
||||||
|
*
|
||||||
|
* To remove data elements from a dataset use
|
||||||
|
* g_dataset_id_remove_data() and g_dataset_remove_data().
|
||||||
|
*
|
||||||
|
* To destroy a dataset, use g_dataset_destroy().
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SECTION: datalist
|
||||||
|
* @title: Keyed Data Lists
|
||||||
|
* @short_description: lists of data elements which are accessible by a
|
||||||
|
* string or GQuark identifier
|
||||||
|
*
|
||||||
|
* Keyed data lists provide lists of arbitrary data elements which can
|
||||||
|
* be accessed either with a string or with a #GQuark corresponding to
|
||||||
|
* the string.
|
||||||
|
*
|
||||||
|
* The #GQuark methods are quicker, since the strings have to be
|
||||||
|
* converted to #GQuarks anyway.
|
||||||
|
*
|
||||||
|
* Data lists are used for associating arbitrary data with #GObjects,
|
||||||
|
* using g_object_set_data() and related functions.
|
||||||
|
*
|
||||||
|
* To create a datalist, use g_datalist_init().
|
||||||
|
*
|
||||||
|
* To add data elements to a datalist use g_datalist_id_set_data(),
|
||||||
|
* g_datalist_id_set_data_full(), g_datalist_set_data() and
|
||||||
|
* g_datalist_set_data_full().
|
||||||
|
*
|
||||||
|
* To get data elements from a datalist use g_datalist_id_get_data()
|
||||||
|
* and g_datalist_get_data().
|
||||||
|
*
|
||||||
|
* To iterate over all data elements in a datalist use
|
||||||
|
* g_datalist_foreach() (not thread-safe).
|
||||||
|
*
|
||||||
|
* To remove data elements from a datalist use
|
||||||
|
* g_datalist_id_remove_data() and g_datalist_remove_data().
|
||||||
|
*
|
||||||
|
* To remove all data elements from a datalist, use g_datalist_clear().
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* GData:
|
||||||
|
*
|
||||||
|
* The #GData 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.
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* GDestroyNotify:
|
||||||
|
* @data: the data element.
|
||||||
|
*
|
||||||
|
* Specifies the type of function which is called when a data element
|
||||||
|
* is destroyed. It is passed the pointer to the data element and
|
||||||
|
* should free any memory and resources allocated for it.
|
||||||
|
**/
|
||||||
|
|
||||||
/* --- defines --- */
|
/* --- defines --- */
|
||||||
#define G_QUARK_BLOCK_SIZE (512)
|
#define G_QUARK_BLOCK_SIZE (512)
|
||||||
@@ -125,6 +214,13 @@ g_datalist_clear_i (GData **datalist)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_clear:
|
||||||
|
* @datalist: a datalist.
|
||||||
|
*
|
||||||
|
* Frees all the data elements of the datalist. The data elements'
|
||||||
|
* destroy functions are called if they have been set.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_datalist_clear (GData **datalist)
|
g_datalist_clear (GData **datalist)
|
||||||
{
|
{
|
||||||
@@ -178,6 +274,13 @@ g_dataset_destroy_internal (GDataset *dataset)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_dataset_destroy:
|
||||||
|
* @dataset_location: the location identifying the dataset.
|
||||||
|
*
|
||||||
|
* Destroys the dataset, freeing all memory allocated, and calling any
|
||||||
|
* destroy functions set for data elements.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_dataset_destroy (gconstpointer dataset_location)
|
g_dataset_destroy (gconstpointer dataset_location)
|
||||||
{
|
{
|
||||||
@@ -300,6 +403,67 @@ g_data_set_internal (GData **datalist,
|
|||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_dataset_id_set_data_full:
|
||||||
|
* @dataset_location: the location identifying the dataset.
|
||||||
|
* @key_id: the #GQuark id to identify the data element.
|
||||||
|
* @data: the data element.
|
||||||
|
* @destroy_func: 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.
|
||||||
|
*
|
||||||
|
* Sets the data element associated with the given #GQuark id, and also
|
||||||
|
* the function to call when the data element is destroyed. Any
|
||||||
|
* previous data with the same key is removed, and its destroy function
|
||||||
|
* is called.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_set_data_full:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the string to identify the data element.
|
||||||
|
* @d: the data element.
|
||||||
|
* @f: 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.
|
||||||
|
*
|
||||||
|
* Sets the data corresponding to the given string identifier, and the
|
||||||
|
* function to call when the data element is destroyed.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_id_set_data:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the #GQuark id to identify the data element.
|
||||||
|
* @d: the data element.
|
||||||
|
*
|
||||||
|
* Sets the data element associated with the given #GQuark id. Any
|
||||||
|
* previous data with the same key is removed, and its destroy function
|
||||||
|
* is called.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_set_data:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the string to identify the data element.
|
||||||
|
* @d: the data element.
|
||||||
|
*
|
||||||
|
* Sets the data corresponding to the given string identifier.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_id_remove_data:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the #GQuark id identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes a data element from a dataset. The data element's destroy
|
||||||
|
* function is called if it has been set.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_remove_data:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the string identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes a data element corresponding to a string. Its destroy
|
||||||
|
* function is called if it has been set.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_dataset_id_set_data_full (gconstpointer dataset_location,
|
g_dataset_id_set_data_full (gconstpointer dataset_location,
|
||||||
GQuark key_id,
|
GQuark key_id,
|
||||||
@@ -338,6 +502,72 @@ g_dataset_id_set_data_full (gconstpointer dataset_location,
|
|||||||
G_UNLOCK (g_dataset_global);
|
G_UNLOCK (g_dataset_global);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_id_set_data_full:
|
||||||
|
* @datalist: a datalist.
|
||||||
|
* @key_id: the #GQuark to identify the data element.
|
||||||
|
* @data: the data element or %NULL to remove any previous element
|
||||||
|
* corresponding to @key_id.
|
||||||
|
* @destroy_func: 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 @data is %NULL, then @destroy_func must
|
||||||
|
* also be %NULL.
|
||||||
|
*
|
||||||
|
* Sets the data corresponding to the given #GQuark 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.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_set_data_full:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @k: the string to identify the data element.
|
||||||
|
* @d: the data element, or %NULL to remove any previous element
|
||||||
|
* corresponding to @k.
|
||||||
|
* @f: 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 @d is %NULL, then @f must
|
||||||
|
* also be %NULL.
|
||||||
|
*
|
||||||
|
* Sets the data element corresponding to the given string identifier,
|
||||||
|
* and the function to be called when the data element is removed.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_id_set_data:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @q: the #GQuark to identify the data element.
|
||||||
|
* @d: the data element, or %NULL to remove any previous element
|
||||||
|
* corresponding to @q.
|
||||||
|
*
|
||||||
|
* Sets the data corresponding to the given #GQuark id. Any previous
|
||||||
|
* data with the same key is removed, and its destroy function is
|
||||||
|
* called.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_set_data:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @k: the string to identify the data element.
|
||||||
|
* @d: the data element, or %NULL to remove any previous element
|
||||||
|
* corresponding to @k.
|
||||||
|
*
|
||||||
|
* Sets the data element corresponding to the given string identifier.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_id_remove_data:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @q: the #GQuark identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes an element, using its #GQuark identifier.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_remove_data:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @k: the string identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes an element using its string identifier. The data element's
|
||||||
|
* destroy function is called if it has been set.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_datalist_id_set_data_full (GData **datalist,
|
g_datalist_id_set_data_full (GData **datalist,
|
||||||
GQuark key_id,
|
GQuark key_id,
|
||||||
@@ -363,6 +593,22 @@ g_datalist_id_set_data_full (GData **datalist,
|
|||||||
G_UNLOCK (g_dataset_global);
|
G_UNLOCK (g_dataset_global);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_dataset_id_remove_no_notify:
|
||||||
|
* @dataset_location: the location identifying the dataset.
|
||||||
|
* @key_id: the #GQuark ID identifying the data element.
|
||||||
|
* @Returns: the data previously stored at @key_id, or %NULL if none.
|
||||||
|
*
|
||||||
|
* Removes an element, without calling its destroy notification
|
||||||
|
* function.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_remove_no_notify:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the string identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes an element, without calling its destroy notifier.
|
||||||
|
**/
|
||||||
gpointer
|
gpointer
|
||||||
g_dataset_id_remove_no_notify (gconstpointer dataset_location,
|
g_dataset_id_remove_no_notify (gconstpointer dataset_location,
|
||||||
GQuark key_id)
|
GQuark key_id)
|
||||||
@@ -385,6 +631,22 @@ g_dataset_id_remove_no_notify (gconstpointer dataset_location,
|
|||||||
return ret_data;
|
return ret_data;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_id_remove_no_notify:
|
||||||
|
* @datalist: a datalist.
|
||||||
|
* @key_id: the #GQuark identifying a data element.
|
||||||
|
* @Returns: the data previously stored at @key_id, or %NULL if none.
|
||||||
|
*
|
||||||
|
* Removes an element, without calling its destroy notification
|
||||||
|
* function.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_remove_no_notify:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @k: the string identifying the data element.
|
||||||
|
*
|
||||||
|
* Removes an element, without calling its destroy notifier.
|
||||||
|
**/
|
||||||
gpointer
|
gpointer
|
||||||
g_datalist_id_remove_no_notify (GData **datalist,
|
g_datalist_id_remove_no_notify (GData **datalist,
|
||||||
GQuark key_id)
|
GQuark key_id)
|
||||||
@@ -401,6 +663,24 @@ g_datalist_id_remove_no_notify (GData **datalist,
|
|||||||
return ret_data;
|
return ret_data;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_dataset_id_get_data:
|
||||||
|
* @dataset_location: the location identifying the dataset.
|
||||||
|
* @key_id: the #GQuark id to identify the data element.
|
||||||
|
* @Returns: the data element corresponding to the #GQuark, or %NULL if
|
||||||
|
* it is not found.
|
||||||
|
*
|
||||||
|
* Gets the data element corresponding to a #GQuark.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_dataset_get_data:
|
||||||
|
* @l: the location identifying the dataset.
|
||||||
|
* @k: the string identifying the data element.
|
||||||
|
* @Returns: the data element corresponding to the string, or %NULL if
|
||||||
|
* it is not found.
|
||||||
|
*
|
||||||
|
* Gets the data element corresponding to a string.
|
||||||
|
**/
|
||||||
gpointer
|
gpointer
|
||||||
g_dataset_id_get_data (gconstpointer dataset_location,
|
g_dataset_id_get_data (gconstpointer dataset_location,
|
||||||
GQuark key_id)
|
GQuark key_id)
|
||||||
@@ -430,6 +710,24 @@ g_dataset_id_get_data (gconstpointer dataset_location,
|
|||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_id_get_data:
|
||||||
|
* @datalist: a datalist.
|
||||||
|
* @key_id: the #GQuark identifying a data element.
|
||||||
|
* @Returns: the data element, or %NULL if it is not found.
|
||||||
|
*
|
||||||
|
* Retrieves the data element corresponding to @key_id.
|
||||||
|
**/
|
||||||
|
/**
|
||||||
|
* g_datalist_get_data:
|
||||||
|
* @dl: a datalist.
|
||||||
|
* @k: the string identifying a data element.
|
||||||
|
* @Returns: the data element, or %NULL if it is not found.
|
||||||
|
*
|
||||||
|
* Gets a data element, using its string identifer. This is slower than
|
||||||
|
* g_datalist_id_get_data() because the string is first converted to a
|
||||||
|
* #GQuark.
|
||||||
|
**/
|
||||||
gpointer
|
gpointer
|
||||||
g_datalist_id_get_data (GData **datalist,
|
g_datalist_id_get_data (GData **datalist,
|
||||||
GQuark key_id)
|
GQuark key_id)
|
||||||
@@ -451,6 +749,28 @@ g_datalist_id_get_data (GData **datalist,
|
|||||||
return data;
|
return data;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* GDataForeachFunc:
|
||||||
|
* @key_id: the #GQuark id to identifying the data element.
|
||||||
|
* @data: the data element.
|
||||||
|
* @user_data: user data passed to g_dataset_foreach().
|
||||||
|
*
|
||||||
|
* Specifies the type of function passed to g_dataset_foreach(). It is
|
||||||
|
* called with each #GQuark id and associated data element, together
|
||||||
|
* with the @user_data parameter supplied to g_dataset_foreach().
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_dataset_foreach:
|
||||||
|
* @dataset_location: the location identifying the dataset.
|
||||||
|
* @func: the function to call for each data element.
|
||||||
|
* @user_data: user data to pass to the function.
|
||||||
|
*
|
||||||
|
* Calls the given function for each data element which is associated
|
||||||
|
* with the given location. Note that this function is NOT thread-safe.
|
||||||
|
* So unless @datalist can be protected from any modifications during
|
||||||
|
* invocation of this function, it should not be called.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_dataset_foreach (gconstpointer dataset_location,
|
g_dataset_foreach (gconstpointer dataset_location,
|
||||||
GDataForeachFunc func,
|
GDataForeachFunc func,
|
||||||
@@ -483,6 +803,19 @@ g_dataset_foreach (gconstpointer dataset_location,
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_foreach:
|
||||||
|
* @datalist: a datalist.
|
||||||
|
* @func: the function to call for each data element.
|
||||||
|
* @user_data: user data to pass to the function.
|
||||||
|
*
|
||||||
|
* Calls the given function for each data element of the datalist. The
|
||||||
|
* function is called with each data element's #GQuark id and data,
|
||||||
|
* together with the given @user_data parameter. Note that this
|
||||||
|
* function is NOT thread-safe. So unless @datalist can be protected
|
||||||
|
* from any modifications during invocation of this function, it should
|
||||||
|
* not be called.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_datalist_foreach (GData **datalist,
|
g_datalist_foreach (GData **datalist,
|
||||||
GDataForeachFunc func,
|
GDataForeachFunc func,
|
||||||
@@ -500,6 +833,13 @@ g_datalist_foreach (GData **datalist,
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_datalist_init:
|
||||||
|
* @datalist: a pointer to a pointer to a datalist.
|
||||||
|
*
|
||||||
|
* Resets the datalist to %NULL. It does not free any memory or call
|
||||||
|
* any destroy functions.
|
||||||
|
**/
|
||||||
void
|
void
|
||||||
g_datalist_init (GData **datalist)
|
g_datalist_init (GData **datalist)
|
||||||
{
|
{
|
||||||
@@ -600,6 +940,56 @@ g_data_initialize (void)
|
|||||||
g_dataset_cached = NULL;
|
g_dataset_cached = NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SECTION: quarks
|
||||||
|
* @title: Quarks
|
||||||
|
* @short_description: a 2-way association between a string and a
|
||||||
|
* unique integer identifier
|
||||||
|
*
|
||||||
|
* Quarks are associations between strings and integer identifiers.
|
||||||
|
* Given either the string or the #GQuark identifier it is possible to
|
||||||
|
* retrieve the other.
|
||||||
|
*
|
||||||
|
* Quarks are used for both <link
|
||||||
|
* linkend="glib-datasets">Datasets</link> and <link
|
||||||
|
* linkend="glib-keyed-data-lists">Keyed Data Lists</link>.
|
||||||
|
*
|
||||||
|
* To create a new quark from a string, use g_quark_from_string() or
|
||||||
|
* g_quark_from_static_string().
|
||||||
|
*
|
||||||
|
* To find the string corresponding to a given #GQuark, use
|
||||||
|
* g_quark_to_string().
|
||||||
|
*
|
||||||
|
* To find the #GQuark corresponding to a given string, use
|
||||||
|
* g_quark_try_string().
|
||||||
|
*
|
||||||
|
* Another use for the string pool maintained for the quark functions
|
||||||
|
* is string interning, using g_intern_string() or
|
||||||
|
* g_intern_static_string(). An interned string is a canonical
|
||||||
|
* representation for a string. One important advantage of interned
|
||||||
|
* strings is that they can be compared for equality by a simple
|
||||||
|
* pointer comparision, rather than using strcmp().
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* GQuark:
|
||||||
|
*
|
||||||
|
* A GQuark is a non-zero integer which uniquely identifies a
|
||||||
|
* particular string. A GQuark value of zero is associated to %NULL.
|
||||||
|
**/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_quark_try_string:
|
||||||
|
* @string: a string.
|
||||||
|
* @Returns: the #GQuark associated with the string, or 0 if @string is
|
||||||
|
* %NULL or there is no #GQuark associated with it.
|
||||||
|
*
|
||||||
|
* Gets the #GQuark associated with the given string, or 0 if string is
|
||||||
|
* %NULL or it has no associated #GQuark.
|
||||||
|
*
|
||||||
|
* If you want the GQuark to be created if it doesn't already exist,
|
||||||
|
* use g_quark_from_string() or g_quark_from_static_string().
|
||||||
|
**/
|
||||||
GQuark
|
GQuark
|
||||||
g_quark_try_string (const gchar *string)
|
g_quark_try_string (const gchar *string)
|
||||||
{
|
{
|
||||||
@@ -630,6 +1020,16 @@ g_quark_from_string_internal (const gchar *string,
|
|||||||
return quark;
|
return quark;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_quark_from_string:
|
||||||
|
* @string: a string.
|
||||||
|
* @Returns: the #GQuark identifying the string, or 0 if @string is
|
||||||
|
* %NULL.
|
||||||
|
*
|
||||||
|
* Gets the #GQuark identifying the given string. If the string does
|
||||||
|
* not currently have an associated #GQuark, a new #GQuark is created,
|
||||||
|
* using a copy of the string.
|
||||||
|
**/
|
||||||
GQuark
|
GQuark
|
||||||
g_quark_from_string (const gchar *string)
|
g_quark_from_string (const gchar *string)
|
||||||
{
|
{
|
||||||
@@ -645,6 +1045,25 @@ g_quark_from_string (const gchar *string)
|
|||||||
return quark;
|
return quark;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_quark_from_static_string:
|
||||||
|
* @string: a string.
|
||||||
|
* @Returns: the #GQuark identifying the string, or 0 if @string is
|
||||||
|
* %NULL.
|
||||||
|
*
|
||||||
|
* Gets the #GQuark identifying the given (static) string. If the
|
||||||
|
* string does not currently have an associated #GQuark, a new #GQuark
|
||||||
|
* is created, linked to the given string.
|
||||||
|
*
|
||||||
|
* Note that this function is identical to g_quark_from_string() except
|
||||||
|
* that if a new #GQuark is created the string itself is used rather
|
||||||
|
* than a copy. This saves memory, but can only be used if the string
|
||||||
|
* will <emphasis>always</emphasis> exist. It can be used with
|
||||||
|
* statically allocated strings in the main program, but not with
|
||||||
|
* statically allocated memory in dynamically loaded modules, if you
|
||||||
|
* expect to ever unload the module again (e.g. do not use this
|
||||||
|
* function in GTK+ theme engines).
|
||||||
|
**/
|
||||||
GQuark
|
GQuark
|
||||||
g_quark_from_static_string (const gchar *string)
|
g_quark_from_static_string (const gchar *string)
|
||||||
{
|
{
|
||||||
@@ -660,6 +1079,13 @@ g_quark_from_static_string (const gchar *string)
|
|||||||
return quark;
|
return quark;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* g_quark_to_string:
|
||||||
|
* @quark: a #GQuark.
|
||||||
|
* @Returns: the string associated with the #GQuark.
|
||||||
|
*
|
||||||
|
* Gets the string associated with the given #GQuark.
|
||||||
|
**/
|
||||||
G_CONST_RETURN gchar*
|
G_CONST_RETURN gchar*
|
||||||
g_quark_to_string (GQuark quark)
|
g_quark_to_string (GQuark quark)
|
||||||
{
|
{
|
||||||
@@ -753,7 +1179,5 @@ g_intern_static_string (const gchar *string)
|
|||||||
return result;
|
return result;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#define __G_DATASET_C__
|
#define __G_DATASET_C__
|
||||||
#include "galiasdef.c"
|
#include "galiasdef.c"
|
||||||
|
Reference in New Issue
Block a user