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</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   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.15 (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="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Strings.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Arrays.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-String-Chunks.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-String-Chunks.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry" title="String Chunks">
  30 <a name="glib-String-Chunks"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-String-Chunks.top_of_page"></a>String Chunks</span></h2>
  34 <p>String Chunks — efficient storage of groups of strings</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv" title="Synopsis">
  39 <a name="glib-String-Chunks.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43                     <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk">GStringChunk</a>;
  44 <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="returnvalue">GStringChunk</span></a>*       <a class="link" href="glib-String-Chunks.html#g-string-chunk-new" title="g_string_chunk_new ()">g_string_chunk_new</a>                  (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> size</code></em>);
  45 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              <a class="link" href="glib-String-Chunks.html#g-string-chunk-insert" title="g_string_chunk_insert ()">g_string_chunk_insert</a>               (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
  46                                                          <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>);
  47 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              <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>         (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
  48                                                          <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>);
  49 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              <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>           (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>,
  50                                                          <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>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);
  52 <span class="returnvalue">void</span>                <a class="link" href="glib-String-Chunks.html#g-string-chunk-clear" title="g_string_chunk_clear ()">g_string_chunk_clear</a>                (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>);
  53 <span class="returnvalue">void</span>                <a class="link" href="glib-String-Chunks.html#g-string-chunk-free" title="g_string_chunk_free ()">g_string_chunk_free</a>                 (<em class="parameter"><code><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a> *chunk</code></em>);
  54 </pre>
  55 </div>
  56 <div class="refsect1" title="Description">
  57 <a name="glib-String-Chunks.description"></a><h2>Description</h2>
  58 <p>
  59 String chunks are used to store groups of strings. Memory is
  60 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>
  61 they are copied into the next free position in a block. When a block
  62 is full a new block is allocated.
  63 </p>
  64 <p>
  65 When storing a large number of strings, string chunks are more
  66 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
  67 needed, and less memory is wasted in memory allocation overheads.
  68 </p>
  69 <p>
  70 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
  71 possible to remove duplicates.
  72 </p>
  73 <p>
  74 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>.
  75 </p>
  76 <p>
  77 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>.
  78 </p>
  79 <p>
  80 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
  81 which are already in the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>, use
  82 <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>.
  83 </p>
  84 <p>
  85 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
  86 not possible to free individual strings.
  87 </p>
  88 </div>
  89 <div class="refsect1" title="Details">
  90 <a name="glib-String-Chunks.details"></a><h2>Details</h2>
  91 <div class="refsect2" title="GStringChunk">
  92 <a name="GStringChunk"></a><h3>GStringChunk</h3>
  93 <pre class="programlisting">typedef struct _GStringChunk GStringChunk;</pre>
  94 <p>
  95 An opaque data structure representing String Chunks. It should only
  96 be accessed by using the following functions.
  97 </p>
  98 </div>
  99 <hr>
 100 <div class="refsect2" title="g_string_chunk_new ()">
 101 <a name="g-string-chunk-new"></a><h3>g_string_chunk_new ()</h3>
 102 <pre class="programlisting"><a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="returnvalue">GStringChunk</span></a>*       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>
 103 <p>
 104 Creates a new <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 105 </p>
 106 <div class="variablelist"><table border="0">
 107 <col align="left" valign="top">
 108 <tbody>
 109 <tr>
 110 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
 111 <td>the default size of the blocks of memory which are
 112        allocated to store the strings. If a particular string
 113        is larger than this default size, a larger block of
 114        memory will be allocated for it.
 115 </td>
 116 </tr>
 117 <tr>
 118 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 119 <td> a new <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 120 </td>
 121 </tr>
 122 </tbody>
 123 </table></div>
 124 </div>
 125 <hr>
 126 <div class="refsect2" title="g_string_chunk_insert ()">
 127 <a name="g-string-chunk-insert"></a><h3>g_string_chunk_insert ()</h3>
 128 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              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>,
 129                                                          <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>
 130 <p>
 131 Adds a copy of <em class="parameter"><code>string</code></em> to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 132 It returns a pointer to the new copy of the string
 133 in the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>. The characters in the string
 134 can be changed, if necessary, though you should not
 135 change anything after the end of the string.
 136 </p>
 137 <p>
 138 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
 139 does not check for duplicates. Also strings added
 140 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
 141 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
 142 duplicates.
 143 </p>
 144 <div class="variablelist"><table border="0">
 145 <col align="left" valign="top">
 146 <tbody>
 147 <tr>
 148 <td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>
 149 <td>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 150 </td>
 151 </tr>
 152 <tr>
 153 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 154 <td>the string to add
 155 </td>
 156 </tr>
 157 <tr>
 158 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 159 <td> a pointer to the copy of <em class="parameter"><code>string</code></em> within
 160          the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 161 </td>
 162 </tr>
 163 </tbody>
 164 </table></div>
 165 </div>
 166 <hr>
 167 <div class="refsect2" title="g_string_chunk_insert_const ()">
 168 <a name="g-string-chunk-insert-const"></a><h3>g_string_chunk_insert_const ()</h3>
 169 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              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>,
 170                                                          <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>
 171 <p>
 172 Adds a copy of <em class="parameter"><code>string</code></em> to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>, unless the same
 173 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
 174 <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>.
 175 </p>
 176 <p>
 177 This function is useful if you need to copy a large number
 178 of strings but do not want to waste space storing duplicates.
 179 But you must remember that there may be several pointers to
 180 the same string, and so any changes made to the strings
 181 should be done very carefully.
 182 </p>
 183 <p>
 184 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
 185 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
 186 if they do match.
 187 </p>
 188 <div class="variablelist"><table border="0">
 189 <col align="left" valign="top">
 190 <tbody>
 191 <tr>
 192 <td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>
 193 <td>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 194 </td>
 195 </tr>
 196 <tr>
 197 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 198 <td>the string to add
 199 </td>
 200 </tr>
 201 <tr>
 202 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 203 <td> a pointer to the new or existing copy of <em class="parameter"><code>string</code></em>
 204          within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 205 </td>
 206 </tr>
 207 </tbody>
 208 </table></div>
 209 </div>
 210 <hr>
 211 <div class="refsect2" title="g_string_chunk_insert_len ()">
 212 <a name="g-string-chunk-insert-len"></a><h3>g_string_chunk_insert_len ()</h3>
 213 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>*              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>,
 214                                                          <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>,
 215                                                          <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>
 216 <p>
 217 Adds a copy of the first <em class="parameter"><code>len</code></em> bytes of <em class="parameter"><code>string</code></em> to the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 218 The copy is nul-terminated.
 219 </p>
 220 <p>
 221 Since this function does not stop at nul bytes, it is the caller's
 222 responsibility to ensure that <em class="parameter"><code>string</code></em> has at least <em class="parameter"><code>len</code></em> addressable
 223 bytes.
 224 </p>
 225 <p>
 226 The characters in the returned string can be changed, if necessary,
 227 though you should not change anything after the end of the string.
 228 </p>
 229 <div class="variablelist"><table border="0">
 230 <col align="left" valign="top">
 231 <tbody>
 232 <tr>
 233 <td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>
 234 <td>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 235 </td>
 236 </tr>
 237 <tr>
 238 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 239 <td>bytes to insert
 240 </td>
 241 </tr>
 242 <tr>
 243 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 244 <td>number of bytes of <em class="parameter"><code>string</code></em> to insert, or -1 to insert a
 245     nul-terminated string
 246 </td>
 247 </tr>
 248 <tr>
 249 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 250 <td> a pointer to the copy of <em class="parameter"><code>string</code></em> within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 251
 252 </td>
 253 </tr>
 254 </tbody>
 255 </table></div>
 256 <p class="since">Since 2.4</p>
 257 </div>
 258 <hr>
 259 <div class="refsect2" title="g_string_chunk_clear ()">
 260 <a name="g-string-chunk-clear"></a><h3>g_string_chunk_clear ()</h3>
 261 <pre class="programlisting"><span class="returnvalue">void</span>                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>
 262 <p>
 263 Frees all strings contained within the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 264 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
 265 access any of the strings which were contained within it.
 266 </p>
 267 <div class="variablelist"><table border="0">
 268 <col align="left" valign="top">
 269 <tbody><tr>
 270 <td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>
 271 <td>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 272 </td>
 273 </tr></tbody>
 274 </table></div>
 275 <p class="since">Since 2.14</p>
 276 </div>
 277 <hr>
 278 <div class="refsect2" title="g_string_chunk_free ()">
 279 <a name="g-string-chunk-free"></a><h3>g_string_chunk_free ()</h3>
 280 <pre class="programlisting"><span class="returnvalue">void</span>                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>
 281 <p>
 282 Frees all memory allocated by the <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>.
 283 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
 284 access any of the strings which were contained within it.
 285 </p>
 286 <div class="variablelist"><table border="0">
 287 <col align="left" valign="top">
 288 <tbody><tr>
 289 <td><p><span class="term"><em class="parameter"><code>chunk</code></em> :</span></p></td>
 290 <td>a <a class="link" href="glib-String-Chunks.html#GStringChunk" title="GStringChunk"><span class="type">GStringChunk</span></a>
 291 </td>
 292 </tr></tbody>
 293 </table></div>
 294 </div>
 295 </div>
 296 </div>
 297 <div class="footer">
 298 <hr>
 299           Generated by GTK-Doc V1.15</div>
 300 </body>
 301 </html>