mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-10-01 19:36:37 +02:00
a5c0df554e
Thu Sep 7 12:35:35 2000 Owen Taylor <otaylor@redhat.com> * Some further makefile improvement. * Restore all the docs that mysteriously vanished earlier.
111 lines
3.4 KiB
Plaintext
111 lines
3.4 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
String Chunks
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
efficient storage of groups of strings.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
String chunks are used to store groups of strings.
|
|
Memory is allocated in blocks, and as strings are added to the #GStringChunk
|
|
they are copied into the next free position in a block. When a block is
|
|
full a new block is allocated.
|
|
</para>
|
|
<para>
|
|
When storing a large number of strings, string chunks are more efficient
|
|
than using g_strdup() since fewer calls to <function>malloc()</function>
|
|
are needed, and less memory is wasted in memory allocation overheads.
|
|
</para>
|
|
<para>
|
|
By adding strings with g_string_chunk_insert_const() it is also possible
|
|
to remove duplicates.
|
|
</para>
|
|
<para>
|
|
To create a new #GStringChunk use g_string_chunk_new().
|
|
</para>
|
|
<para>
|
|
To add strings to a #GStringChunk use g_string_chunk_insert().
|
|
</para>
|
|
<para>
|
|
To add strings to a #GStringChunk, but without duplicating strings which are
|
|
already in the #GStringChunk, use g_string_chunk_insert_const().
|
|
</para>
|
|
<para>
|
|
To free the entire #GStringChunk use g_string_chunk_free().
|
|
It is not possible to free individual strings.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GStringChunk ##### -->
|
|
<para>
|
|
An opaque data structure representing String Chunks.
|
|
It should only be accessed by using the following functions.
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION g_string_chunk_new ##### -->
|
|
<para>
|
|
Creates a new #GStringChunk.
|
|
</para>
|
|
|
|
@size: the default size of the blocks of memory which are allocated to store
|
|
the strings. If a particular string is larger than this default size, a larger
|
|
block of memory will be allocated for it.
|
|
@Returns: a new #GStringChunk.
|
|
|
|
|
|
<!-- ##### FUNCTION g_string_chunk_insert ##### -->
|
|
<para>
|
|
Adds a copy of @string to the #GStringChunk.
|
|
It returns a pointer to the new copy of the string in the #GStringChunk.
|
|
The characters in the string can be changed, if necessary, though you
|
|
should not change anything after the end of the string.
|
|
</para>
|
|
<para>
|
|
Unlike g_string_chunk_insert_const(), this function does not check for
|
|
duplicates. Also strings added with g_string_chunk_insert() will not be
|
|
searched by g_string_chunk_insert_const() when looking for duplicates.
|
|
</para>
|
|
|
|
@chunk: a #GStringChunk.
|
|
@string: the string to add.
|
|
@Returns: a pointer to the copy of @string within the #GStringChunk.
|
|
|
|
|
|
<!-- ##### FUNCTION g_string_chunk_insert_const ##### -->
|
|
<para>
|
|
Adds a copy of @string to the #GStringChunk, unless the same string has
|
|
already been added to the #GStringChunk with g_string_chunk_insert_const().
|
|
</para>
|
|
<para>
|
|
This function is useful if you need to copy a large number of strings
|
|
but do not want to waste space storing duplicates. But you must remember
|
|
that there may be several pointers to the same string, and so any changes
|
|
made to the strings should be done very carefully.
|
|
</para>
|
|
<para>
|
|
Note that g_string_chunk_insert_const() will not return a pointer to a string
|
|
added with g_string_chunk_insert(), even if they do match.
|
|
</para>
|
|
|
|
@chunk: a #GStringChunk.
|
|
@string: the string to add.
|
|
@Returns: a pointer to the new or existing copy of @string within the
|
|
#GStringChunk.
|
|
|
|
|
|
<!-- ##### FUNCTION g_string_chunk_free ##### -->
|
|
<para>
|
|
Frees all memory allocated by the #GStringChunk.
|
|
After calling g_string_chunk_free() it is not safe to
|
|
access any of the strings which were contained within it.
|
|
</para>
|
|
|
|
@chunk: a #GStringChunk.
|
|
|
|
|