SYNOPSIS

#include <bson.h>

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

bool
bson_iter_init (bson_iter_t  *iter,
                const bson_t *bson);

bool
bson_iter_init_find (bson_iter_t  *iter,
                     const bson_t *bson,
                     const char   *key);

bool
bson_iter_init_find_case (bson_iter_t  *iter,
                          const bson_t *bson,
                          const char   *key);

DESCRIPTION

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

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

The bson_iter_init() function shall initialize iter to iterate upon the BSON document bson. Upon initialization, iter is placed before the first element. Callers must call bson_iter_next(), bson_iter_find(), or bson_iter_find_case() to advance to an element.

The bson_iter_init_find() function shall initialize iter to iterate upon the BSON document bson. Upon initialization, iter will be advanced to the first element named key. key is case-sensitive. If key was not found, FALSE is returned.

The bson_iter_init_find_case() function shall initialize iter to iterate upon the BSON document bson. Upon initialization, iter will be advanced to the first element named key. key is case-insensitive, and therefore "Foo" would match an element named "foo". If key was not found, FALSE is returned.

RETURN VALUE

bson_iter_init(), bson_iter_init_find(), and bson_iter_init_find_case() return TRUE if iter is valid for further use. iter should be considered invalid if any of these return FALSE.

ERRORS

If bson is invalid or there was another failure initializing iter, FALSE is returned and iter should be considered invalid.

EXAMPLES

static void
print_doc_id (const bson_t *doc)
{
        bson_iter_t iter;
        bson_oid_t oid;
        char oidstr[25];

        if (bson_iter_init (&iter, doc) &&
            bson_iter_find (&iter, "_id") &&
            BSON_ITER_HOLDS_OID (&iter)) {
                bson_iter_oid (&iter, &oid);
                bson_oid_to_string (&oid, oidstr);
                printf ("%s\n", oidstr);
        } else {
                printf ("Document is missing _id.\n");
        }
}

SEE ALSO

AUTHORS

This page was written by MongoDB, Inc.