:memo: add more API documentation
diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index 0c32335..e350baf 100644 --- a/doc/docset/docSet.sql +++ b/doc/docset/docSet.sql
@@ -12,6 +12,7 @@ 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 ('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_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/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');
diff --git a/doc/mkdocs/docs/api/basic_json/binary_t.md b/doc/mkdocs/docs/api/basic_json/binary_t.md new file mode 100644 index 0000000..2d6cd57 --- /dev/null +++ b/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.
diff --git a/doc/mkdocs/docs/api/basic_json/get.md b/doc/mkdocs/docs/api/basic_json/get.md index 7154109..4b17037 100644 --- a/doc/mkdocs/docs/api/basic_json/get.md +++ b/doc/mkdocs/docs/api/basic_json/get.md
@@ -10,6 +10,13 @@ // (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 @@ 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` : 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 @@ --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.
diff --git a/doc/mkdocs/docs/api/basic_json/get_binary.md b/doc/mkdocs/docs/api/basic_json/get_binary.md new file mode 100644 index 0000000..46d5b65 --- /dev/null +++ b/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.
diff --git a/doc/mkdocs/docs/api/basic_json/get_ptr.md b/doc/mkdocs/docs/api/basic_json/get_ptr.md new file mode 100644 index 0000000..80c2a19 --- /dev/null +++ b/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.
diff --git a/doc/mkdocs/docs/api/basic_json/get_ref.md b/doc/mkdocs/docs/api/basic_json/get_ref.md new file mode 100644 index 0000000..13b8e0f --- /dev/null +++ b/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.
diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 5825177..29989f2 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md
@@ -68,33 +68,33 @@ ### 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 @@ - [**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
diff --git a/doc/mkdocs/docs/api/basic_json/object_comparator_t.md b/doc/mkdocs/docs/api/basic_json/object_comparator_t.md new file mode 100644 index 0000000..8fb8656 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/object_comparator_t.md
@@ -0,0 +1,18 @@ +# 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.
diff --git a/doc/mkdocs/docs/api/basic_json/object_t.md b/doc/mkdocs/docs/api/basic_json/object_t.md index a3d2b7c..efc18c4 100644 --- a/doc/mkdocs/docs/api/basic_json/object_t.md +++ b/doc/mkdocs/docs/api/basic_json/object_t.md
@@ -35,14 +35,25 @@ (`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
diff --git a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md new file mode 100644 index 0000000..cfb5e64 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
@@ -0,0 +1,72 @@ +# 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.
diff --git a/doc/mkdocs/docs/api/basic_json/update.md b/doc/mkdocs/docs/api/basic_json/update.md index 9c23711..a1837c8 100644 --- a/doc/mkdocs/docs/api/basic_json/update.md +++ b/doc/mkdocs/docs/api/basic_json/update.md
@@ -27,7 +27,7 @@ ## 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:
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index caeb812..a1c4b1e 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml
@@ -81,6 +81,7 @@ - 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 @@ - 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 @@ - 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