# bson_iter_t

## BSON Document Iterator

## Synopsis

    #include <bson.h>

    typedef struct
    {
       /*< private >*/
    } bson_iter_t;

## Description

bson_iter_t is a structure used to iterate through the elements of a bson_t. 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.

The bson_t MUST be valid for the lifetime of the iter and it is an error to modify the bson_t while using the iter.

## Examples

### Iterate all Fields

    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));
       }
    }

### Find a Named Field

    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));
    }

### Recurse into a Sub-Document or Sub-Array

    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));
       }
    }

### Find a Sub-Document Field

    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));
    }