From 86b5ce953a4339e444f656353a6aaad378cae36d Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Sun, 28 Oct 2018 15:09:26 +0100
Subject: [PATCH] :memo: added examples for BSON functions

---
 doc/examples/from_bson.cpp    | 21 +++++++++++++++++++++
 doc/examples/from_bson.link   |  1 +
 doc/examples/from_bson.output |  4 ++++
 doc/examples/to_bson.cpp      | 21 +++++++++++++++++++++
 doc/examples/to_bson.link     |  1 +
 doc/examples/to_bson.output   |  1 +
 include/nlohmann/json.hpp     | 12 ++++++++----
 7 files changed, 57 insertions(+), 4 deletions(-)
 create mode 100644 doc/examples/from_bson.cpp
 create mode 100644 doc/examples/from_bson.link
 create mode 100644 doc/examples/from_bson.output
 create mode 100644 doc/examples/to_bson.cpp
 create mode 100644 doc/examples/to_bson.link
 create mode 100644 doc/examples/to_bson.output

diff --git a/doc/examples/from_bson.cpp b/doc/examples/from_bson.cpp
new file mode 100644
index 00000000..df71dd37
--- /dev/null
+++ b/doc/examples/from_bson.cpp
@@ -0,0 +1,21 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create byte vector
+    std::vector<uint8_t> v = {0x1b, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6f, 0x6d,
+                              0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73,
+                              0x63, 0x68, 0x65, 0x6d, 0x61, 0x00, 0x00, 0x00,
+                              0x00, 0x00, 0x00
+                             };
+
+    // deserialize it with BSON
+    json j = json::from_bson(v);
+
+    // print the deserialized JSON value
+    std::cout << std::setw(2) << j << std::endl;
+}
diff --git a/doc/examples/from_bson.link b/doc/examples/from_bson.link
new file mode 100644
index 00000000..59fee158
--- /dev/null
+++ b/doc/examples/from_bson.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/qtfoxfHO7u4eKMcO"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/from_bson.output b/doc/examples/from_bson.output
new file mode 100644
index 00000000..259f63bd
--- /dev/null
+++ b/doc/examples/from_bson.output
@@ -0,0 +1,4 @@
+{
+  "compact": true,
+  "schema": 0
+}
diff --git a/doc/examples/to_bson.cpp b/doc/examples/to_bson.cpp
new file mode 100644
index 00000000..fd2884f1
--- /dev/null
+++ b/doc/examples/to_bson.cpp
@@ -0,0 +1,21 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON value
+    json j = R"({"compact": true, "schema": 0})"_json;
+
+    // serialize it to BSON
+    std::vector<uint8_t> v = json::to_bson(j);
+
+    // print the vector content
+    for (auto& byte : v)
+    {
+        std::cout << "0x" << std::hex << std::setw(2) << std::setfill('0') << (int)byte << " ";
+    }
+    std::cout << std::endl;
+}
diff --git a/doc/examples/to_bson.link b/doc/examples/to_bson.link
new file mode 100644
index 00000000..c069a220
--- /dev/null
+++ b/doc/examples/to_bson.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/2roucrct3qDL6LCk"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/to_bson.output b/doc/examples/to_bson.output
new file mode 100644
index 00000000..379532a2
--- /dev/null
+++ b/doc/examples/to_bson.output
@@ -0,0 +1 @@
+0x1b 0x00 0x00 0x00 0x08 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0x00 0x01 0x10 0x73 0x63 0x68 0x65 0x6d 0x61 0x00 0x00 0x00 0x00 0x00 0x00 
diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp
index fdd692cb..0ba01de7 100644
--- a/include/nlohmann/json.hpp
+++ b/include/nlohmann/json.hpp
@@ -6672,6 +6672,9 @@ class basic_json
 
     @complexity Linear in the size of the JSON value @a j.
 
+    @liveexample{The example shows the serialization of a JSON value to a byte
+    vector in BSON format.,to_bson}
+
     @sa http://bsonspec.org/spec.html
     @sa @ref from_bson(detail::input_adapter&&, const bool strict) for the
         analogous deserialization
@@ -7020,9 +7023,6 @@ class basic_json
         return res ? result : basic_json(value_t::discarded);
     }
 
-
-
-
     /*!
     @brief Create a JSON value from an input in BSON format
 
@@ -7054,7 +7054,6 @@ class basic_json
     Max Key         | 0x7F             | still unsupported
     Min Key         | 0xFF             | still unsupported
 
-
     @warning The mapping is **incomplete**. The unsupported mappings
              are indicated in the table above.
 
@@ -7068,6 +7067,11 @@ class basic_json
 
     @throw parse_error.114 if an unsupported BSON record type is encountered
 
+    @complexity Linear in the size of the input @a i.
+
+    @liveexample{The example shows the deserialization of a byte vector in
+    BSON format to a JSON value.,from_bson}
+
     @sa http://bsonspec.org/spec.html
     @sa @ref to_bson(const basic_json&) for the analogous serialization
     @sa @ref from_cbor(detail::input_adapter&&, const bool, const bool) for the