.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "BSON_ITER_T" "3" "2016\(hy10\(hy12" "libbson"
.SH NAME
bson_iter_t \- BSON Document Iterator
.SH "SYNOPSIS"

.nf
.nf
#include <bson.h>

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

.SH "DESCRIPTION"

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

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

.SH "EXAMPLES"

.nf
.nf
bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc)) {
   while (bson_iter_next (&iter)) {
      printf ("Found a field named: %s\en", bson_iter_key (&iter));
   }
}
.fi
.fi

.nf
.nf
bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc) &&
    bson_iter_find (&iter, "my_field")) {
   printf ("Found the field named: %s\en", bson_iter_key (&iter));
}
.fi
.fi

.nf
.nf
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 \e"%s\e" in sub document.\en",
              bson_iter_key (&sub_iter));
   }
}
.fi
.fi

.nf
.nf
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\en",
           (int)bson_iter_type (&sub_iter));
}
.fi
.fi


.B
.SH COLOPHON
This page is part of libbson.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.