Merge pull request nlohmann#24 from nlohmann/develop

📝 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

@@ -0,0 +1,67 @@
+# 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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,59 @@
+# 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

@@ -0,0 +1,64 @@
+# 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.