<?xml version="1.0"?>
<page id="bson_string_t"
      type="guide"
      style="class"
      xmlns="http://projectmallard.org/1.0/"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/">

  <info>
    <link type="guide" xref="index#api-reference" />
  </info>

  <title>bson_string_t</title>
  <subtitle>String Building Abstraction</subtitle>

  <section id="description">
    <title>Synopsis</title>
    <synopsis><code mime="text/x-csrc"><![CDATA[#include <bson.h>

typedef struct
{
   char     *str;
   uint32_t  len;
   uint32_t  alloc;
} bson_string_t;]]></code></synopsis>
  </section>

  <section id="description">
    <title>Description</title>
    <p><link xref="bson_string_t">bson_string_t</link> is an abstraction for building strings. As chunks are added to the string, allocations are performed in powers of two.</p>
    <p>This API is useful if you need to build UTF-8 encoded strings.</p>
  </section>

  <links type="topic" groups="function" style="2column">
    <title>Functions</title>
  </links>

  <section id="examples">
    <title>Example</title>
    <listing>
      <title></title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_string_t *str;

str = bson_string_new (NULL);
bson_string_append_printf (str, "%d %s %f\n", 0, "some string", 0.123);
printf ("%s\n", str->str);

bson_string_free (str, true);]]></code></synopsis>
      <note style="tip"><p>You can call <link xref="bson_string_free">bson_string_free()</link> with <code>false</code> if you would like to take ownership of <code>str->str</code>. Some API's that do this might call <code mime="text/x-csrc">return bson_string_free (str, false);</code> after building the string.</p></note>
    </listing>
  </section>
</page>
