From c4a4e672fdcef60bbdd3e93cf3c8163a6cd7e08a Mon Sep 17 00:00:00 2001
From: Niels Lohmann <niels.lohmann@gmail.com>
Date: Fri, 29 Oct 2021 21:26:41 +0200
Subject: [PATCH] :memo: add examples for parsing from iterator pair (#3100)

---
 doc/examples/parse__iterator_pair.cpp    | 15 ++++++++++
 doc/examples/parse__iterator_pair.link   |  1 +
 doc/examples/parse__iterator_pair.output |  6 ++++
 doc/examples/parse__pointers.cpp         | 15 ++++++++++
 doc/examples/parse__pointers.link        |  1 +
 doc/examples/parse__pointers.output      |  6 ++++
 doc/mkdocs/docs/api/basic_json/parse.md  | 35 ++++++++++++++++++++++--
 7 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 doc/examples/parse__iterator_pair.cpp
 create mode 100644 doc/examples/parse__iterator_pair.link
 create mode 100644 doc/examples/parse__iterator_pair.output
 create mode 100644 doc/examples/parse__pointers.cpp
 create mode 100644 doc/examples/parse__pointers.link
 create mode 100644 doc/examples/parse__pointers.output

diff --git a/doc/examples/parse__iterator_pair.cpp b/doc/examples/parse__iterator_pair.cpp
new file mode 100644
index 000000000..d0c30c1a5
--- /dev/null
+++ b/doc/examples/parse__iterator_pair.cpp
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a JSON text given an input with other values
+    std::vector<std::uint8_t> input = {'[', '1', ',', '2', ',', '3', ']', 'o', 't', 'h', 'e', 'r'};
+
+    // parse and serialize JSON
+    json j_complete = json::parse(input.begin(), input.begin() + 7);
+    std::cout << std::setw(4) << j_complete << "\n\n";
+}
diff --git a/doc/examples/parse__iterator_pair.link b/doc/examples/parse__iterator_pair.link
new file mode 100644
index 000000000..f464e54c8
--- /dev/null
+++ b/doc/examples/parse__iterator_pair.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/hUJYo1HWmfTBLMGn"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__iterator_pair.output b/doc/examples/parse__iterator_pair.output
new file mode 100644
index 000000000..74633e808
--- /dev/null
+++ b/doc/examples/parse__iterator_pair.output
@@ -0,0 +1,6 @@
+[
+    1,
+    2,
+    3
+]
+
diff --git a/doc/examples/parse__pointers.cpp b/doc/examples/parse__pointers.cpp
new file mode 100644
index 000000000..a5a16eea9
--- /dev/null
+++ b/doc/examples/parse__pointers.cpp
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a JSON text given as string that is not null-terminated
+    const char* ptr = "[1,2,3]another value";
+
+    // parse and serialize JSON
+    json j_complete = json::parse(ptr, ptr + 7);
+    std::cout << std::setw(4) << j_complete << "\n\n";
+}
diff --git a/doc/examples/parse__pointers.link b/doc/examples/parse__pointers.link
new file mode 100644
index 000000000..9a93ef1c5
--- /dev/null
+++ b/doc/examples/parse__pointers.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/AWbpa8e1xRV3y4MM"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__pointers.output b/doc/examples/parse__pointers.output
new file mode 100644
index 000000000..74633e808
--- /dev/null
+++ b/doc/examples/parse__pointers.output
@@ -0,0 +1,6 @@
+[
+    1,
+    2,
+    3
+]
+
diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md
index 4a8a692d6..88d3f93a7 100644
--- a/doc/mkdocs/docs/api/basic_json/parse.md
+++ b/doc/mkdocs/docs/api/basic_json/parse.md
@@ -19,7 +19,7 @@ static basic_json parse(IteratorType first, IteratorType last,
 1. Deserialize from a compatible input.
 2. Deserialize from a pair of character iterators
     
-    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+    The `value_type` of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
     respectively as UTF-8, UTF-16 and UTF-32.
 
 ## Template parameters
@@ -34,7 +34,10 @@ static basic_json parse(IteratorType first, IteratorType last,
     - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
 
 `IteratorType`
-:   a compatible iterator type
+:   a compatible iterator type, for instance.
+
+    - a pair of `std::string::iterator` or `std::vector<std::uint8_t>::iterator`
+    - a pair of pointers such as `ptr` and `ptr + len`
 
 ## Parameters
 
@@ -135,6 +138,34 @@ super-linear complexity.
     --8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
     ```
 
+??? example "Parsing from a non null-terminated string"
+
+    The example below demonstrates the `parse()` function reading from a string that is not null-terminated.
+
+    ```cpp
+    --8<-- "examples/parse__pointers.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__pointers.output"
+    ```
+
+??? example "Parsing from an iterator pair"
+
+    The example below demonstrates the `parse()` function reading from an iterator pair.
+
+    ```cpp
+    --8<-- "examples/parse__iterator_pair.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__iterator_pair.output"
+    ```
+
 ??? example "Effect of `allow_exceptions` parameter"
 
     The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.