The bsoncxx basic builder provides an extremely flexible API for programmatically building documents with complex structures. However, for use cases of building simple documents of a known schema that contain any nested subdocuments or subarrays, the basic builder API is overly verbose.

To illustrate, see this example of using the basic builder to create the document {a: {b: [1, "x", {c: 1}]}}:

    auto doc1 = make_document(kvp("a", [](sub_document subdoc) {
        subdoc.append(kvp("b", [](sub_array subarr) {
            subarr.append(1, "x", [](sub_document subdoc) { subdoc.append(kvp("c", 1)); });
        }));
    }));

This can be simplified by creating subdocuments and subarrays using bsoncxx::make_document() or bsoncxx::make_array(). However, these helpers create document::value and array::value temporaries, which is inefficient. For example, the following code snippet performs the same function as the above code snippet and is more readable, but it creates two unnecessary document::value temporaries and one unnecessary array::value temporary in the process:

    auto doc2 = make_document(
        kvp("a", make_document(kvp("b", make_array(1, "x", make_document(kvp("c", 1))))))); 

We should provide some solution to users that aims to achieve the best of both worlds: the performance of the lambda approach, but the readability of the make_document() approach. For example, if we had helpers called make_sub_document_func() and make_sub_array_func(), we might be able to use them as follows:

    auto doc3 = make_document(
        kvp("a",
            make_sub_document_func(
                kvp("b", make_sub_array_func(1, "x", make_sub_document_func(kvp("c", 1)))))));