docs/reference/glib/tmpl/string_chunks.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 String Chunks
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 efficient storage of groups of strings.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 String chunks are used to store groups of strings.
  10 Memory is allocated in blocks, and as strings are added to the #GStringChunk
  11 they are copied into the next free position in a block. When a block is
  12 full a new block is allocated.
  13 </para>
  14 <para>
  15 When storing a large number of strings, string chunks are more efficient
  16 than using g_strdup() since fewer calls to <function>malloc()</function>
  17 are needed, and less memory is wasted in memory allocation overheads.
  18 </para>
  19 <para>
  20 By adding strings with g_string_chunk_insert_const() it is also possible
  21 to remove duplicates.
  22 </para>
  23 <para>
  24 To create a new #GStringChunk use g_string_chunk_new().
  25 </para>
  26 <para>
  27 To add strings to a #GStringChunk use g_string_chunk_insert().
  28 </para>
  29 <para>
  30 To add strings to a #GStringChunk, but without duplicating strings which are
  31 already in the #GStringChunk, use g_string_chunk_insert_const().
  32 </para>
  33 <para>
  34 To free the entire #GStringChunk use g_string_chunk_free().
  35 It is not possible to free individual strings.
  36 </para>
  37
  38 <!-- ##### SECTION See_Also ##### -->
  39 <para>
  40
  41 </para>
  42
  43 <!-- ##### SECTION Stability_Level ##### -->
  44
  45
  46 <!-- ##### STRUCT GStringChunk ##### -->
  47 <para>
  48 An opaque data structure representing String Chunks.
  49 It should only be accessed by using the following functions.
  50 </para>
  51
  52
  53 <!-- ##### FUNCTION g_string_chunk_new ##### -->
  54 <para>
  55 Creates a new #GStringChunk.
  56 </para>
  57
  58 @size: the default size of the blocks of memory which are allocated to store
  59 the strings. If a particular string is larger than this default size, a larger
  60 block of memory will be allocated for it.
  61 @Returns: a new #GStringChunk.
  62
  63
  64 <!-- ##### FUNCTION g_string_chunk_insert ##### -->
  65 <para>
  66 Adds a copy of @string to the #GStringChunk.
  67 It returns a pointer to the new copy of the string in the #GStringChunk.
  68 The characters in the string can be changed, if necessary, though you
  69 should not change anything after the end of the string.
  70 </para>
  71 <para>
  72 Unlike g_string_chunk_insert_const(), this function does not check for
  73 duplicates. Also strings added with g_string_chunk_insert() will not be
  74 searched by g_string_chunk_insert_const() when looking for duplicates.
  75 </para>
  76
  77 @chunk: a #GStringChunk.
  78 @string: the string to add.
  79 @Returns: a pointer to the copy of @string within the #GStringChunk.
  80
  81
  82 <!-- ##### FUNCTION g_string_chunk_insert_const ##### -->
  83 <para>
  84 Adds a copy of @string to the #GStringChunk, unless the same string has
  85 already been added to the #GStringChunk with g_string_chunk_insert_const().
  86 </para>
  87 <para>
  88 This function is useful if you need to copy a large number of strings
  89 but do not want to waste space storing duplicates. But you must remember
  90 that there may be several pointers to the same string, and so any changes
  91 made to the strings should be done very carefully.
  92 </para>
  93 <para>
  94 Note that g_string_chunk_insert_const() will not return a pointer to a string
  95 added with g_string_chunk_insert(), even if they do match.
  96 </para>
  97
  98 @chunk: a #GStringChunk.
  99 @string: the string to add.
 100 @Returns: a pointer to the new or existing copy of @string within the
 101 #GStringChunk.
 102
 103
 104 <!-- ##### FUNCTION g_string_chunk_insert_len ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @chunk:
 110 @string:
 111 @len:
 112 @Returns:
 113
 114
 115 <!-- ##### FUNCTION g_string_chunk_free ##### -->
 116 <para>
 117 Frees all memory allocated by the #GStringChunk.
 118 After calling g_string_chunk_free() it is not safe to
 119 access any of the strings which were contained within it.
 120 </para>
 121
 122 @chunk: a #GStringChunk.
 123
 124