📝 add more API documentation

doc/docset/docSet.sql

@@ -12,6 +12,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/ba
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Constructor', 'api/basic_json/basic_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('begin', 'Method', 'api/basic_json/begin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('binary', 'Function', 'api/basic_json/binary/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('binary_t', 'Type', 'api/basic_json/binary_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('boolean_t', 'Type', 'api/basic_json/boolean_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('cbegin', 'Method', 'api/basic_json/cbegin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('cbor_tag_handler_t', 'Enum', 'api/basic_json/cbor_tag_handler_t/index.html');
@@ -39,6 +40,9 @@ INSERT INTO searchIndex(name, type, path) VALUES ('from_ubjson', 'Function', 'ap
 INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_json/front/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('get', 'Method', 'api/basic_json/get/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('get_allocator', 'Function', 'api/basic_json/get_allocator/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('get_binary', 'Method', 'api/basic_json/get_binary/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('get_ptr', 'Method', 'api/basic_json/get_ptr/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('get_ref', 'Method', 'api/basic_json/get_ref/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('input_format_t', 'Enum', 'api/basic_json/input_format_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('insert', 'Method', 'api/basic_json/insert/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('invalid_iterator', 'Class', 'api/basic_json/invalid_iterator/index.html');
@@ -65,6 +69,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('number_float_t', 'Type', 'api
 INSERT INTO searchIndex(name, type, path) VALUES ('number_integer_t', 'Type', 'api/basic_json/number_integer_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('number_unsigned_t', 'Type', 'api/basic_json/number_unsigned_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('object', 'Function', 'api/basic_json/object/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('object_comparator_t', 'Type', 'api/basic_json/object_comparator_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('object_t', 'Type', 'api/basic_json/object_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator!=', 'Operator', 'api/basic_json/operator!=/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator+=', 'Operator', 'api/basic_json/operator+=/index.html');
@@ -73,6 +78,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('operator==', 'Operator', 'api
 INSERT INTO searchIndex(name, type, path) VALUES ('operator[]', 'Operator', 'api/basic_json/operator[]/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/basic_json/operator_literal_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/basic_json/operator_literal_json_pointer/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('operator ValueType', 'Operator', 'api/basic_json/operator_ValueType/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator value_t', 'Operator', 'api/basic_json/operator_value_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_json', 'Class', 'api/ordered_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map', 'Class', 'api/ordered_map/index.html');

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

+# basic_json::binary_t
+
+```cpp
+using binary_t = byte_container_with_subtype<BinaryType>;
+```
+
+This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type
+2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
+compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
+
+Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
+is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
+incompatible with each other, and it is up to the user to translate between them).
+
+[CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
+> Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
+> (major type 0).
+
+[MessagePack's documentation on the bin type
+family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
+> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
+
+[BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
+represent the generic binary type which has the description:
+> Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and
+> tools.
+
+None of these impose any limitations on the internal representation other than the basic unit of storage be some type of
+array whose parts are decomposable into bytes.
+
+The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to
+represent a byte array in modern C++.
+
+## Template parameters
+
+`BinaryType`
+:   container type to store arrays
+
+## Notes
+
+#### Default type
+
+The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
+
+#### Storage
+
+Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the
+type `#!cpp binary_t*` must be dereferenced.
+
+#### Notes on subtypes
+
+- CBOR
+    - Binary values are represented as byte strings. Subtypes are written as tags.
+
+- MessagePack
+    - If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
+      fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
+      then added as singed 8-bit integer.
+    - If no subtype is given, the bin family (bin8, bin16, bin32) is used.
+
+- BSON
+    - 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.
+
+## Version history
+
+- Added in version 3.8.0.

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

@@ -10,6 +10,13 @@ ValueType get() const noexcept(
 // (2)
 template<typename BasicJsonType>
 BasicJsonType get() const;
+
+// (3)
+template<typename PointerType>
+PointerType get_ptr();
+
+template<typename PointerType>
+constexpr const PointerType get_ptr() const noexcept;
 ```
 
 1. Explicit type conversion between the JSON value and a compatible value which is
@@ -52,7 +59,9 @@ BasicJsonType get() const;
 2. Overload for `basic_json` specializations. The function is equivalent to executing
     ```cpp
     return *this;
-    ``` 
+    ```
+
+3. Explicit pointer access to the internally stored JSON value. No copies are made.
 
 ## Template parameters
 
@@ -62,15 +71,28 @@ BasicJsonType get() const;
 `BasicJsonType`
 :   a specialization of `basic_json`
 
+`PointerType`
+:   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md),
+    [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile.
+
 ## Return value
 
 1. copy of the JSON value, converted to `ValueType`
 2. a copy of `#!cpp *this`, converted into `BasicJsonType`
+3. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
+   otherwise
 
 ## Exceptions
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
+## Notes
+
+!!! warning
+
+    Writing data to the pointee (overload 3) of the result yields an undefined state.
+
 ## Example
 
 ??? example
@@ -91,7 +113,23 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
     --8<-- "examples/get__ValueType_const.output"
     ```
 
+??? example
+
+    The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
+    conversions are made and a `#cpp nullptr` is returned if the value and the requested pointer type does not match.
+        
+    ```cpp
+    --8<-- "examples/get__PointerType.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get__PointerType.output"
+    ```
+
 ## Version history
 
 1. Since version 2.1.0.
 2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
+3. Since version 1.0.0.

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

+# basic_json::get_binary
+
+```cpp
+binary_t& get_binary();
+
+const binary_t& get_binary() const;
+```
+
+Returns a reference to the stored binary value.
+
+## Return value
+
+Reference to binary value.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Exceptions
+
+Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value is not binary
+
+## Complexity
+
+Constant.
+
+## Version history
+
+- Added in version 3.8.0.

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

+# basic_json::get_ptr
+
+```cpp
+template<typename PointerType>
+PointerType get_ptr();
+
+template<typename PointerType>
+constexpr const PointerType get_ptr() const noexcept;
+```
+
+Implicit pointer access to the internally stored JSON value. No copies are made.
+
+## Template arguments
+
+`PointerType`
+:   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md),
+    [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile.
+
+## Return value
+
+pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
+otherwise
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+!!! warning
+
+    Writing data to the pointee of the result yields an undefined state.
+
+## Example
+
+??? example
+
+    The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
+    conversions are made and a `#!cpp nullptr` is returned if the value and the requested pointer type does not match.
+    
+    ```cpp
+    --8<-- "examples/get_ptr.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_ptr.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to binary types in version 3.8.0.

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

+# basic_json::get_ref
+
+```cpp
+template<typename ReferenceType>
+ReferenceType get_ref();
+
+template<typename ReferenceType>
+const ReferenceType get_ref() const;
+```
+
+Implicit reference access to the internally stored JSON value. No copies are made.
+
+## Template arguments
+
+`ReferenceType`
+:   reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
+    [`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
+    [`number_unsigned`](number_unsigned.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Enforced by static assertion.
+
+## Return value
+
+reference to the internally stored JSON value if the requested reference type fits to the JSON value; throws
+[`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) otherwise
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Exceptions
+
+Throws [`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) if the requested reference type does not
+match the stored JSON value type; example: `"incompatible ReferenceType for get_ref, actual type is binary"`.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+!!! warning
+
+    Writing data to the referee of the result yields an undefined state.
+
+## Example
+
+??? example
+
+    The example shows several calls to `get_ref()`.
+    
+    ```cpp
+    --8<-- "examples/get_ref.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_ref.output"
+    ```
+
+## Version history
+
+- Added in version 1.1.0.
+- Extended to binary types in version 3.8.0.

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

@@ -68,33 +68,33 @@ Todo
 
 ### Container types
 
-| Type                   | Definition |
-| ---------------------- | ---------- |
-| value_type             | `#!cpp basic_json` |
-| reference              | `#!cpp value_type&` |
-| const_reference        | `#!cpp const value_type&` |
-| difference_type        | `#!cpp std::ptrdiff_t` |
-| size_type              | `#!cpp std::size_t` |
-| allocator_type         | `#!cpp AllocatorType<basic_json>` |
-| pointer                | `#!cpp std::allocator_traits<allocator_type>::pointer` |
-| const_pointer          | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
-| iterator               | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
-| const_iterator         | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
-| reverse_iterator       |  |
-| const_reverse_iterator |  |
-| iteration_proxy        |  |
+| Type                     | Definition |
+| ------------------------ | ---------- |
+| `value_type`             | `#!cpp basic_json` |
+| `reference`              | `#!cpp value_type&` |
+| `const_reference`        | `#!cpp const value_type&` |
+| `difference_type`        | `#!cpp std::ptrdiff_t` |
+| `size_type`              | `#!cpp std::size_t` |
+| `allocator_type`         | `#!cpp AllocatorType<basic_json>` |
+| `pointer`                | `#!cpp std::allocator_traits<allocator_type>::pointer` |
+| `const_pointer`          | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
+| `iterator`               | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
+| `const_iterator`         | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
+| `reverse_iterator`       |  |
+| `const_reverse_iterator` |  |
+| `iteration_proxy`        |  |
 
 ### JSON value data types
 
-- object_comparator_t
-- [**object_t**](object_t.md) - type for objects
 - [**array_t**](array_t.md) - type for arrays
-- [**string_t**](string_t.md) - type for strings
+- [**binary_t**](binary_t.md) - type for binary arrays
 - [**boolean_t**](boolean_t.md) - type for booleans
+- [**number_float_t**](number_float_t.md) - type for numbers (floating-point)
 - [**number_integer_t**](number_integer_t.md) - type for numbers (integer)
 - [**number_unsigned_t**](number_unsigned_t.md) - type for numbers (unsigned)
-- [**number_float_t**](number_float_t.md) - type for numbers (floating-point)
-- binary_t
+- [**object_comparator_t**](object_comparator_t.md) - comparator for objects
+- [**object_t**](object_t.md) - type for objects
+- [**string_t**](string_t.md) - type for strings
 
 ### Parser callback
 
@@ -137,10 +137,10 @@ Direct access to the stored value of a JSON value.
 
 - [**get**](get.md) - get a value
 - get_to - get a value
-- get_ptr - get a pointer value
-- get_ref - get a reference value
-- operator ValueType - get a value
-- get_binary - get a binary value
+- [**get_ptr**](get_ptr.md) - get a pointer value
+- [**get_ref**](get_ref.md) - get a reference value
+- [**operator ValueType**](operator_ValueType.md) - get a value
+- [**get_binary**](get_binary.md) - get a binary value
 
 ### Element access
 

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

+# basic_json::object_comparator_t
+
+```cpp
+// until C++14
+using object_comparator_t = std::less<StringType>;
+
+// since C++14
+using object_comparator_t = std::less<>;
+```
+
+The comparator used in [`object_t`](object_t.md).
+
+When C++14 is detected, a transparent com parator is used which, when combined with perfect forwarding on find() and
+count() calls, prevents unnecessary string construction.
+
+## Version history
+
+- Unknown.

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

@@ -35,14 +35,25 @@ With the default values for `ObjectType` (`std::map`), `StringType` (`std::strin
 (`std::allocator`), the default value for `object_t` is:
 
 ```cpp
+// until C++14
 std::map<
   std::string, // key_type
   basic_json, // value_type
   std::less<std::string>, // key_compare
   std::allocator<std::pair<const std::string, basic_json>> // allocator_type
 >
+
+// since C++14
+std::map<
+  std::string, // key_type
+  basic_json, // value_type
+  std::less<>, // key_compare
+  std::allocator<std::pair<const std::string, basic_json>> // allocator_type
+>
 ```
 
+See [`object_comparator_t`](object_comparator_t.md) for more information.
+
 #### Behavior
 
 The choice of `object_t` influences the behavior of the JSON class. With the default type, objects have the following

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

+# basic_json::operator ValueType
+
+```cpp
+template<typename ValueType>
+JSON_EXPLICIT operator ValueType() const;
+```
+
+Implicit type conversion between the JSON value and a compatible value. The call is realized by calling
+[`get()`](get.md). See [Notes](#notes) for the meaning of `JSON_EXPLICIT`.
+
+## Template parameters
+
+`ValueType`
+:   the value type to return
+
+## Return value
+
+copy of the JSON value, converted to `ValueType`
+
+## Exceptions
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws
+
+## Complexity
+
+Linear in the size of the JSON value.
+
+## Notes
+
+By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
+
+```cpp
+template<typename ValueType>
+operator ValueType() const;
+```
+
+If [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) is set to `0`,
+`JSON_EXPLICIT` is defined to `#!cpp explicit`:
+
+```cpp
+template<typename ValueType>
+explicit operator ValueType() const;
+```
+
+That is, implicit conversions can be switched off by defining
+[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
+
+## Example
+
+??? example
+
+    The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers, (2) A JSON array can be converted to a standard
+    `std::vector<short>`, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string, json>`.
+        
+    ```cpp
+    --8<-- "examples/operator__ValueType.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator__ValueType.output"
+    ```
+
+## Version history
+
+- Since version 1.0.0.
+- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) added
+  in version 3.9.0.

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

@@ -27,7 +27,7 @@ function.
 
 ## Exceptions
 
-1. The function can throw thw following exceptions:
+1. The function can throw the following exceptions:
     - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
       objects; example: `"cannot use update() with string"`
 2. The function can throw thw following exceptions:

doc/mkdocs/mkdocs.yml

@@ -81,6 +81,7 @@ nav:
         - api/basic_json/~basic_json.md
         - api/basic_json/begin.md
         - api/basic_json/binary.md
+        - api/basic_json/binary_t.md
         - api/basic_json/boolean_t.md
         - api/basic_json/cbegin.md
         - api/basic_json/cbor_tag_handler_t.md
@@ -108,6 +109,9 @@ nav:
         - api/basic_json/front.md
         - api/basic_json/get.md
         - api/basic_json/get_allocator.md
+        - api/basic_json/get_binary.md
+        - api/basic_json/get_ptr.md
+        - api/basic_json/get_ref.md
         - api/basic_json/input_format_t.md
         - api/basic_json/insert.md
         - api/basic_json/invalid_iterator.md
@@ -132,7 +136,9 @@ nav:
         - api/basic_json/number_integer_t.md
         - api/basic_json/number_unsigned_t.md
         - api/basic_json/object.md
+        - api/basic_json/object_comparator_t.md
         - api/basic_json/object_t.md
+        - api/basic_json/operator_ValueType.md
         - api/basic_json/operator_value_t.md
         - api/basic_json/operator[].md
         - api/basic_json/operator=.md