🚸 add examples

doc/examples/array_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
+}

doc/examples/array_t.output

@@ -0,0 +1 @@
+true

doc/examples/binary_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
+}

doc/examples/binary_t.output

@@ -0,0 +1 @@
+true

doc/examples/boolean_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
+}

doc/examples/boolean_t.output

@@ -0,0 +1 @@
+true

doc/examples/number_float_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<double, json::number_float_t>::value << std::endl;
+}

doc/examples/number_float_t.output

@@ -0,0 +1 @@
+true

doc/examples/number_integer_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<std::int64_t, json::number_integer_t>::value << std::endl;
+}

doc/examples/number_integer_t.output

@@ -0,0 +1 @@
+true

doc/examples/number_unsigned_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<std::uint64_t, json::number_unsigned_t>::value << std::endl;
+}

doc/examples/number_unsigned_t.output

@@ -0,0 +1 @@
+true

doc/examples/object_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<std::map<json::string_t, json>, json::object_t>::value << std::endl;
+}

doc/examples/object_t.output

@@ -0,0 +1 @@
+true

doc/examples/string_t.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha << std::is_same<std::string, json::string_t>::value << std::endl;
+}

doc/examples/string_t.output

@@ -0,0 +1 @@
+true

doc/examples/to_string.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+using std::to_string;
+
+int main()
+{
+    // create values
+    json j = {{"one", 1}, {"two", 2}};
+    int i = 42;
+
+    // use ADL to select best to_string function
+    auto j_str = to_string(j);  // calling nlohmann::to_string
+    auto i_str = to_string(i);  // calling std::to_string
+
+    // serialize without indentation
+    std::cout << j_str << "\n\n"
+              << i_str << std::endl;
+}

doc/examples/to_string.output

@@ -0,0 +1,3 @@
+{"one":1,"two":2}
+
+42

doc/mkdocs/docs/api/basic_json/array_t.md

@@ -47,6 +47,22 @@ introduced by the compiler or runtime environment. A theoretical limit can be qu
 Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type
 `#!cpp array_t*` must be dereferenced.
 
+## Examples
+
+??? example
+
+    The following code shows that `array_t` is by default, a typedef to `#!cpp std::vector<nlohmann::json>`.
+     
+    ```cpp
+    --8<-- "examples/array_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/array_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/binary_t.md

@@ -63,6 +63,23 @@ type `#!cpp binary_t*` must be dereferenced.
     - 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.
 
+## Examples
+
+??? example
+
+    The following code shows that `binary_t` is by default, a typedef to
+    `#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
+     
+    ```cpp
+    --8<-- "examples/binary_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/binary_t.output"
+    ```
+
 ## See also
 
 - [byte_container_with_subtype](../byte_container_with_subtype/index.md)

doc/mkdocs/docs/api/basic_json/boolean_t.md

@@ -21,6 +21,22 @@ With the default values for `BooleanType` (`#!cpp bool`), the default value for
 
 Boolean values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `boolean_t` is by default, a typedef to `#!cpp bool`.
+     
+    ```cpp
+    --8<-- "examples/boolean_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/boolean_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/index.md

@@ -92,7 +92,7 @@ The class satisfies the following concept requirements:
 - [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
 - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
 - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
-- initializer_list_t
+- **initializer_list_t** - type for initializer lists of `basic_json` values
 - [**input_format_t**](input_format_t.md) - type to choose the format to parse
 - [**json_sax_t**](../json_sax/index.md) - type for SAX events
 
@@ -145,9 +145,9 @@ The class satisfies the following concept requirements:
 - [(constructor)](basic_json.md)
 - [(destructor)](~basic_json.md)
 - [**operator=**](operator=.md) - copy assignment
-- [**array**](array_t.md) (static) - explicitly create an array
+- [**array**](array_t.md) (_static_) - explicitly create an array
-- [**binary**](binary.md) (static) - explicitly create a binary array
+- [**binary**](binary.md) (_static_) - explicitly create a binary array
-- [**object**](object_t.md) (static) - explicitly create an object
+- [**object**](object_t.md) (_static_) - explicitly create an object
 
 ### Object inspection
 
@@ -242,9 +242,9 @@ Access to the JSON value
 
 ### Deserialization / Parsing
 
-- [**parse**](parse.md) (static) - deserialize from a compatible input
+- [**parse**](parse.md) (_static_) - deserialize from a compatible input
-- [**accept**](accept.md) (static) - check if the input is valid JSON
+- [**accept**](accept.md) (_static_) - check if the input is valid JSON
-- [**sax_parse**](sax_parse.md) (static) - generate SAX events
+- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events
 
 ### JSON Pointer functions
 
@@ -254,7 +254,7 @@ Access to the JSON value
 ### JSON Patch functions
 
 - [**patch**](patch.md) - applies a JSON patch
-- [**diff**](diff.md) (static) - creates a diff as a JSON patch
+- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch
 
 ### JSON Merge Patch functions
 
@@ -267,14 +267,14 @@ Access to the JSON value
 
 ### Binary formats
 
-- [**from_bson**](from_bson.md) (static) - create a JSON value from an input in BSON format
+- [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
-- [**from_cbor**](from_cbor.md) (static) - create a JSON value from an input in CBOR format
+- [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
-- [**from_msgpack**](from_msgpack.md) (static) - create a JSON value from an input in MessagePack format
+- [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
-- [**from_ubjson**](from_ubjson.md) (static) - create a JSON value from an input in UBJSON format
+- [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
-- [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value
+- [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
-- [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value
+- [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
-- [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value
+- [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
-- [**to_ubjson**](to_ubjson.md) (static) - create a UBJSON serialization of a given JSON value
+- [**to_ubjson**](to_ubjson.md) (_static_) - create a UBJSON serialization of a given JSON value
 
 ## Non-member functions
 

doc/mkdocs/docs/api/basic_json/input_format_t.md

@@ -25,7 +25,7 @@ ubjson
 :   UBJSON (Universal Binary JSON)
 
 bson
-:   BSON (Bin­ary JSON)
+:   BSON (Binary JSON)
 
 ## Version history
 

doc/mkdocs/docs/api/basic_json/number_float_t.md

@@ -49,6 +49,22 @@ and be serialized to `null`.
 
 Floating-point number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_float_t` is by default, a typedef to `#!cpp double`.
+     
+    ```cpp
+    --8<-- "examples/number_float_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_float_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/number_integer_t.md

@@ -55,6 +55,22 @@ interoperable.
 
 Integer number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_integer_t` is by default, a typedef to `#!cpp std::int64_t`.
+     
+    ```cpp
+    --8<-- "examples/number_integer_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_integer_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/number_unsigned_t.md

@@ -55,6 +55,22 @@ range [0, UINT64_MAX], this class's integer type is interoperable.
 
 Integer number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_unsigned_t` is by default, a typedef to `#!cpp std::uint64_t`.
+     
+    ```cpp
+    --8<-- "examples/number_unsigned_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_unsigned_t.output"
+    ```
+
 ## Version history
 
 - Added in version 2.0.0.

doc/mkdocs/docs/api/basic_json/object_t.md

@@ -92,6 +92,22 @@ return name/value pairs in a different order than they were originally stored. I
 alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
 [RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
 
+## Examples
+
+??? example
+
+    The following code shows that `object_t` is by default, a typedef to `#!cpp std::map<json::string_t, json>`.
+     
+    ```cpp
+    --8<-- "examples/object_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/string_t.md

@@ -45,6 +45,22 @@ This implementation is interoperable as it does compare strings code unit by cod
 String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type
 `string_t*` must be dereferenced.
 
+## Examples
+
+??? example
+
+    The following code shows that `string_t` is by default, a typedef to `#!cpp std::string`.
+     
+    ```cpp
+    --8<-- "examples/string_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/string_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

doc/mkdocs/docs/api/basic_json/to_string.md

@@ -39,6 +39,23 @@ std::string to_string(const BasicJsonType& j)
 }
 ```
 
+## Examples
+
+??? example
+
+    The following code shows how the library's `to_string()` function integrates with others, allowing
+    argument-dependent lookup.
+     
+    ```cpp
+    --8<-- "examples/to_string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_string.output"
+    ```
+
 ## See also
 
 - [dump](dump.md)

doc/mkdocs/mkdocs.yml

@@ -280,7 +280,7 @@ markdown_extensions:
 
 plugins:
     - search:
-        separator: '[\s\-\._]'
+        separator: '[\s\-\.]'
         lang: en
     - minify:
         minify_html: true

doc/mkdocs/scripts/check_structure.py

@@ -33,11 +33,12 @@ def check_structure():
         'Version history'
     ]
 
-    for file in glob.glob('api/**/*.md', recursive=True):
+    for file in sorted(glob.glob('api/**/*.md', recursive=True)):
         with open(file) as file_content:
             header_idx = -1
             existing_headers = []
             in_initial_code_example = False
+            previous_line = None
 
             for lineno, line in enumerate(file_content.readlines()):
                 line = line.strip()
@@ -74,6 +75,12 @@ def check_structure():
                 if line == '```' and in_initial_code_example:
                     in_initial_code_example = False
 
+                # consecutive blank lines are bad
+                if line == '' and previous_line == '':
+                    print(f'{file}:{lineno}-{lineno+1}: Error: Consecutive blank lines!')
+
+                previous_line = line
+
             for required_header in required_headers:
                 if required_header not in existing_headers:
                     print(f'{file}:{lineno+1}: Error: required header "{required_header}" was not found!')