add example folder

source/docs-libbson/bson_array_builder_t.txt

@@ -33,7 +33,7 @@ Appending an Array Value
 
 ``bson_append_array_builder_begin`` may be used to append an array as a value. Example:
 
-.. literalinclude:: ../examples/creating.c
+.. literalinclude:: includes/examples/creating.c
    :language: c
    :start-after: // bson_array_builder_t example ... begin
    :end-before: // bson_array_builder_t example ... end
@@ -58,7 +58,7 @@ be reused and will start appending a new array at index "0":
 
 Example:
 
-.. literalinclude:: ../examples/creating.c
+.. literalinclude:: includes/examples/creating.c
    :language: c
    :start-after: // bson_array_builder_t top-level example ... begin
    :end-before: // bson_array_builder_t top-level example ... end

source/docs-libbson/bson_visitor_t.txt

@@ -232,6 +232,6 @@ Example Corruption Check
 Example Custom Validation
 -------------------------
 
-.. literalinclude:: ../examples/bson-check-depth.c
+.. literalinclude:: includes/examples/bson-check-depth.c
    :caption: bson-check-depth.c
    :start-after: -- sphinx-include-start --

source/docs-libbson/creating.txt

@@ -66,7 +66,7 @@ Sub-Documents and Sub-Arrays
 To simplify the creation of sub-documents :ref:`bson_append_document_begin` can be used
 to build a sub-document using the parent's memory region as the destination buffer.
 
-.. literalinclude:: ../examples/creating.c
+.. literalinclude:: includes/examples/creating.c
    :language: c
    :start-after: // bson_append_document_begin example ... begin
    :end-before: // bson_append_document_begin example ... end
@@ -75,7 +75,7 @@ to build a sub-document using the parent's memory region as the destination buff
 To simplify the creation of sub-arrays :ref:`bson_array_builder_t` can be used to build a sub-array
 using the parent's memory region as the destination buffer.
 
-.. literalinclude:: ../examples/creating.c
+.. literalinclude:: includes/examples/creating.c
    :language: c
    :start-after: // bson_array_builder_t example ... begin
    :end-before: // bson_array_builder_t example ... end

source/docs-libbson/include-and-link.txt

@@ -9,7 +9,7 @@ Include bson.h
 
 All libbson's functions and types are available in one header file. Simply include ``bson.h``:
 
-.. literalinclude:: ../examples/hello_bson.c
+.. literalinclude:: includes/examples/hello_bson.c
    :caption: hello_bson.c
    :start-after: -- sphinx-include-start --
 
@@ -19,13 +19,13 @@ CMake
 The libbson installation includes a `CMake config-file package`_, so you can use CMake's `find_package`_
 command to import libbson's CMake target and link to libbson (as a shared library):
 
-.. literalinclude:: ../examples/cmake/find_package/CMakeLists.txt
+.. literalinclude:: includes/examples/cmake/find_package/CMakeLists.txt
    :caption: CMakeLists.txt
    :start-after: -- sphinx-include-start --
 
 You can also use libbson as a static library instead: Use the ``mongo::bson_static`` CMake target:
 
-.. literalinclude:: ../examples/cmake/find_package_static/CMakeLists.txt
+.. literalinclude:: includes/examples/cmake/find_package_static/CMakeLists.txt
    :start-after: -- sphinx-include-start --
    :emphasize-lines: 1, 5
 
@@ -37,12 +37,12 @@ pkg-config
 
 If you're not using CMake, use `pkg-config`_ on the command line to set header and library paths:
 
-.. literalinclude:: ../examples/compile-with-pkg-config.sh
+.. literalinclude:: includes/examples/compile-with-pkg-config.sh
    :start-after: -- sphinx-include-start --
 
 Or to statically link to libbson:
 
-.. literalinclude:: ../examples/compile-with-pkg-config-static.sh
+.. literalinclude:: includes/examples/compile-with-pkg-config-static.sh
    :start-after: -- sphinx-include-start --
 
 .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/

source/docs-libbson/includes/examples/bcon-col-view.c

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2013 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 <bson/bson.h>
+
+#define QUERY(...) ELE_QUERY, __VA_ARGS__, NULL
+#define SORT(...) ELE_SORT, __VA_ARGS__, NULL
+#define LIMIT(var) ELE_LIMIT, (var)
+#define COL_VIEW_CREATE(...) col_view_create ("", __VA_ARGS__, ELE_END)
+
+typedef enum ele {
+   ELE_SORT,
+   ELE_LIMIT,
+   ELE_QUERY,
+   ELE_END,
+} ele_t;
+
+bson_t *
+col_view_create (const char *stub, ...)
+{
+   bson_t *bson;
+   va_list ap;
+   ele_t type;
+   int keep_going = 1;
+
+   bcon_append_ctx_t ctx;
+   bcon_append_ctx_init (&ctx);
+
+   va_start (ap, stub);
+
+   bson = bson_new ();
+
+   while (keep_going) {
+      type = va_arg (ap, ele_t);
+
+      switch (type) {
+      case ELE_SORT:
+         BCON_APPEND_CTX (bson, &ctx, "sort", "{");
+         bcon_append_ctx_va (bson, &ctx, &ap);
+         BCON_APPEND_CTX (bson, &ctx, "}");
+         break;
+      case ELE_LIMIT: {
+         int i = va_arg (ap, int);
+         BCON_APPEND_CTX (bson, &ctx, "limit", BCON_INT32 (i));
+         break;
+      }
+      case ELE_QUERY:
+         BCON_APPEND_CTX (bson, &ctx, "query", "{");
+         bcon_append_ctx_va (bson, &ctx, &ap);
+         BCON_APPEND_CTX (bson, &ctx, "}");
+         break;
+      case ELE_END:
+         keep_going = 0;
+         break;
+      default:
+         BSON_ASSERT (0);
+         break;
+      }
+   }
+
+   va_end (ap);
+
+   return bson;
+}
+
+int
+main (void)
+{
+   bson_t *bson;
+   char *json;
+
+   bson = COL_VIEW_CREATE (SORT ("a", BCON_INT32 (1)), QUERY ("hello", "world"), LIMIT (10));
+
+   json = bson_as_canonical_extended_json (bson, NULL);
+   printf ("%s\n", json);
+   bson_free (json);
+
+   bson_destroy (bson);
+
+   return 0;
+}

source/docs-libbson/includes/examples/bcon-speed.c

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2013-2014 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 <bson/bson.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/*
+ * This is a test for comparing the performance of BCON to regular
+ * bson_append*() function calls.
+ *
+ * Maybe run the following a few times to get an idea of the performance
+ * implications of using BCON. Generally, it's fast enough to be very
+ * useful and result in easier to read BSON code.
+ *
+ * time ./bcon-speed 100000 y
+ * time ./bcon-speed 100000 n
+ */
+
+
+int
+main (int argc, char *argv[])
+{
+   int i;
+   int n;
+   int bcon;
+   bson_t bson, foo, bar, baz;
+   bson_init (&bson);
+
+   if (argc != 3) {
+      fprintf (stderr,
+               "usage: bcon-speed NUM_ITERATIONS [y|n]\n"
+               "\n"
+               "  y = perform speed tests with bcon\n"
+               "  n = perform speed tests with bson_append\n"
+               "\n");
+      return EXIT_FAILURE;
+   }
+
+   BSON_ASSERT (argc == 3);
+
+   n = atoi (argv[1]);
+   bcon = (argv[2][0] == 'y') ? 1 : 0;
+
+   for (i = 0; i < n; i++) {
+      if (bcon) {
+         BCON_APPEND (
+            &bson, "foo", "{", "bar", "{", "baz", "[", BCON_INT32 (1), BCON_INT32 (2), BCON_INT32 (3), "]", "}", "}");
+      } else {
+         bson_append_document_begin (&bson, "foo", -1, &foo);
+         bson_append_document_begin (&foo, "bar", -1, &bar);
+         bson_append_array_begin (&bar, "baz", -1, &baz);
+         bson_append_int32 (&baz, "0", -1, 1);
+         bson_append_int32 (&baz, "1", -1, 2);
+         bson_append_int32 (&baz, "2", -1, 3);
+         bson_append_array_end (&bar, &baz);
+         bson_append_document_end (&foo, &bar);
+         bson_append_document_end (&bson, &foo);
+      }
+
+      bson_reinit (&bson);
+   }
+
+   bson_destroy (&bson);
+
+   return 0;
+}

source/docs-libbson/includes/examples/bson-check-depth.c

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2018-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.
+ */
+
+/* -- sphinx-include-start -- */
+/* Reports the maximum nested depth of a BSON document. */
+#include <bson/bson.h>
+
+#include <assert.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+typedef struct {
+   uint32_t depth;
+   uint32_t max_depth;
+   bool valid;
+} check_depth_t;
+
+bool
+_check_depth_document (const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data);
+
+static const bson_visitor_t check_depth_funcs = {
+   NULL,
+   NULL,
+   NULL,
+   NULL,
+   NULL,
+   _check_depth_document,
+   _check_depth_document,
+   NULL,
+};
+
+bool
+_check_depth_document (const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data)
+{
+   check_depth_t *state = (check_depth_t *) data;
+   bson_iter_t child;
+
+   BSON_UNUSED (iter);
+   BSON_UNUSED (key);
+
+   if (!bson_iter_init (&child, v_document)) {
+      fprintf (stderr, "corrupt\n");
+      return true; /* cancel */
+   }
+
+   state->depth++;
+   if (state->depth > state->max_depth) {
+      state->valid = false;
+      return true; /* cancel */
+   }
+
+   bson_iter_visit_all (&child, &check_depth_funcs, state);
+   state->depth--;
+   return false; /* continue */
+}
+
+void
+check_depth (const bson_t *bson, uint32_t max_depth)
+{
+   bson_iter_t iter;
+   check_depth_t state = {0};
+
+   if (!bson_iter_init (&iter, bson)) {
+      fprintf (stderr, "corrupt\n");
+   }
+
+   state.valid = true;
+   state.max_depth = max_depth;
+   _check_depth_document (&iter, NULL, bson, &state);
+   if (!state.valid) {
+      printf ("document exceeds maximum depth of %" PRIu32 "\n", state.max_depth);
+   } else {
+      char *as_json = bson_as_canonical_extended_json (bson, NULL);
+      printf ("document %s ", as_json);
+      printf ("is valid\n");
+      bson_free (as_json);
+   }
+}
+
+int
+main (int argc, char **argv)
+{
+   bson_reader_t *bson_reader;
+   const bson_t *bson;
+   bool reached_eof;
+   bson_error_t error;
+
+   if (argc != 3) {
+      fprintf (stderr, "usage: %s FILE MAX_DEPTH\n", argv[0]);
+      fprintf (stderr, "Checks that the depth of the BSON contained in FILE\n");
+      fprintf (stderr, "does not exceed MAX_DEPTH\n");
+   }
+
+   const char *const filename = argv[1];
+   const int max_depth = atoi (argv[2]);
+
+   bson_reader = bson_reader_new_from_file (filename, &error);
+   if (!bson_reader) {
+      printf ("could not read %s: %s\n", filename, error.message);
+      return 1;
+   }
+
+   BSON_ASSERT (bson_in_range_signed (uint32_t, max_depth));
+
+   while ((bson = bson_reader_read (bson_reader, &reached_eof))) {
+      check_depth (bson, (uint32_t) max_depth);
+   }
+
+   if (!reached_eof) {
+      printf ("error reading BSON\n");
+   }
+
+   bson_reader_destroy (bson_reader);
+   return 0;
+}