| <!-- ##### 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> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### 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_insert_len ##### --> |
| <para> |
| |
| </para> |
| |
| @chunk: |
| @string: |
| @len: |
| @Returns: |
| |
| |
| <!-- ##### 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. |
| |
| |