Uploaded image for project: 'C++ Driver'
  1. C++ Driver
  2. CXX-1294

Add new free functions to assist in efficient subdocument/subarray building with the basic builder

    • Type: Icon: New Feature New Feature
    • Resolution: Duplicate
    • Priority: Icon: Minor - P4 Minor - P4
    • None
    • Affects Version/s: None
    • Component/s: API
    • None

      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)))))));
      

            Assignee:
            Unassigned Unassigned
            Reporter:
            backlog-cxx-driver [DO NOT USE] Backlog - CXX Driver Team
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: