📝 make examples collapsible

doc/mkdocs/Makefile

@@ -9,7 +9,7 @@ prepare_files: clean
 	# create subfolders
 	mkdir docs/images docs/examples
 	# copy images
-	cp -vr ../json.gif docs/images
+	cp -vr ../json.gif ../images/range-begin-end.svg ../images/range-rbegin-rend.svg docs/images
 	# copy examples
 	cp -vr ../examples/*.cpp ../examples/*.output docs/examples
 

doc/mkdocs/docs/features/binary_formats/bson.md

@@ -36,7 +36,7 @@ binary          | *any value*                       | binary      | 0x05
     and the keys may not contain U+0000, since they are serialized a
     zero-terminated c-strings.
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/to_bson.cpp"
@@ -81,7 +81,7 @@ Min Key         | 0xFF             | *unsupported*
     The mapping is **incomplete**. The unsupported mappings are indicated in the table above.
 
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/from_bson.cpp"

doc/mkdocs/docs/features/binary_formats/cbor.md

@@ -84,7 +84,7 @@ binary          | *size*: 4294967296..18446744073709551615   | byte string (8 by
       - half-precision floats (0xF9)
       - break (0xFF)
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/to_cbor.cpp"
@@ -159,7 +159,7 @@ Double-Precision Float | number_float    | 0xFB
 
 	CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/from_cbor.cpp"

doc/mkdocs/docs/features/binary_formats/index.md

@@ -5,7 +5,7 @@ Though JSON is a ubiquitous data format, it is not a very compact format suitabl
 - [BSON](bson.md) (Binary JSON),
 - [CBOR](cbor.md) (Concise Binary Object Representation),
 - [MessagePack](messagepack.md), and
-- [UBJSON](ubjson.md) (Universal Binary JSON Specification)
+- [UBJSON](ubjson.md) (Universal Binary JSON)
 
 to efficiently encode JSON values to byte vectors and to decode such vectors.
 
@@ -29,6 +29,8 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
 | MessagePack | supported     | supported       |
 | UBJSON      | not supported | not supported   |
 
+See [binary values](../binary_values.md) for more information.
+
 ### Sizes
 
 | Format             | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
@@ -39,3 +41,5 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
 | UBJSON             | 53,2 %      | 91,3 %       | 78,2 %            | 96,6 %        |
 | UBJSON (size)      | 58,6 %      | 92,3 %       | 86,8 %            | 97,4 %        |
 | UBJSON (size+type) | 55,9 %      | 92,3 %       | 85,0 %            | 95,0 %        |
+
+Sizes compared to minified JSON value.

doc/mkdocs/docs/features/binary_formats/messagepack.md

@@ -69,7 +69,7 @@ binary          | *size*: 65536..4294967295         | bin 32           | 0xC6
 
 	If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`.
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/to_msgpack.cpp"
@@ -129,7 +129,7 @@ negative fixint  | number_integer  | 0xE0-0xFF
 	Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
 
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/from_msgpack.cpp"

doc/mkdocs/docs/features/binary_formats/ubjson.md

@@ -81,7 +81,7 @@ object          | *see notes on optimized format*   | map         | `{`
     different JSON object.
 
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/to_ubjson.cpp"
@@ -120,7 +120,7 @@ object      | object (optimized values are supported) | `{`
 	The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
 
 
-!!! example
+??? example
 
     ```cpp
     --8<-- "examples/from_ubjson.cpp"

doc/mkdocs/docs/features/binary_values.md

@@ -88,7 +88,7 @@ Binary values are serialized differently according to the formats.
 
 JSON does not have a binary type, and this library does not introduce a new type as this would break conformance. Instead, binary values are serialized as an object with two keys: `bytes` holds an array of integers, and `subtype` is an integer or `null`.
 
-!!! example
+??? example
 
     Code:
 
@@ -120,7 +120,7 @@ JSON does not have a binary type, and this library does not introduce a new type
 
 [BSON](binary_formats/bson.md) supports binary values and subtypes. If a subtype is given, it is used and added as unsigned 8-bit integer. If no subtype is given, the generic binary subtype 0x00 is used.
 
-!!! example
+??? example
 
     Code:
     
@@ -160,7 +160,7 @@ JSON does not have a binary type, and this library does not introduce a new type
 
 [CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.
 
-!!! example
+??? example
 
     Code:
     
@@ -200,7 +200,7 @@ JSON does not have a binary type, and this library does not introduce a new type
 
 If no subtype is given, the bin family (bin8, bin16, bin32) is used.
 
-!!! example
+??? example
 
     Code:
     
@@ -239,7 +239,7 @@ If no subtype is given, the bin family (bin8, bin16, bin32) is used.
 
 [UBJSON](binary_formats/ubjson.md) neither supports binary values nor subtypes, and proposes to serialize binary values as array of uint8 values. This translation is implemented by the library.
 
-!!! example
+??? example
 
     Code:
     

doc/mkdocs/docs/features/iterators.md

+# Iterators
+
+## Overview
+
+A JSON value is a container and allows access via iterators. 
+
+![](../images/range-begin-end.svg)
+
+![](../images/range-rbegin-rend.svg)
+
+## Iterator getters
+
+### `begin()`
+
+??? example
+
+    The following code shows an example for `begin()`.
+
+    ```cpp
+    --8<-- "examples/begin.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/begin.output"
+    ```
+
+### `cbegin()`
+
+??? example
+
+    The following code shows an example for `cbegin()`.
+
+    ```cpp
+    --8<-- "examples/cbegin.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/cbegin.output"
+    ```
+
+### `end()`
+
+??? example
+
+    The following code shows an example for `end()`.
+
+    ```cpp
+    --8<-- "examples/end.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/end.output"
+    ```
+
+### `cend()`
+
+??? example
+
+    The following code shows an example for `cend()`.
+
+    ```cpp
+    --8<-- "examples/cend.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/cend.output"
+    ```
+
+### `rbegin()`
+
+??? example
+
+    The following code shows an example for `rbegin()`.
+
+    ```cpp
+    --8<-- "examples/rbegin.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/rbegin.output"
+    ```
+
+### `rend()`
+
+??? example
+
+    The following code shows an example for `rend()`.
+
+    ```cpp
+    --8<-- "examples/rend.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/rend.output"
+    ```
+
+### `items()`
+
+??? example
+
+    The following code shows an example for `items()`.
+
+    ```cpp
+    --8<-- "examples/items.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/items.output"
+    ```
+
+## Iterator invalidation
+
+| Operations | invalidated iterators |
+| ---------- | --------------------- |
+| `clear`    | all                   |

doc/mkdocs/docs/features/json_patch.md

-# JSON Patch
-
-On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows to describe differences between two JSON values - effectively allowing patch and diff operations known from Unix.
-
-```cpp
-
-// a JSON patch (RFC 6902)
-json j_patch = R"([
-  { "op": "replace", "path": "/baz", "value": "boo" },
-  { "op": "add", "path": "/hello", "value": ["world"] },
-  { "op": "remove", "path": "/foo"}
-])"_json;
-
-// apply the patch
-json j_result = j_original.patch(j_patch);
-// {
-//    "baz": "boo",
-//    "hello": ["world"]
-// }
-
-// calculate a JSON patch from two JSON values
-json::diff(j_result, j_original);
-// [
-//   { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
-//   { "op": "remove","path": "/hello" },
-//   { "op": "add", "path": "/foo", "value": "bar" }
-// ]
-```
+# JSON Patch and Diff
+
+## Patches
+
+JSON Patch ([RFC 6902](https://tools.ietf.org/html/rfc6902)) defines a JSON document structure for expressing a sequence of operations to apply to a JSON) document. With the `patch` function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.
+
+??? example
+
+    The following code shows how a JSON patch is applied to a value.
+
+    ```cpp
+    --8<-- "examples/patch.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/patch.output"
+    ```
+
+## Diff
+
+The library can also calculate a JSON patch (i.e., a **diff**) given two JSON values.
+
+!!! success "Invariant"
+
+    For two JSON values *source* and *target*, the following code yields always true:
+
+    ```cüü
+    source.patch(diff(source, target)) == target;
+    ```
+
+??? example
+
+    The following code shows how a JSON patch is created as a diff for two JSON values.
+
+    ```cpp
+    --8<-- "examples/diff.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/diff.output"
+    ```

doc/mkdocs/docs/features/merge_patch.md

 # JSON Merge Patch
 
-The library supports **JSON Merge Patch** ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
+The library supports JSON Merge Patch ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format.
+The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.
 
-```cpp
-// a JSON value
-json j_document = R"({
-  "a": "b",
-  "c": {
-    "d": "e",
-    "f": "g"
-  }
-})"_json;
+Instead of using [JSON Pointer](json_pointer.md) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
 
-// a patch
-json j_patch = R"({
-  "a":"z",
-  "c": {
-    "f": null
-  }
-})"_json;
+??? example
 
-// apply the patch
-j_document.merge_patch(j_patch);
-// {
-//  "a": "z",
-//  "c": {
-//    "d": "e"
-//  }
-// }
-```
+    The following code shows how a JSON Merge Patch is applied to a JSON document.
+
+    ```cpp
+    --8<-- "examples/merge_patch.cpp"
+    ```
+    
+    Output:
+
+    ```json
+    --8<-- "examples/merge_patch.output"
+    ```

doc/mkdocs/docs/features/sax_interface.md

@@ -3,7 +3,7 @@
 The library uses a SAX-like interface with the following functions:
 
 ```plantuml
-class sax {
+interface json::sax_t {
     + {abstract} bool null()
 
     + {abstract} bool boolean(bool val)

doc/mkdocs/docs/features/types.md

@@ -17,6 +17,8 @@ By default, JSON values are stored as follows:
 
 Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.
 
+## Storage
+
 ```plantuml
 enum value_t {
     null
@@ -44,8 +46,10 @@ class json_value << (U,orchid) >> {
 }
 
 class basic_json {
+    -- type and value --
     value_t m_type
     json_value m_value
+    -- derived types --
     + <u>typedef</u> object_t
     + <u>typedef</u> array_t
     + <u>typedef</u> binary_t

doc/mkdocs/mkdocs.yml

@@ -44,6 +44,7 @@ nav:
       - features/binary_formats/messagepack.md
       - features/binary_formats/ubjson.md
     - features/binary_values.md
+    - features/iterators.md
     - features/json_pointer.md
     - features/json_patch.md
     - features/merge_patch.md