.\" 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 "PARSING_AND_ITERATING_BSON_DOCUMENTS" "3" "2016\(hy10\(hy12" "libbson"
.SH NAME
Parsing_and_Iterating_BSON_Documents \- None
.SH "PARSING"

BSON documents are lazily parsed as necessary. To begin parsing a BSON document, use one of the provided Libbson functions to create a new
.B bson_t
from existing data such as
.B bson_new_from_data(3)
. This will make a copy of the data so that additional mutations may occur to the BSON document.

.B NOTE
.RS
If you only want to parse a BSON document and have no need to mutate it, you may use
.B bson_init_static(3)
to avoid making a copy of the data.
.RE

.nf
bson_t *b;

  b = bson_new_from_data (my_data, my_data_len);
  if (!b) {
     fprintf (stderr, "The specified length embedded in <my_data> did not match <my_data_len>\en");
     return;
  }

  bson_destroy (b);
.fi

Only two checks are performed when creating a new
.B bson_t
from an existing buffer. First, the document must begin with the buffer length, matching what was expected by the caller. Second, the document must end with the expected trailing
.B \0
byte.

To parse the document further we use a
.B bson_iter_t
to iterate the elements within the document. Let's print all of the field names in the document.

.nf
bson_t *b;
  bson_iter_t iter;

  if ((b = bson_new_from_data (my_data, my_data_len))) {
     if (bson_iter_init (&iter, b)) {
        while (bson_iter_next (&iter)) {
           printf ("Found element key: \e"%s\e"\en", bson_iter_key (&iter));
        }
     }
     bson_destroy (b);
  }
.fi

Converting a document to JSON uses a
.B bson_iter_t
and
.B bson_visitor_t
to iterate all fields of a BSON document recursively and generate a UTF\(hy8 encoded JSON string.

.nf
bson_t *b;
  char *json;

  if ((b = bson_new_from_data (my_data, my_data_len))) {
     if ((json = bson_as_json (b, NULL))) {
        printf ("%s\en", json);
        bson_free (json);
     }
     bson_destroy (b);
  }
.fi

.SH "RECURSING INTO SUB-DOCUMENTS"

Libbson provides convenient sub\(hyiterators to dive down into a sub\(hydocument or sub\(hyarray. Below is an example that will dive into a sub\(hydocument named "foo" and print it's field names.

.nf
bson_iter_t iter;
bson_iter_t *child;
char *json;

if (bson_iter_init_find (&iter, doc, "foo") &&
    BSON_ITER_HOLDS_DOCUMENT (&iter) &&
    bson_iter_recurse (&iter, &child)) {
   while (bson_iter_next (&child)) {
      printf ("Found sub\(hykey of \e"foo\e" named \e"%s\e"\en", bson_iter_key (&child));
   }
}
.fi

.SH "FINDING FIELDS USING DOT NOTATION"

Using the
.B bson_iter_recurse(3)
function exemplified above,
.B bson_iter_find_descendant(3)
can find a field for you using the MongoDB style path notation such as "foo.bar.0.baz".

Let's create a document like
.B {"foo": {"bar": [{"baz: 1}]}}
and locate the
.B "baz"
field.

.nf
bson_t *b;
bson_iter_t iter;
bson_iter_t baz;

b = BCON_NEW ("foo", "{", "bar", "[", "{", "baz", BCON_INT32 (1), "}", "]", "}");

if (bson_iter_init (&iter, b) &&
    bson_iter_find_descendant (&iter, "foo.bar.0.baz", &baz) &&
    BSON_ITER_HOLDS_INT32 (&baz)) {
   printf ("baz = %d\en", bson_iter_int32 (&baz));
}

bson_destroy (b);
.fi

.SH "VALIDATING A BSON DOCUMENT"

If all you want to do is validate that a BSON document is valid, you can use
.B bson_validate(3)
.

.nf
size_t err_offset;

if (!bson_validate (doc, BSON_VALIDATE_NONE, &err_offset)) {
   fprintf (stderr, "The document failed to validate at offset: %u\en",
            (unsigned)err_offset);
}
.fi

See the
.B bson_validate(3)
documentation for more information and examples.


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