CXX-3082 Add examples for bsoncxx::v_noabi::builder::concatenate

docs/api/bsoncxx/examples/bson_documents/create_array.md

@@ -32,6 +32,10 @@
 
 @snippet api/bsoncxx/examples/bson_documents/create_array/builder_make_document.cpp Example
 
+### With concatenate
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_concatenate.cpp Example
+
 ### With Multiple Appends
 
 @snippet api/bsoncxx/examples/bson_documents/create_array/builder_append.cpp Example

docs/api/bsoncxx/examples/bson_documents/create_doc.md

@@ -32,6 +32,10 @@
 
 @snippet api/bsoncxx/examples/bson_documents/create_doc/builder_make_document.cpp Example
 
+### With concatenate
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_concatenate.cpp Example
+
 ### With Multiple Appends
 
 @snippet api/bsoncxx/examples/bson_documents/create_doc/builder_append.cpp Example

examples/api/bsoncxx/examples/bson_documents/access_array/algorithms.cpp

@@ -17,7 +17,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -46,5 +46,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2.0, "three"));
 }

examples/api/bsoncxx/examples/bson_documents/access_array/basic.cpp

@@ -14,7 +14,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -47,6 +47,6 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {  // clang-format off
-    example(bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2.0, "three"));
 
 }  // clang-format on

examples/api/bsoncxx/examples/bson_documents/access_array/find.cpp

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -41,5 +41,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2));
 }

examples/api/bsoncxx/examples/bson_documents/access_array/iterators.cpp

@@ -14,7 +14,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -57,5 +57,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2));
 }

examples/api/bsoncxx/examples/bson_documents/access_array/subscript.cpp

@@ -14,7 +14,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -41,5 +41,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2));
 }

examples/api/bsoncxx/examples/bson_documents/create_array/builder_concatenate.cpp

@@ -0,0 +1,43 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <iostream>
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/concatenate.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// a: [1]
+// b: [2]
+void example(bsoncxx::array::view a, bsoncxx::array::view b) {
+    bsoncxx::builder::basic::array builder;
+
+    builder.append(bsoncxx::builder::concatenate(a));
+    builder.append(bsoncxx::builder::concatenate(b));
+
+    ASSERT(builder.view() == bsoncxx::builder::basic::make_array(1, 2));
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::builder::basic::make_array(1), bsoncxx::builder::basic::make_array(2));
+}

examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_value.cpp

@@ -18,8 +18,8 @@
 
 #include <bsoncxx/array/value.hpp>
 #include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/document/value.hpp>
-#include <bsoncxx/json.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -47,8 +47,8 @@ void example(const std::uint8_t* data, std::size_t length) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    bsoncxx::document::value owner = bsoncxx::from_json(R"({"v": [1, 2]})");
-    bsoncxx::array::view arr = owner.view()["v"].get_array().value;
+    const auto owner = bsoncxx::builder::basic::make_array(1, 2);
+    const auto arr = owner.view();
 
     example(arr.data(), arr.length());
 }

examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_view.cpp

@@ -18,7 +18,6 @@
 #include <bsoncxx/array/view.hpp>
 #include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/document/value.hpp>
-#include <bsoncxx/json.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -39,8 +38,8 @@ void example(const std::uint8_t* data, std::size_t length) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    bsoncxx::document::value owner = bsoncxx::from_json(R"({"v": [1, 2]})");
-    bsoncxx::array::view arr = owner.view()["v"].get_array().value;
+    const auto owner = bsoncxx::builder::basic::make_array(1, 2);
+    const auto arr = owner.view();
 
     example(arr.data(), arr.length());
 }

examples/api/bsoncxx/examples/bson_documents/create_doc/builder_concatenate.cpp

@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/concatenate.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// a: {"a": 1}
+// b: {"b": 2}
+void example(bsoncxx::document::view a, bsoncxx::document::view b) {
+    bsoncxx::builder::basic::document builder;
+
+    builder.append(bsoncxx::builder::concatenate(a));
+    builder.append(bsoncxx::builder::concatenate(b));
+
+    ASSERT(builder.view() == bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1})"), bsoncxx::from_json(R"({"b": 2})"));
+}

examples/api/bsoncxx/examples/bson_documents/elements/arr_multi.cpp

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 #include <bsoncxx/array/element.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -62,8 +62,8 @@ void example(bsoncxx::array::element e) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
-    const auto arr = doc["v"].get_array().value;
+    const auto owner = bsoncxx::builder::basic::make_array(1, 2.0, "three");
+    const auto arr = owner.view();
 
     example(arr[0]);
     example(arr[1]);

examples/api/bsoncxx/examples/bson_documents/elements/arr_single.cpp

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 #include <bsoncxx/array/element.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -40,8 +40,8 @@ void example(bsoncxx::array::element e) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
-    const auto arr = doc["v"].get_array().value;
+    const auto owner = bsoncxx::builder::basic::make_array(1, 2.0, "three");
+    const auto arr = owner.view();
 
     example(arr[0]);
     example(arr[1]);

examples/api/bsoncxx/examples/bson_documents/values/arr_view.cpp

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 #include <bsoncxx/array/element.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 #include <bsoncxx/types/bson_value/view.hpp>
 
@@ -48,8 +48,8 @@ void example(bsoncxx::array::element e) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
-    const auto arr = doc["v"].get_array().value;
+    const auto owner = bsoncxx::builder::basic::make_array(1, 2.0, "three");
+    const auto arr = owner.view();
 
     example(arr[0]);
     example(arr[1]);

examples/api/bsoncxx/examples/bson_errors/access_arr_iter_end.cpp

@@ -14,7 +14,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -48,5 +48,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2, 3]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2, 3));
 }

examples/api/bsoncxx/examples/bson_errors/access_arr_key_missing.cpp

@@ -16,7 +16,7 @@
 
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/array/view.hpp>
-#include <bsoncxx/json.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -38,5 +38,5 @@ void example(bsoncxx::array::view arr) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1, 2, 3]})")["v"].get_array().value);
+    example(bsoncxx::builder::basic::make_array(1, 2, 3));
 }

examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid_type.cpp

@@ -13,9 +13,9 @@
 // limitations under the License.
 
 #include <bsoncxx/array/element.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/exception/error_code.hpp>
 #include <bsoncxx/exception/exception.hpp>
-#include <bsoncxx/json.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <examples/api/runner.hh>
@@ -51,5 +51,5 @@ void example(bsoncxx::array::element e) {
 }  // namespace
 
 RUNNER_REGISTER_COMPONENT() {
-    example(bsoncxx::from_json(R"({"v": [1]})")["v"].get_array().value[0]);
+    example(bsoncxx::builder::basic::make_array(1).view()[0]);
 }

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp

@@ -26,8 +26,10 @@ namespace v_noabi {
 namespace builder {
 
 ///
-/// Container to concatenate a document. Use it by constructing an instance with the
-/// document to be concatenated, and pass it into a document stream builder.
+/// Container to concatenate a document.
+///
+/// Use this with a document builder to merge an existing document's fields with that of the
+/// document being built.
 ///
 struct concatenate_doc {
     document::view_or_value doc;
@@ -54,8 +56,10 @@ struct concatenate_doc {
 };
 
 ///
-/// Container to concatenate an array. Use this with the array stream builder in order
-/// to pass an array into a new builder and append its values to the stream.
+/// Container to concatenate an array.
+///
+/// Use this with an array builder to merge an existing array's fields with that of the array being
+/// built.
 ///
 struct concatenate_array {
     array::view_or_value array;
@@ -84,8 +88,8 @@ struct concatenate_array {
 ///
 /// Helper method to concatenate a document.
 ///
-/// Use this with the document stream builder to merge an existing document's fields with a new
-/// document's.
+/// Use this with a document or array builder to merge an existing document's fields with that of
+/// the document or array being built.
 ///
 /// @param doc The document to concatenate.
 ///
@@ -101,15 +105,15 @@ inline concatenate_doc concatenate(document::view_or_value doc) {
 ///
 /// Helper method to concatenate an array.
 ///
-/// Use this with the document stream builder to merge an existing array's fields with a new
-/// document's.
+/// Use this with a document or array builder to merge an existing array's fields with that of the
+/// document or array being built.
 ///
 /// @param array The array to concatenate.
 ///
 /// @return concatenate_doc A concatenating struct.
 ///
 /// @see
-/// - @ref bsoncxx::v_noabi::builder::concatenate_doc
+/// - @ref bsoncxx::v_noabi::builder::concatenate_array
 ///
 inline concatenate_array concatenate(array::view_or_value array) {
     return {std::move(array)};