<?xml version="1.0"?>
<page id="bson_iter_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_iter_t</title>
  <subtitle>BSON Document Iterator</subtitle>

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

typedef struct
{
   /*< private >*/
} bson_iter_t;]]></code></synopsis>
  </section>

  <section id="description">
    <title>Description</title>
    <p><link xref="bson_iter_t">bson_iter_t</link> is a structure used to iterate through the elements of a <link xref="bson_t">bson_t</link>. It is meant to be used on the stack and can be discarded at any time as it contains no external allocation. The contents of the structure should be considered private and may change between releases, however the structure size will not change.</p>

    <p>The <link xref="bson_t">bson_t</link> <em>MUST</em> be valid for the lifetime of the iter and it is an error to modify the <link xref="bson_t">bson_t</link> while using the iter.</p>
  </section>

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

  <section id="examples">
    <title>Examples</title>

    <listing>
      <title>Iterate all Fields</title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc)) {
   while (bson_iter_next (&iter)) {
      printf ("Found a field named: %s\n", bson_iter_key (&iter));
   }
}]]></code></synopsis>
    </listing>

    <listing>
      <title>Find a Named Field</title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc) &&
    bson_iter_find (&iter, "my_field")) {
   printf ("Found the field named: %s\n", bson_iter_key (&iter));
}]]></code></synopsis>
    </listing>

    <listing>
      <title>Recurse into a Sub-Document or Sub-Array</title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_iter_t iter;
bson_iter_t sub_iter;

if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") &&
    (BSON_ITER_HOLDS_DOCUMENT (&iter) ||
     BSON_ITER_HOLDS_ARRAY (&iter)) &&
    bson_iter_recurse (&iter, &sub_iter)) {
   while (bson_iter_next (&sub_iter)) {
      printf ("Found key \"%s\" in sub document.\n",
              bson_iter_key (&sub_iter));
   }
}]]></code></synopsis>
    </listing>

    <listing>
      <title>Find a Sub-Document Field</title>
      <synopsis><code mime="text/x-csrc"><![CDATA[bson_iter_t iter;

if (bson_iter_init (&iter, my_doc) &&
    bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) {
   printf ("The type of a.b.c.d is: %d\n",
           (int)bson_iter_type (&sub_iter));
}]]></code></synopsis>
    </listing>
 
  </section>
</page>
