lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-28 12:02:00 +03:00
Code Activity

Consolidate documentation (#3071)

Browse Source 
* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables
This commit is contained in:
Niels Lohmann
2021-12-29 13:41:01 +01:00
committed by GitHub
parent 6d3115924c
commit 29cd970b94
392 changed files with 4827 additions and 12560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
doc/mkdocs/docs/api/basic_json/index.md
View File

@ -1,6 +1,6 @@
# basic_json
# <small>nlohmann::</small>basic_json
Defined in header `<json.hpp>`
<small>Defined in header `<nlohmann/json.hpp>`</small>
```cpp
template<
@ -18,41 +18,83 @@ template<
class basic_json;
```
## Template parameters
| Template parameter | Description | Derived type |
|----------------------|---------------------------------------------------------------------------|---------------------------------------------|
| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
| `AllocatorType` | type of the allocator to use | |
| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
## Specializations
- [**json**](../json.md) - default specialization
- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
## Template parameters
| Template parameter | Description | Derived type |
| -------------------- | ----------- | ------------ |
| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
| `AllocatorType` | type of the allocator to use | |
| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
## Iterator invalidation
Todo
## Requirements
The class satisfies the following concept requirements:
### Basic
- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default
constructed. The result will be a JSON null value.
- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed
from an rvalue argument.
- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be
copy-constructed from an lvalue expression.
- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value van be assigned from an
rvalue argument.
- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from
an lvalue expression.
- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed.
### Layout
- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have
[standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data
members are private and standard layout types, the class has no virtual functions or (virtual) base classes.
### Library-wide
- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
`==`, see [`operator==`](operator_eq.md).
- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
`<`, see [`operator<`](operator_le).
- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
any lvalue or rvalue of other compatible types, using unqualified function `swap`.
- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
`std::nullptr_t` objects which are used to model the `null` value.
### Container
- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and
provide iterator access.
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like
STL containers and provide reverse iterator access.
## Member types
- [**adl_serializer**](../adl_serializer.md) - the default serializer
- [**adl_serializer**](../adl_serializer) - the default serializer
- [**value_t**](value_t.md) - the JSON type enumeration
- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
- [**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_t**](../json_sax/index.md) - type for SAX events
### Exceptions
@ -65,21 +107,21 @@ 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) |
| 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` | reverse iterator, derived from `iterator` |
| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
| `iteration_proxy` | helper type for [`items`](items.md) function |
| `reverse_iterator` | reverse iterator, derived from `iterator` |
| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
| `iteration_proxy` | helper type for [`items`](items.md) function |
### JSON value data types
@ -103,9 +145,9 @@ Todo
- [(constructor)](basic_json.md)
- [(destructor)](~basic_json.md)
- [**operator=**](operator=.md) - copy assignment
- [**array**](array_t.md) (static) - explicitly create an array
- [**binary**](binary.md) (static) - explicitly create a binary array
- [**object**](object_t.md) (static) - explicitly create an object
- [**array**](array_t.md) (_static_) - explicitly create an array
- [**binary**](binary.md) (_static_) - explicitly create a binary array
- [**object**](object_t.md) (_static_) - explicitly create an object
### Object inspection
@ -183,7 +225,7 @@ Access to the JSON value
- [**erase**](erase.md) - remove elements
- [**insert**](insert.md) - inserts elements
- [**update**](update.md) - updates a JSON object from another object, overwriting existing keys
- swap - exchanges the values
- [**swap**](swap.md) - exchanges the values
### Lexicographical comparison operators
@ -197,13 +239,12 @@ Access to the JSON value
### Serialization / Dumping
- [**dump**](dump.md) - serialization
- to_string - user-defined to_string function for JSON values
### Deserialization / Parsing
- [**parse**](parse.md) (static) - deserialize from a compatible input
- [**accept**](accept.md) (static) - check if the input is valid JSON
- [**sax_parse**](sax_parse.md) (static) - generate SAX events
- [**parse**](parse.md) (_static_) - deserialize from a compatible input
- [**accept**](accept.md) (_static_) - check if the input is valid JSON
- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events
### JSON Pointer functions
@ -213,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
@ -226,19 +267,20 @@ Access to the JSON value
### Binary formats
- [**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_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
- [**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_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
- [**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_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
- [**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_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
## Non-member functions
- operator<<(std::ostream&) - serialize to stream
- operator>>(std::istream&) - deserialize from stream
- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
## Literals
@ -247,6 +289,29 @@ Access to the JSON value
## Helper classes
- std::hash<nlohmann::json\>
- std::less<nlohmann::value_t\>
- std::swap<nlohmann::json\>
- [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
- [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
## Example
??? example
The example shows how the library is used.
```cpp
--8<-- "examples/README.cpp"
```
Output:
```json
--8<-- "examples/README.output"
```
## See also
- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
## Version history
- Added in version 1.0.0.