docs/reference/glib/html/glib-String-Chunks.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>String Chunks: GLib Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-data-types.html" title="GLib Data Types">
   9 <link rel="prev" href="glib-Strings.html" title="Strings">
  10 <link rel="next" href="glib-Arrays.html" title="Arrays">
  11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts">
  17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span>
  18                   <a href="#glib-String-Chunks.description" class="shortcut">Description</a></span>
  19 </td>
  20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  21 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="glib-Strings.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="glib-Arrays.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  24 </tr></table>
  25 <div class="refentry">
  26 <a name="glib-String-Chunks"></a><div class="titlepage"></div>
  27 <div class="refnamediv"><table width="100%"><tr>
  28 <td valign="top">
  29 <h2><span class="refentrytitle"><a name="glib-String-Chunks.top_of_page"></a>String Chunks</span></h2>
  30 <p>String Chunks — efficient storage of groups of strings</p>
  31 </td>
  32 <td class="gallery_image" valign="top" align="right"></td>
  33 </tr></table></div>
  34 <div class="refsect1">
  35 <a name="glib-String-Chunks.functions"></a><h2>Functions</h2>
  36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  37 <colgroup>
  38 <col width="150px" class="functions_return">
  39 <col class="functions_name">
  40 </colgroup>
  41 <tbody>
  42 <tr>
  43 <td class="function_type">
  44 <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="returnvalue">GStringChunk</span></a> *
  45 </td>
  46 <td class="function_name">
  47 <a class="link" href="glib-String-Chunks.html#g-string-chunk-new" title="g_string_chunk_new ()">g_string_chunk_new</a> <span class="c_punctuation">()</span>
  48 </td>
  49 </tr>
  50 <tr>
  51 <td class="function_type">
  52 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
  53 </td>
  54 <td class="function_name">
  55 <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert" title="g_string_chunk_insert ()">g_string_chunk_insert</a> <span class="c_punctuation">()</span>
  56 </td>
  57 </tr>
  58 <tr>
  59 <td class="function_type">
  60 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
  61 </td>
  62 <td class="function_name">
  63 <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()">g_string_chunk_insert_const</a> <span class="c_punctuation">()</span>
  64 </td>
  65 </tr>
  66 <tr>
  67 <td class="function_type">
  68 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
  69 </td>
  70 <td class="function_name">
  71 <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-len" title="g_string_chunk_insert_len ()">g_string_chunk_insert_len</a> <span class="c_punctuation">()</span>
  72 </td>
  73 </tr>
  74 <tr>
  75 <td class="function_type">
  76 <span class="returnvalue">void</span>
  77 </td>
  78 <td class="function_name">
  79 <a class="link" href="glib-String-Chunks.html#g-string-chunk-clear" title="g_string_chunk_clear ()">g_string_chunk_clear</a> <span class="c_punctuation">()</span>
  80 </td>
  81 </tr>
  82 <tr>
  83 <td class="function_type">
  84 <span class="returnvalue">void</span>
  85 </td>
  86 <td class="function_name">
  87 <a class="link" href="glib-String-Chunks.html#g-string-chunk-free" title="g_string_chunk_free ()">g_string_chunk_free</a> <span class="c_punctuation">()</span>
  88 </td>
  89 </tr>
  90 </tbody>
  91 </table></div>
  92 </div>
  93 <div class="refsect1">
  94 <a name="glib-String-Chunks.other"></a><h2>Types and Values</h2>
  95 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  96 <colgroup>
  97 <col width="150px" class="name">
  98 <col class="description">
  99 </colgroup>
 100 <tbody><tr>
 101 <td class="datatype_keyword"> </td>
 102 <td class="function_name"><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk">GStringChunk</a></td>
 103 </tr></tbody>
 104 </table></div>
 105 </div>
 106 <div class="refsect1">
 107 <a name="glib-String-Chunks.includes"></a><h2>Includes</h2>
 108 <pre class="synopsis">#include &lt;glib.h&gt;
 109 </pre>
 110 </div>
 111 <div class="refsect1">
 112 <a name="glib-String-Chunks.description"></a><h2>Description</h2>
 113 <p>String chunks are used to store groups of strings. Memory is
 114 allocated in blocks, and as strings are added to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 115 they are copied into the next free position in a block. When a block
 116 is full a new block is allocated.</p>
 117 <p>When storing a large number of strings, string chunks are more
 118 efficient than using <a class="link" href="glib-String-Utility-Functions.html#g-strdup" title="g_strdup ()"><code class="function">g_strdup()</code></a> since fewer calls to <code class="function">malloc()</code> are
 119 needed, and less memory is wasted in memory allocation overheads.</p>
 120 <p>By adding strings with <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a> it is also
 121 possible to remove duplicates.</p>
 122 <p>To create a new <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> use <a class="link" href="glib-String-Chunks.html#g-string-chunk-new" title="g_string_chunk_new ()"><code class="function">g_string_chunk_new()</code></a>.</p>
 123 <p>To add strings to a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> use <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert" title="g_string_chunk_insert ()"><code class="function">g_string_chunk_insert()</code></a>.</p>
 124 <p>To add strings to a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>, but without duplicating strings
 125 which are already in the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>, use
 126 <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a>.</p>
 127 <p>To free the entire <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> use <a class="link" href="glib-String-Chunks.html#g-string-chunk-free" title="g_string_chunk_free ()"><code class="function">g_string_chunk_free()</code></a>. It is
 128 not possible to free individual strings.</p>
 129 </div>
 130 <div class="refsect1">
 131 <a name="glib-String-Chunks.functions_details"></a><h2>Functions</h2>
 132 <div class="refsect2">
 133 <a name="g-string-chunk-new"></a><h3>g_string_chunk_new ()</h3>
 134 <pre class="programlisting"><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="returnvalue">GStringChunk</span></a> *
 135 g_string_chunk_new (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> size</code></em>);</pre>
 136 <p>Creates a new <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.</p>
 137 <div class="refsect3">
 138 <a name="g-string-chunk-new.parameters"></a><h4>Parameters</h4>
 139 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 140 <colgroup>
 141 <col width="150px" class="parameters_name">
 142 <col class="parameters_description">
 143 <col width="200px" class="parameters_annotations">
 144 </colgroup>
 145 <tbody><tr>
 146 <td class="parameter_name"><p>size</p></td>
 147 <td class="parameter_description"><p>the default size of the blocks of memory which are
 148 allocated to store the strings. If a particular string
 149 is larger than this default size, a larger block of
 150 memory will be allocated for it.</p></td>
 151 <td class="parameter_annotations"> </td>
 152 </tr></tbody>
 153 </table></div>
 154 </div>
 155 <div class="refsect3">
 156 <a name="g-string-chunk-new.returns"></a><h4>Returns</h4>
 157 <p> a new <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p>
 158 </div>
 159 </div>
 160 <hr>
 161 <div class="refsect2">
 162 <a name="g-string-chunk-insert"></a><h3>g_string_chunk_insert ()</h3>
 163 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
 164 g_string_chunk_insert (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
 165                        <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
 166 <p>Adds a copy of <em class="parameter"><code>string</code></em>
 167  to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 168 It returns a pointer to the new copy of the string
 169 in the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>. The characters in the string
 170 can be changed, if necessary, though you should not
 171 change anything after the end of the string.</p>
 172 <p>Unlike <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a>, this function
 173 does not check for duplicates. Also strings added
 174 with <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert" title="g_string_chunk_insert ()"><code class="function">g_string_chunk_insert()</code></a> will not be searched
 175 by <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a> when looking for
 176 duplicates.</p>
 177 <div class="refsect3">
 178 <a name="g-string-chunk-insert.parameters"></a><h4>Parameters</h4>
 179 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 180 <colgroup>
 181 <col width="150px" class="parameters_name">
 182 <col class="parameters_description">
 183 <col width="200px" class="parameters_annotations">
 184 </colgroup>
 185 <tbody>
 186 <tr>
 187 <td class="parameter_name"><p>chunk</p></td>
 188 <td class="parameter_description"><p>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p></td>
 189 <td class="parameter_annotations"> </td>
 190 </tr>
 191 <tr>
 192 <td class="parameter_name"><p>string</p></td>
 193 <td class="parameter_description"><p>the string to add</p></td>
 194 <td class="parameter_annotations"> </td>
 195 </tr>
 196 </tbody>
 197 </table></div>
 198 </div>
 199 <div class="refsect3">
 200 <a name="g-string-chunk-insert.returns"></a><h4>Returns</h4>
 201 <p> a pointer to the copy of <em class="parameter"><code>string</code></em>
 202 within
 203 the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p>
 204 </div>
 205 </div>
 206 <hr>
 207 <div class="refsect2">
 208 <a name="g-string-chunk-insert-const"></a><h3>g_string_chunk_insert_const ()</h3>
 209 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
 210 g_string_chunk_insert_const (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
 211                              <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
 212 <p>Adds a copy of <em class="parameter"><code>string</code></em>
 213  to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>, unless the same
 214 string has already been added to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> with
 215 <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a>.</p>
 216 <p>This function is useful if you need to copy a large number
 217 of strings but do not want to waste space storing duplicates.
 218 But you must remember that there may be several pointers to
 219 the same string, and so any changes made to the strings
 220 should be done very carefully.</p>
 221 <p>Note that <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert-const" title="g_string_chunk_insert_const ()"><code class="function">g_string_chunk_insert_const()</code></a> will not return a
 222 pointer to a string added with <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert" title="g_string_chunk_insert ()"><code class="function">g_string_chunk_insert()</code></a>, even
 223 if they do match.</p>
 224 <div class="refsect3">
 225 <a name="g-string-chunk-insert-const.parameters"></a><h4>Parameters</h4>
 226 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 227 <colgroup>
 228 <col width="150px" class="parameters_name">
 229 <col class="parameters_description">
 230 <col width="200px" class="parameters_annotations">
 231 </colgroup>
 232 <tbody>
 233 <tr>
 234 <td class="parameter_name"><p>chunk</p></td>
 235 <td class="parameter_description"><p>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p></td>
 236 <td class="parameter_annotations"> </td>
 237 </tr>
 238 <tr>
 239 <td class="parameter_name"><p>string</p></td>
 240 <td class="parameter_description"><p>the string to add</p></td>
 241 <td class="parameter_annotations"> </td>
 242 </tr>
 243 </tbody>
 244 </table></div>
 245 </div>
 246 <div class="refsect3">
 247 <a name="g-string-chunk-insert-const.returns"></a><h4>Returns</h4>
 248 <p> a pointer to the new or existing copy of <em class="parameter"><code>string</code></em>
 249 within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p>
 250 </div>
 251 </div>
 252 <hr>
 253 <div class="refsect2">
 254 <a name="g-string-chunk-insert-len"></a><h3>g_string_chunk_insert_len ()</h3>
 255 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *
 256 g_string_chunk_insert_len (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
 257                            <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 258                            <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);</pre>
 259 <p>Adds a copy of the first <em class="parameter"><code>len</code></em>
 260  bytes of <em class="parameter"><code>string</code></em>
 261  to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 262 The copy is nul-terminated.</p>
 263 <p>Since this function does not stop at nul bytes, it is the caller's
 264 responsibility to ensure that <em class="parameter"><code>string</code></em>
 265  has at least <em class="parameter"><code>len</code></em>
 266  addressable
 267 bytes.</p>
 268 <p>The characters in the returned string can be changed, if necessary,
 269 though you should not change anything after the end of the string.</p>
 270 <div class="refsect3">
 271 <a name="g-string-chunk-insert-len.parameters"></a><h4>Parameters</h4>
 272 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 273 <colgroup>
 274 <col width="150px" class="parameters_name">
 275 <col class="parameters_description">
 276 <col width="200px" class="parameters_annotations">
 277 </colgroup>
 278 <tbody>
 279 <tr>
 280 <td class="parameter_name"><p>chunk</p></td>
 281 <td class="parameter_description"><p>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p></td>
 282 <td class="parameter_annotations"> </td>
 283 </tr>
 284 <tr>
 285 <td class="parameter_name"><p>string</p></td>
 286 <td class="parameter_description"><p>bytes to insert</p></td>
 287 <td class="parameter_annotations"> </td>
 288 </tr>
 289 <tr>
 290 <td class="parameter_name"><p>len</p></td>
 291 <td class="parameter_description"><p>number of bytes of <em class="parameter"><code>string</code></em>
 292 to insert, or -1 to insert a
 293 nul-terminated string</p></td>
 294 <td class="parameter_annotations"> </td>
 295 </tr>
 296 </tbody>
 297 </table></div>
 298 </div>
 299 <div class="refsect3">
 300 <a name="g-string-chunk-insert-len.returns"></a><h4>Returns</h4>
 301 <p> a pointer to the copy of <em class="parameter"><code>string</code></em>
 302 within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p>
 303 </div>
 304 <p class="since">Since: <a class="link" href="api-index-2-4.html#api-index-2.4">2.4</a></p>
 305 </div>
 306 <hr>
 307 <div class="refsect2">
 308 <a name="g-string-chunk-clear"></a><h3>g_string_chunk_clear ()</h3>
 309 <pre class="programlisting"><span class="returnvalue">void</span>
 310 g_string_chunk_clear (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>);</pre>
 311 <p>Frees all strings contained within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 312 After calling <a class="link" href="glib-String-Chunks.html#g-string-chunk-clear" title="g_string_chunk_clear ()"><code class="function">g_string_chunk_clear()</code></a> it is not safe to
 313 access any of the strings which were contained within it.</p>
 314 <div class="refsect3">
 315 <a name="g-string-chunk-clear.parameters"></a><h4>Parameters</h4>
 316 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 317 <colgroup>
 318 <col width="150px" class="parameters_name">
 319 <col class="parameters_description">
 320 <col width="200px" class="parameters_annotations">
 321 </colgroup>
 322 <tbody><tr>
 323 <td class="parameter_name"><p>chunk</p></td>
 324 <td class="parameter_description"><p>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p></td>
 325 <td class="parameter_annotations"> </td>
 326 </tr></tbody>
 327 </table></div>
 328 </div>
 329 <p class="since">Since: <a class="link" href="api-index-2-14.html#api-index-2.14">2.14</a></p>
 330 </div>
 331 <hr>
 332 <div class="refsect2">
 333 <a name="g-string-chunk-free"></a><h3>g_string_chunk_free ()</h3>
 334 <pre class="programlisting"><span class="returnvalue">void</span>
 335 g_string_chunk_free (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>);</pre>
 336 <p>Frees all memory allocated by the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 337 After calling <a class="link" href="glib-String-Chunks.html#g-string-chunk-free" title="g_string_chunk_free ()"><code class="function">g_string_chunk_free()</code></a> it is not safe to
 338 access any of the strings which were contained within it.</p>
 339 <div class="refsect3">
 340 <a name="g-string-chunk-free.parameters"></a><h4>Parameters</h4>
 341 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 342 <colgroup>
 343 <col width="150px" class="parameters_name">
 344 <col class="parameters_description">
 345 <col width="200px" class="parameters_annotations">
 346 </colgroup>
 347 <tbody><tr>
 348 <td class="parameter_name"><p>chunk</p></td>
 349 <td class="parameter_description"><p>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a></p></td>
 350 <td class="parameter_annotations"> </td>
 351 </tr></tbody>
 352 </table></div>
 353 </div>
 354 </div>
 355 </div>
 356 <div class="refsect1">
 357 <a name="glib-String-Chunks.other_details"></a><h2>Types and Values</h2>
 358 <div class="refsect2">
 359 <a name="GStringChunk"></a><h3>GStringChunk</h3>
 360 <pre class="programlisting">typedef struct _GStringChunk GStringChunk;</pre>
 361 <p>An opaque data structure representing String Chunks.
 362 It should only be accessed by using the following functions.</p>
 363 </div>
 364 </div>
 365 </div>
 366 <div class="footer">
 367 <hr>Generated by GTK-Doc V1.25.1</div>
 368 </body>
 369 </html>