Working with BSON

Building Arrays in Loops

Sometimes it's necessary to build an array using a loop. With the basic builder, a top-level array can be built by simply calling append inside a loop:

// [ 1, 2, 3 ]
const auto elements = {1, 2, 3};
auto array_builder = bsoncxx::builder::basic::array{};
for (const auto& element : elements) {
    array_builder.append(element);
}

To build a subarray in a loop, pass a lambda to append (or as the second argument of kvp if the subarray is contained by a document rather than an array):

// { "foo" : [ 1, 2, 3 ] }
using bsoncxx::builder::basic::kvp;
using bsoncxx::builder::basic::sub_array;
const auto elements = {1, 2, 3};
auto doc = bsoncxx::builder::basic::document{};
doc.append(kvp("foo", [&elements](sub_array child) {
    for (const auto& element : elements) {
        child.append(element);
    }
}));

When building an array with the stream builder, it's important to be aware that the return type of using the << operator on a stream builder is not uniform. To build an array in a loop properly, intermediate values returned by the stream builder should be stored in variables when the type changes. One attempt to build an array from a stream builder using a loop might look like the following:

// { "subdocs" : [ { "key" : 1 }, { "key" : 2 }, { "key" : 3 } ], "another_key" : 42 }
using namespace bsoncxx;
builder::stream::document builder{};
auto in_array = builder << "subdocs" << builder::stream::open_array;
for (auto&& e : {1, 2, 3}) {
    in_array = in_array << builder::stream::open_document << "key" << e
                        << builder::stream::close_document;
}
auto after_array = in_array << builder::stream::close_array;
after_array << "another_key" << 42;
document::value doc = after_array << builder::stream::finalize;
std::cout << to_json(doc) << std::endl;

for (auto && e : {1, 2, 3}) {
   auto open_state = in_array << builder::stream::open_document;
   auto temp_state = open_state << "key" << e;
   in_array = temp_state << builder::stream::close_document;
}

Owning BSON Documents

bsoncxx::document::value

This type represents an actual BSON document, one that owns its buffer of data. These documents can be constructed from a builder by calling extract():

bsoncxx::document::value basic_doc{basic_builder.extract()};
bsoncxx::document::value stream_doc{stream_builder.extract()};

After calling extract() the builder is in a moved-from state, and should not be used.

It's possible to create a bsoncxx::document::value in a single line using the stream builder interface and the finalize token. finalize returns a document::value from a temporary stream builder:

// { "finalize" : "is nifty" }
bsoncxx::document::value one_line = bsoncxx::builder::stream::document{} << "finalize" << "is nifty" << bsoncxx::builder::stream::finalize;

Non-owning BSON Documents (views)

bsoncxx::document::view

This type is a view into an owning bsoncxx::document::value.

bsoncxx::document::view document_view{document_value.view()};

A document::value also implicitly converts to a document::view:

bsoncxx::document::view document_view{document_value};

In performance-critical code, passing views around is preferable to using values because we can avoid excess copying. Also, passing a view of a document allows us to use the document multiple times:

// { "copies" : { "$gt" : 100 } }
auto query_value = document{} << "copies" << open_document << "$gt" << 100 << close_document << finalize;
// Run the same query across different collections
auto collection1 = db["science_fiction"];
auto cursor1 = collection1.find(query_value.view());
auto collection2 = db["cookbooks"];
auto cursor2 = collection2.find(query_value.view());

Optionally-owning BSON Documents (view_or_value)

Many driver methods take a document::view_or_value parameter, for example, run_command:

bsoncxx::document::value run_command(bsoncxx::document::view_or_value command);

Such methods can take either a document::view or a document::value. If a document::value is passed in, it must be passed by r-value reference, so ownership of the document is transferred to the method.

document::value ping = document{} << "ping" << 1 << finalize;
// You can pass a document::view into run_command()
db.run_command(ping.view());
// Or you can move in a document::value
db.run_command(std::move(ping));

You shouldn't need to create view_or_value types directly in order to use the driver. They are offered as a convenience method to allow driver methods to take documents in either an owning or non-owning way. The view_or_value type also helps mitigate some of the lifetime issues discussed in the next section.

BSON Document Lifetime

It is imperative that document::value types outlive any document::view types that use them. If the underlying value gets cleaned up, the view will be left with a dangling pointer. Consider a method that returns a view of a newly-created document:

bsoncxx::document::view make_a_dangling_view() {
   bsoncxx::builder::basic::document builder{};
   builder.append(kvp("hello", "world"));
   // This creates a document::value on the stack that will disappear when we return.
   bsoncxx::document::value stack_value{builder.extract()};
   // We're returning a view of the local value
   return stack_value.view(); // Bad!!
}

This method returns a dangling view that should not be used:

// This view contains a dangling pointer
bsoncxx::document::view dangling_view = make_a_dangling_view(); // Warning!!

Attempting to create a view off of a builder will similarly create a dangerous view object, because the temporary value returned from extract() isn't captured:

bsoncxx::builder::stream::document temp_builder{};
temp_builder << "oh" << "no";
bsoncxx::document::view dangling_view = temp_builder.extract().view(); // Bad!!

Printing BSON Documents

bsoncxx::to_json()

The bsoncxx library comes with a convenience method to convert BSON documents to strings for easy inspection:

bsoncxx::document::value = document{} << "I am" << "a BSON document" << finalize;
std::cout << bsoncxx::to_json(doc.view()) << std::endl;

There is an analogous method, from_json(), to build document::values out of existing JSON strings.

Getting Fields out of BSON Documents

The [ ] operator reaches into a BSON document to retrieve values:

// doc_view = { "store" : "Key Foods", "fruits" : [ "apple", "banana" ] }
auto store = doc_view["store"];
auto first_fruit = doc_view["fruits"][0];

This returns a bsoncxx::document::element, which holds the actual desired value:

document::element store_ele{doc_view["store"]};
if (store_ele) {
    // this block will only execute if "store" was found in the document
    std::cout << "Examining inventory at " << to_json(store_ele.get_value()) << std::endl;
}

This feature is shown in more detail in this example and this example.

BSON Types

The BSON specification provides a list of supported types. These are represented in C++ using the b_xxx type wrappers.

Some BSON types don't necessarily have a native representation to wrap and are implemented via special classes.