<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="raptor-section-stringbuffer">
<refmeta>
<refentrytitle role="top_of_page" id="raptor-section-stringbuffer.top_of_page">String buffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RAPTOR Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>String buffer</refname>
<refpurpose>Append-only strings.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="raptor-section-stringbuffer.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
typedef             <link linkend="raptor-stringbuffer">raptor_stringbuffer</link>;
<link linkend="raptor-stringbuffer">raptor_stringbuffer</link>* <link linkend="raptor-new-stringbuffer">raptor_new_stringbuffer</link>            (void);
<link linkend="void">void</link>                <link linkend="raptor-free-stringbuffer">raptor_free_stringbuffer</link>            (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-append-counted-string">raptor_stringbuffer_append_counted_string</link>
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length,
                                                         <link linkend="int">int</link> do_copy);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-append-string">raptor_stringbuffer_append_string</link>   (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="int">int</link> do_copy);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-append-decimal">raptor_stringbuffer_append_decimal</link>  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         <link linkend="int">int</link> integer);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-append-stringbuffer">raptor_stringbuffer_append_stringbuffer</link>
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         <link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *append);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-prepend-counted-string">raptor_stringbuffer_prepend_counted_string</link>
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length,
                                                         <link linkend="int">int</link> do_copy);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-prepend-string">raptor_stringbuffer_prepend_string</link>  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="int">int</link> do_copy);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-stringbuffer-as-string">raptor_stringbuffer_as_string</link>       (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);
<link linkend="size-t">size_t</link>              <link linkend="raptor-stringbuffer-length">raptor_stringbuffer_length</link>          (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);
<link linkend="int">int</link>                 <link linkend="raptor-stringbuffer-copy-to-string">raptor_stringbuffer_copy_to_string</link>  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length);
</synopsis>
</refsynopsisdiv>









<refsect1 id="raptor-section-stringbuffer.description" role="desc">
<title role="desc.title">Description</title>
<para>
A utility class that allows easy construction of strings that
grow at the end by appending new strings.  Primarily used for
constructing/serializing syntaxes into strings by the <link linkend="raptor-iostream"><type>raptor_iostream</type></link>
and <link linkend="raptor-serializer"><type>raptor_serializer</type></link> classes.
</para>
</refsect1>

<refsect1 id="raptor-section-stringbuffer.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="raptor-stringbuffer" role="typedef">
<title>raptor_stringbuffer</title>
<indexterm zone="raptor-stringbuffer"><primary>raptor_stringbuffer</primary></indexterm><programlisting>raptor_stringbuffer* raptor_stringbuffer;
</programlisting>
<para>
Raptor string buffer class</para>
<para>

</para></refsect2>
<refsect2 id="raptor-new-stringbuffer" role="function">
<title>raptor_new_stringbuffer ()</title>
<indexterm zone="raptor-new-stringbuffer"><primary>raptor_new_stringbuffer</primary></indexterm><programlisting><link linkend="raptor-stringbuffer">raptor_stringbuffer</link>* raptor_new_stringbuffer            (void);</programlisting>
<para>
Create a new stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> pointer to a raptor_stringbuffer object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-free-stringbuffer" role="function">
<title>raptor_free_stringbuffer ()</title>
<indexterm zone="raptor-free-stringbuffer"><primary>raptor_free_stringbuffer</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_free_stringbuffer            (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);</programlisting>
<para>
Destroy a stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> stringbuffer object to destroy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-append-counted-string" role="function">
<title>raptor_stringbuffer_append_counted_string ()</title>
<indexterm zone="raptor-stringbuffer-append-counted-string"><primary>raptor_stringbuffer_append_counted_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_append_counted_string
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length,
                                                         <link linkend="int">int</link> do_copy);</programlisting>
<para>
If <parameter>string</parameter> is NULL or <parameter>length</parameter> is 0, no work is performed.
</para>
<para>
If <parameter>do_copy</parameter> is non-0, the passed-in string is copied into new memory
otherwise the stringbuffer becomes the owner of the string pointer
and will free it when the stringbuffer is destroyed.
</para>
<para>
Add a string to the stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> length of string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_copy</parameter>&nbsp;:</term>
<listitem><simpara> non-0 to copy the string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-append-string" role="function">
<title>raptor_stringbuffer_append_string ()</title>
<indexterm zone="raptor-stringbuffer-append-string"><primary>raptor_stringbuffer_append_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_append_string   (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="int">int</link> do_copy);</programlisting>
<para>
Add a string to the stringbuffer.
</para>
<para>
If <parameter>string</parameter> is NULL, no work is performed.
</para>
<para>
If <parameter>do_copy</parameter> is non-0, the passed-in string is copied into new memory
otherwise the stringbuffer becomes the owner of the string pointer
and will free it when the stringbuffer is destroyed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_copy</parameter>&nbsp;:</term>
<listitem><simpara> non-0 to copy the string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-append-decimal" role="function">
<title>raptor_stringbuffer_append_decimal ()</title>
<indexterm zone="raptor-stringbuffer-append-decimal"><primary>raptor_stringbuffer_append_decimal</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_append_decimal  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         <link linkend="int">int</link> integer);</programlisting>
<para>
Add an integer in decimal to the stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>integer</parameter>&nbsp;:</term>
<listitem><simpara> integer to format as decimal and add
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-append-stringbuffer" role="function">
<title>raptor_stringbuffer_append_stringbuffer ()</title>
<indexterm zone="raptor-stringbuffer-append-stringbuffer"><primary>raptor_stringbuffer_append_stringbuffer</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_append_stringbuffer
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         <link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *append);</programlisting>
<para>
Add a stringbuffer to the stringbuffer.
</para>
<para>
This function removes the content from the appending stringbuffer,
making it empty and appends it to the supplied stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-stringbuffer"><type>raptor_stringbuffer</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>append</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-stringbuffer"><type>raptor_stringbuffer</type></link> to append
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-prepend-counted-string" role="function">
<title>raptor_stringbuffer_prepend_counted_string ()</title>
<indexterm zone="raptor-stringbuffer-prepend-counted-string"><primary>raptor_stringbuffer_prepend_counted_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_prepend_counted_string
                                                        (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length,
                                                         <link linkend="int">int</link> do_copy);</programlisting>
<para>
If do_copy is non-0, the passed-in string is copied into new memory
otherwise the stringbuffer becomes the owner of the string pointer
and will free it when the stringbuffer is destroyed.
</para>
<para>
Add a string to the start of the stringbuffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> length of string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_copy</parameter>&nbsp;:</term>
<listitem><simpara> non-0 to copy the string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-prepend-string" role="function">
<title>raptor_stringbuffer_prepend_string ()</title>
<indexterm zone="raptor-stringbuffer-prepend-string"><primary>raptor_stringbuffer_prepend_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_prepend_string  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="int">int</link> do_copy);</programlisting>
<para>
Add a string to the start of the stringbuffer.
</para>
<para>
If do_copy is non-0, the passed-in string is copied into new memory
otherwise the stringbuffer becomes the owner of the string pointer
and will free it when the stringbuffer is destroyed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_copy</parameter>&nbsp;:</term>
<listitem><simpara> non-0 to copy the string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-as-string" role="function">
<title>raptor_stringbuffer_as_string ()</title>
<indexterm zone="raptor-stringbuffer-as-string"><primary>raptor_stringbuffer_as_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_stringbuffer_as_string       (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);</programlisting>
<para>
Return the stringbuffer as a C string.
</para>
<para>
Note: the return value is a to a shared string that the stringbuffer
allocates and manages.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> NULL on failure or stringbuffer is empty, otherwise
  a pointer to a shared copy of the string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-length" role="function">
<title>raptor_stringbuffer_length ()</title>
<indexterm zone="raptor-stringbuffer-length"><primary>raptor_stringbuffer_length</primary></indexterm><programlisting><link linkend="size-t">size_t</link>              raptor_stringbuffer_length          (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer);</programlisting>
<para>
Return the stringbuffer length.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> size of stringbuffer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-stringbuffer-copy-to-string" role="function">
<title>raptor_stringbuffer_copy_to_string ()</title>
<indexterm zone="raptor-stringbuffer-copy-to-string"><primary>raptor_stringbuffer_copy_to_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_stringbuffer_copy_to_string  (<link linkend="raptor-stringbuffer">raptor_stringbuffer</link> *stringbuffer,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="size-t">size_t</link> length);</programlisting>
<para>
Copy the stringbuffer into a string.
</para>
<para>
Copies the underlying string to a pre-allocated buffer.  The
output string is always '\0' terminated.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>stringbuffer</parameter>&nbsp;:</term>
<listitem><simpara> raptor stringbuffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> output string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> size of output string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure such as stringbuffer is empty, buffer is too small
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>