|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /proc/21585/root/usr/share/gtk-doc/html/glib/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>String Chunks</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="GLib Reference Manual">
<link rel="up" href="glib-data-types.html" title="GLib Data Types">
<link rel="prev" href="glib-Strings.html" title="Strings">
<link rel="next" href="glib-Arrays.html" title="Arrays">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="glib.html" title="GLib Overview">
<link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
<link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
<link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
<link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
<link rel="chapter" href="tools.html" title="GLib Tools">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="glib-Strings.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GLib Reference Manual</th>
<td><a accesskey="n" href="glib-Arrays.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id3254524" class="shortcut">Top</a>
 | 
<a href="#id3254691" class="shortcut">Description</a></nobr></td></tr>
</table>
<div class="refentry" lang="en">
<a name="glib-String-Chunks"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>
<a name="id3254524"></a><span class="refentrytitle">String Chunks</span>
</h2>
<p>String Chunks — efficient storage of groups of strings.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
#include <glib.h>
<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a>;
<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a>* <a href="glib-String-Chunks.html#g-string-chunk-new">g_string_chunk_new</a> (<a href="glib-Basic-Types.html#gsize">gsize</a> size);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-String-Chunks.html#g-string-chunk-insert">g_string_chunk_insert</a> (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-String-Chunks.html#g-string-chunk-insert-const">g_string_chunk_insert_const</a> (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-String-Chunks.html#g-string-chunk-insert-len">g_string_chunk_insert_len</a> (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string,
<a href="glib-Basic-Types.html#gssize">gssize</a> len);
void <a href="glib-String-Chunks.html#g-string-chunk-free">g_string_chunk_free</a> (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id3254691"></a><h2>Description</h2>
<p>
String chunks are used to store groups of strings.
Memory is allocated in blocks, and as strings are added to the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>
they are copied into the next free position in a block. When a block is
full a new block is allocated.
</p>
<p>
When storing a large number of strings, string chunks are more efficient
than using <a href="glib-String-Utility-Functions.html#g-strdup"><code class="function">g_strdup()</code></a> since fewer calls to <code class="function"><code class="function">malloc()</code></code>
are needed, and less memory is wasted in memory allocation overheads.
</p>
<p>
By adding strings with <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a> it is also possible
to remove duplicates.
</p>
<p>
To create a new <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a> use <a href="glib-String-Chunks.html#g-string-chunk-new"><code class="function">g_string_chunk_new()</code></a>.
</p>
<p>
To add strings to a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a> use <a href="glib-String-Chunks.html#g-string-chunk-insert"><code class="function">g_string_chunk_insert()</code></a>.
</p>
<p>
To add strings to a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>, but without duplicating strings which are
already in the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>, use <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a>.
</p>
<p>
To free the entire <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a> use <a href="glib-String-Chunks.html#g-string-chunk-free"><code class="function">g_string_chunk_free()</code></a>.
It is not possible to free individual strings.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id3254864"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id3254874"></a><h3>
<a name="GStringChunk"></a>GStringChunk</h3>
<a class="indexterm" name="id3254887"></a><pre class="programlisting">typedef struct _GStringChunk GStringChunk;</pre>
<p>
An opaque data structure representing String Chunks.
It should only be accessed by using the following functions.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3254904"></a><h3>
<a name="g-string-chunk-new"></a>g_string_chunk_new ()</h3>
<a class="indexterm" name="id3254918"></a><pre class="programlisting"><a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a>* g_string_chunk_new (<a href="glib-Basic-Types.html#gsize">gsize</a> size);</pre>
<p>
Creates a new <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>size</code></em> :</span></td>
<td>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.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a new <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3254994"></a><h3>
<a name="g-string-chunk-insert"></a>g_string_chunk_insert ()</h3>
<a class="indexterm" name="id3255007"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_string_chunk_insert (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);</pre>
<p>
Adds a copy of <em class="parameter"><code>string</code></em> to the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
It returns a pointer to the new copy of the string in the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
The characters in the string can be changed, if necessary, though you
should not change anything after the end of the string.
</p>
<p>
Unlike <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a>, this function does not check for
duplicates. Also strings added with <a href="glib-String-Chunks.html#g-string-chunk-insert"><code class="function">g_string_chunk_insert()</code></a> will not be
searched by <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a> when looking for duplicates.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>chunk</code></em> :</span></td>
<td>a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>string</code></em> :</span></td>
<td>the string to add.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a pointer to the copy of <em class="parameter"><code>string</code></em> within the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3255174"></a><h3>
<a name="g-string-chunk-insert-const"></a>g_string_chunk_insert_const ()</h3>
<a class="indexterm" name="id3255188"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_string_chunk_insert_const (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);</pre>
<p>
Adds a copy of <em class="parameter"><code>string</code></em> to the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>, unless the same string has
already been added to the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a> with <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a>.
</p>
<p>
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.
</p>
<p>
Note that <a href="glib-String-Chunks.html#g-string-chunk-insert-const"><code class="function">g_string_chunk_insert_const()</code></a> will not return a pointer to a string
added with <a href="glib-String-Chunks.html#g-string-chunk-insert"><code class="function">g_string_chunk_insert()</code></a>, even if they do match.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>chunk</code></em> :</span></td>
<td>a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>string</code></em> :</span></td>
<td>the string to add.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td>a pointer to the new or existing copy of <em class="parameter"><code>string</code></em> within the
<a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3255358"></a><h3>
<a name="g-string-chunk-insert-len"></a>g_string_chunk_insert_len ()</h3>
<a class="indexterm" name="id3255374"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_string_chunk_insert_len (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *string,
<a href="glib-Basic-Types.html#gssize">gssize</a> len);</pre>
<p>
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 href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>. The
copy is nul-terminated.
</p>
<p>
The characters in the string can be changed, if necessary, though you
should not change anything after the end of the string.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>chunk</code></em> :</span></td>
<td> a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>string</code></em> :</span></td>
<td> bytes to insert
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>len</code></em> :</span></td>
<td> number of bytes of <em class="parameter"><code>string</code></em> to insert, or -1 to insert a
nul-terminated string.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> a pointer to the copy of <em class="parameter"><code>string</code></em> within the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>
</td>
</tr>
</tbody>
</table></div>
<p>Since 2.4
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3255537"></a><h3>
<a name="g-string-chunk-free"></a>g_string_chunk_free ()</h3>
<a class="indexterm" name="id3255550"></a><pre class="programlisting">void g_string_chunk_free (<a href="glib-String-Chunks.html#GStringChunk">GStringChunk</a> *chunk);</pre>
<p>
Frees all memory allocated by the <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
After calling <a href="glib-String-Chunks.html#g-string-chunk-free"><code class="function">g_string_chunk_free()</code></a> it is not safe to
access any of the strings which were contained within it.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>chunk</code></em> :</span></td>
<td>a <a href="glib-String-Chunks.html#GStringChunk"><span class="type">GStringChunk</span></a>.
</td>
</tr></tbody>
</table></div>
</div>
</div>
</div>
</body>
</html>