<?xml version="1.0"?>
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      style="function"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/"
      id="bson_steal">
  <info>
    <link type="guide" xref="bson_t" group="function"/>
  </info>
  <title>bson_steal()</title>

  <section id="synopsis">
    <title>Synopsis</title>
    <synopsis><code mime="text/x-csrc"><![CDATA[bool
bson_steal (bson_t *dst,
            bson_t *src);
]]></code></synopsis>
  </section>

  <section id="parameters">
    <title>Parameters</title>
    <table>
      <tr><td><p>dst</p></td><td><p>An uninitialized <code xref="bson_t">bson_t</code>.</p></td></tr>
      <tr><td><p>src</p></td><td><p>A <code xref="bson_t">bson_t</code>.</p></td></tr>
    </table>
  </section>

  <section id="description">
    <title>Description</title>
    <p>Efficiently transfer the contents of <code>src</code> to <code>dst</code> and destroy <code>src</code>.</p>
    <p>Before calling this function, <code>src</code> must be initialized and <code>dst</code> must be uninitialized. After this function returns successfully, <code>src</code> is destroyed, and <code>dst</code> is initialized and must be freed with <code xref="bson_destroy">bson_destroy</code>.</p>

    <p>For example, if you have a higher-level structure that wraps a <code xref="bson_t">bson_t</code>, use <code>bson_steal</code> to transfer BSON data into it:</p>
    <code mime="text/x-csrc"><![CDATA[typedef struct {
   bson_t bson;
} bson_wrapper_t;


bson_wrapper_t *
wrap_bson (bson_t *b)
{
   bson_wrapper_t *wrapper = bson_malloc (sizeof (bson_wrapper_t));

   if (bson_steal (&wrapper->bson, b)) {
      return wrapper;
   }

   bson_free (wrapper);
   return NULL;
}


void
bson_wrapper_destroy (bson_wrapper_t *wrapper)
{
   bson_destroy (&wrapper->bson);
   bson_free (wrapper);
}


int
main (int   argc,
      char *argv[])
{
   bson_t bson = BSON_INITIALIZER;
   bson_wrapper_t *wrapper;

   BSON_APPEND_UTF8 (&bson, "key", "value");

   /* now "bson" is destroyed */
   wrapper = wrap_bson (&bson);

   /* clean up */
   bson_wrapper_destroy (wrapper);
}
]]></code>
    <p>See also <code xref="bson_destroy_with_steal">bson_destroy_with_steal</code>, a lower-level function that returns the raw contents of a <code xref="bson_t">bson_t</code>.</p>
  </section>

  <section id="return">
    <title>Returns</title>
    <p>Returns true if <code>src</code> is valid and successfully moved to <code>dst</code>, false otherwise.</p>
  </section>
</page>
