string_chunks.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-String-Chunks">
<refmeta>
<refentrytitle>String Chunks</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>String Chunks</refname><refpurpose>efficient storage of groups of strings.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GStringChunk">GStringChunk</link>;
<link linkend="GStringChunk">GStringChunk</link>* <link linkend="g-string-chunk-new">g_string_chunk_new</link>            (<link linkend="gsize">gsize</link> size);
<link linkend="gchar">gchar</link>*      <link linkend="g-string-chunk-insert">g_string_chunk_insert</link>           (<link linkend="GStringChunk">GStringChunk</link> *chunk,
                                             const <link linkend="gchar">gchar</link> *string);
<link linkend="gchar">gchar</link>*      <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>     (<link linkend="GStringChunk">GStringChunk</link> *chunk,
                                             const <link linkend="gchar">gchar</link> *string);
void        <link linkend="g-string-chunk-free">g_string_chunk_free</link>             (<link linkend="GStringChunk">GStringChunk</link> *chunk);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
String chunks are used to store groups of strings.
Memory is allocated in blocks, and as strings are added to the <link linkend="GStringChunk">GStringChunk</link>
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 <link linkend="g-strdup">g_strdup</link>() since fewer calls to <function><link linkend="malloc">malloc</link>()</function>
are needed, and less memory is wasted in memory allocation overheads.
</para>
<para>
By adding strings with <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>() it is also possible
to remove duplicates.
</para>
<para>
To create a new <link linkend="GStringChunk">GStringChunk</link> use <link linkend="g-string-chunk-new">g_string_chunk_new</link>().
</para>
<para>
To add strings to a <link linkend="GStringChunk">GStringChunk</link> use <link linkend="g-string-chunk-insert">g_string_chunk_insert</link>().
</para>
<para>
To add strings to a <link linkend="GStringChunk">GStringChunk</link>, but without duplicating strings which are
already in the <link linkend="GStringChunk">GStringChunk</link>, use <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>().
</para>
<para>
To free the entire <link linkend="GStringChunk">GStringChunk</link> use <link linkend="g-string-chunk-free">g_string_chunk_free</link>().
It is not possible to free individual strings.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GStringChunk">struct GStringChunk</title>
<programlisting>struct GStringChunk;</programlisting>
<para>
An opaque data structure representing String Chunks.
It should only be accessed by using the following functions.
</para></refsect2>
<refsect2>
<title><anchor id="g-string-chunk-new">g_string_chunk_new ()</title>
<programlisting><link linkend="GStringChunk">GStringChunk</link>* g_string_chunk_new            (<link linkend="gsize">gsize</link> size);</programlisting>
<para>
Creates a new <link linkend="GStringChunk">GStringChunk</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>size</parameter>&nbsp;:</entry>
<entry>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.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GStringChunk">GStringChunk</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-chunk-insert">g_string_chunk_insert ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_string_chunk_insert           (<link linkend="GStringChunk">GStringChunk</link> *chunk,
                                             const <link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Adds a copy of <parameter>string</parameter> to the <link linkend="GStringChunk">GStringChunk</link>.
It returns a pointer to the new copy of the string in the <link linkend="GStringChunk">GStringChunk</link>.
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 <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>(), this function does not check for
duplicates. Also strings added with <link linkend="g-string-chunk-insert">g_string_chunk_insert</link>() will not be
searched by <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>() when looking for duplicates.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>chunk</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStringChunk">GStringChunk</link>.
</entry></row>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to add.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the copy of <parameter>string</parameter> within the <link linkend="GStringChunk">GStringChunk</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-chunk-insert-const">g_string_chunk_insert_const ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_string_chunk_insert_const     (<link linkend="GStringChunk">GStringChunk</link> *chunk,
                                             const <link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Adds a copy of <parameter>string</parameter> to the <link linkend="GStringChunk">GStringChunk</link>, unless the same string has
already been added to the <link linkend="GStringChunk">GStringChunk</link> with <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>().
</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 <link linkend="g-string-chunk-insert-const">g_string_chunk_insert_const</link>() will not return a pointer to a string
added with <link linkend="g-string-chunk-insert">g_string_chunk_insert</link>(), even if they do match.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>chunk</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStringChunk">GStringChunk</link>.
</entry></row>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to add.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the new or existing copy of <parameter>string</parameter> within the
<link linkend="GStringChunk">GStringChunk</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-chunk-free">g_string_chunk_free ()</title>
<programlisting>void        g_string_chunk_free             (<link linkend="GStringChunk">GStringChunk</link> *chunk);</programlisting>
<para>
Frees all memory allocated by the <link linkend="GStringChunk">GStringChunk</link>.
After calling <link linkend="g-string-chunk-free">g_string_chunk_free</link>() it is not safe to
access any of the strings which were contained within it.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>chunk</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStringChunk">GStringChunk</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>