lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-31 10:24:23 +03:00
Code Activity

Clean up and document project files (#4560)

Browse Source
This commit is contained in:
Niels Lohmann
2025-01-17 06:53:35 +01:00
committed by GitHub
parent ad2ee18539
commit 26cfec34be
519 changed files with 3301 additions and 1332 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/mkdocs/Makefile
View File

@ -1,39 +1,35 @@
# serve the site locally
serve: prepare_files style_check
serve: style_check
venv/bin/mkdocs serve
serve_dirty: prepare_files style_check
serve_dirty: style_check
venv/bin/mkdocs serve --dirtyreload
build: prepare_files style_check
# This target is used in the CI (ci_test_build_documentation).
# This target is used by the docset Makefile.
build: style_check
venv/bin/mkdocs build
# create files that are not versioned inside the mkdocs folder (images, examples)
prepare_files: clean
mkdir docs/examples
cp -r ../json.gif docs/images
cp -r ../examples/*.cpp ../examples/*.output docs/examples
style_check:
@cd docs ; python3 ../scripts/check_structure.py
@cd docs ; ../venv/bin/python3 ../scripts/check_structure.py
# clean subfolders
clean:
rm -fr docs/images/json.gif docs/examples
# check the links in the documentation
link_check:
ENABLED_HTMLPROOFER=true venv/bin/mkdocs build
# publish site to GitHub pages (not working in GitHub Actions; need special action)
publish: prepare_files
publish:
venv/bin/mkdocs gh-deploy --clean --force
# install a Python virtual environment
# This target is used by the docset Makefile.
install_venv: requirements.txt
python3 -mvenv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt
# uninstall the virtual environment
uninstall_venv: clean
uninstall_venv:
rm -fr venv
update_requirements:

6
docs/mkdocs/docs/api/basic_json/accept.md
View File

@ -20,7 +20,7 @@ Checks whether the input is valid JSON.
The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
Unlike the [`parse`](parse.md) function, this function neither throws an exception in case of invalid JSON input
Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
(i.e., a parse error) nor creates diagnostic information.
## Template parameters
@ -29,7 +29,7 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
: A compatible input, for instance:
- an `std::istream` object
- a `FILE` pointer (throws if null)
- a `#!c FILE` pointer (throws if null)
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters (throws if null)
- a `std::string`
@ -66,7 +66,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer.
Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `#!c FILE*` or `#!c char*` pointer.
## Complexity

68
docs/mkdocs/docs/api/basic_json/end_pos.md Normal file
View File

@ -0,0 +1,68 @@
# <small>nlohmann::basic_json::</small>end_pos
```cpp
#if JSON_DIAGNOSTIC_POSITIONS
constexpr std::size_t end_pos() const noexcept;
#endif
```
Returns the position immediately following the last character of the JSON string from which the value was parsed from.
| JSON type | return value |
|-----------|-----------------------------------|
| object | position after the closing `}` |
| array | position after the closing `]` |
| string | position after the closing `"` |
| number | position after the last character |
| boolean | position after `e` |
| null | position after `l` |
## Return value
the position of the character _following_ the last character of the given value in the parsed JSON string, if the
value was created by the [`parse`](parse.md) function, or `std::string::npos` if the value was constructed otherwise
## Exception safety
No-throw guarantee: this member function never throws exceptions.
## Complexity
Constant.
## Notes
!!! note "Note"
The function is only available if macro [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) has
been defined to `#!cpp 1` before including the library header.
!!! warning "Invalidation"
The returned positions are only valid as long as the JSON value is not changed. The positions are *not* updated
when the JSON value is changed.
## Examples
??? example "Example"
```cpp
--8<-- "examples/diagnostic_positions.cpp"
```
Output:
```
--8<-- "examples/diagnostic_positions.output"
```
The output shows the start/end positions of all the objects and fields in the JSON string.
## See also
- [start_pos](start_pos.md) to access the start position
- [JSON_DIAGNOSTIC_POSITIONS](../macros/json_diagnostic_positions.md) for an overview of the diagnostic positions
## Version history
- Added in version 3.12.0.

9
docs/mkdocs/docs/api/basic_json/index.md
View File

@ -156,9 +156,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.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**](object.md) (_static_) - explicitly create an object
### Object inspection
@ -181,6 +181,11 @@ Functions to inspect the type of a JSON value.
- [**is_binary**](is_binary.md) - return whether value is a binary array
- [**is_discarded**](is_discarded.md) - return whether value is discarded
Optional functions to access the [diagnostic positions](../macros/json_diagnostic_positions.md).
- [**start_pos**](start_pos.md) - return the start position of the value
- [**end_pos**](end_pos.md) - return the one past the end position of the value
### Value access
Direct access to the stored value of a JSON value.

68
docs/mkdocs/docs/api/basic_json/start_pos.md Normal file
View File

@ -0,0 +1,68 @@
# <small>nlohmann::basic_json::</small>start_pos
```cpp
#if JSON_DIAGNOSTIC_POSITIONS
constexpr std::size_t start_pos() const noexcept;
#endif
```
Returns the position of the first character in the JSON string from which the value was parsed from.
| JSON type | return value |
|-----------|------------------------------------------------|
| object | position of the opening `{` |
| array | position of the opening `[` |
| string | position of the opening `"` |
| number | position of the first character |
| boolean | position of `t` for `true` and `f` for `false` |
| null | position of `n` |
## Return value
the position of the first character of the value in the parsed JSON string, if the value was created by the
[`parse`](parse.md) function, or `std::string::npos` if the value was constructed otherwise
## Exception safety
No-throw guarantee: this member function never throws exceptions.
## Complexity
Constant.
## Notes
!!! note "Note"
The function is only available if macro [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) has
been defined to `#!cpp 1` before including the library header.
!!! warning "Invalidation"
The returned positions are only valid as long as the JSON value is not changed. The positions are *not* updated
when the JSON value is changed.
## Examples
??? example "Example"
```cpp
--8<-- "examples/diagnostic_positions.cpp"
```
Output:
```
--8<-- "examples/diagnostic_positions.output"
```
The output shows the start/end positions of all the objects and fields in the JSON string.
## See also
- [end_pos](end_pos.md) to access the end position
- [JSON_DIAGNOSTIC_POSITIONS](../macros/json_diagnostic_positions.md) for an overview of the diagnostic positions
## Version history
- Added in version 3.12.0.

52
docs/mkdocs/docs/api/macros/index.md
View File

@ -11,6 +11,7 @@ header. See also the [macro overview page](../../features/macros.md).
- [**JSON_CATCH_USER(exception)**<br>**JSON_THROW_USER(exception)**<br>**JSON_TRY_USER**](json_throw_user.md) - control exceptions
- [**JSON_DIAGNOSTICS**](json_diagnostics.md) - control extended diagnostics
- [**JSON_DIAGNOSTIC_POSITIONS**](json_diagnostic_positions.md) - access positions of elements
- [**JSON_NOEXCEPTION**](json_noexception.md) - switch off exceptions
## Language support
@ -49,27 +50,34 @@ header. See also the [macro overview page](../../features/macros.md).
## Serialization/deserialization macros
- Enum: [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md)
- Class/struct:
- Do you need to serialize private variables?
- Yes? Do you only need serialization?
- Yes? `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE`
- No? Allow deserialization of JSON values with missing values?
- Yes? `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT`
- No? `NLOHMANN_DEFINE_TYPE_INTRUSIVE`
- No? Do you only need serialization?
- Yes? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE`
- No? Allow deserialization of JSON values with missing values?
- Yes? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`
- No? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`
### Enums
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**
<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, member...)**][DefInt]
\- serialization/deserialization of types _with_ access to private variables
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**
<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE(type, member...)**][DefNonInt]
\- serialization/deserialization of types _without_ access to private variables
- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum types
- [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md) - serialize/deserialize an enum
[DefInt]: nlohmann_define_type_intrusive.md
[DefNonInt]: nlohmann_define_type_non_intrusive.md
### Classes and structs
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE**](nlohmann_define_type_intrusive.md) - serialize/deserialize a non-derived class
with private members
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT**](nlohmann_define_type_intrusive.md) - serialize/deserialize a
non-derived class with private members; uses default values
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE**](nlohmann_define_type_intrusive.md) - serialize a non-derived class
with private members
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE**](nlohmann_define_type_non_intrusive.md) - serialize/deserialize a non-derived
class
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT**](nlohmann_define_type_non_intrusive.md) - serialize/deserialize a
non-derived class; uses default values
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE**](nlohmann_define_type_non_intrusive.md) - serialize a
non-derived class
- [**NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE**](nlohmann_define_derived_type.md) - serialize/deserialize a derived class
with private members
- [**NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT**](nlohmann_define_derived_type.md) - serialize/deserialize a
derived class with private members; uses default values
- [**NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE**](nlohmann_define_derived_type.md) - serialize a derived
class with private members
- [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE**](nlohmann_define_derived_type.md) - serialize/deserialize a derived
class
- [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT**](nlohmann_define_derived_type.md) - serialize/deserialize
a derived class; uses default values
- [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE**](nlohmann_define_derived_type.md) - serialize a derived
class

55
docs/mkdocs/docs/api/macros/json_diagnostic_positions.md
View File

@ -6,22 +6,34 @@
This macro enables position diagnostics for generated JSON objects.
When enabled, two new properties: `start_pos()` and `end_pos()` are added to `nlohmann::basic_json` objects and fields. `start_pos()` returns the start
position of that JSON object/field in the original string the object was parsed from. Likewise, `end_pos()` returns the end position of that JSON
object/field in the original string the object was parsed from.
When enabled, two new member functions [`start_pos()`](../basic_json/start_pos.md) and
[`end_pos()`](../basic_json/end_pos.md) are added to [`basic_json`](../basic_json/index.md) values. If the value was
created by calling the[`parse`](../basic_json/parse.md) function, then these functions allow to query the byte positions
of the value in the input it was parsed from. In case the value was constructed by other means, `std::string::npos` is
returned.
`start_pos()` returns the first character of a given element in the original JSON string, while `end_pos()` returns the character following the last
character. For objects and arrays, the first and last characters correspond to the opening or closing braces/brackets, respectively. For fields, the first
and last character represent the opening and closing quotes or the first and last character of the field's numerical or predefined value
(true/false/null), respectively.
[`start_pos()`](../basic_json/start_pos.md) returns the position of the first character of a given value in the original
JSON string, while [`end_pos()`](../basic_json/end_pos.md) returns the position of the character _following_ the last
character. For objects and arrays, the first and last characters correspond to the opening or closing braces/brackets,
respectively. For primitive values, the first and last character represent the opening and closing quotes (strings) or
the first and last character of the field's numerical or predefined value (`true`, `false`, `null`), respectively.
Given the above, `end_pos() - start_pos()` for an object or field provides the length of the string representation for that object or field, including the
opening or closing braces, brackets, or quotes.
| JSON type | return value [`start_pos()`](../basic_json/start_pos.md) | return value [`end_pos()`](../basic_json/end_pos.md) |
|-----------|----------------------------------------------------------|------------------------------------------------------|
| object | position of the opening `{` | position after the closing `}` |
| array | position of the opening `[` | position after the closing `]` |
| string | position of the opening `"` | position after the closing `"` |
| number | position of the first character | position after the last character |
| boolean | position of `t` for `true` and `f` for `false` | position after `e` |
| null | position of `n` | position after `l` |
`start_pos()` and `end_pos()` are only set if the JSON object was parsed using `parse()`. For all other cases, `std::string::npos` will be returned.
Given the above, [`end_pos()`](../basic_json/end_pos.md)` - `[`start_pos()`](../basic_json/start_pos.md) for a JSON
value provides the length of the parsed JSON string for that value, including the opening or closing braces, brackets,
or quotes.
Note that enabling this macro increases the size of every JSON value by two `std::size_t` fields and adds
slight runtime overhead.
Note that enabling this macro increases the size of every JSON value by two `std::size_t` fields and adds slight runtime
overhead to parsing, copying JSON value objects, and the generation of error messages for exceptions. It also causes
these values to be reported in those error messages.
## Default definition
@ -35,15 +47,27 @@ When the macro is not defined, the library will define it to its default value.
## Notes
!!! hint "CMake option"
!!! note "CMake option"
Diagnostic messages can also be controlled with the CMake option
Diagnostic positions can also be controlled with the CMake option
[`JSON_Diagnostic_Positions`](../../integration/cmake.md#json_diagnostic_positions) (`OFF` by default)
which defines `JSON_DIAGNOSTIC_POSITIONS` accordingly.
!!! note "Availability"
Diagnostic positions are only available if the value was created by the [`parse`](../basic_json/parse.md) function.
The [`sax_parse`](../basic_json/sax_parse.md) function or all other means to create a JSON value **do not** set the
diagnostic positions and [`start_pos()`](../basic_json/start_pos.md) and [`end_pos()`](../basic_json/end_pos.md)
will only return `std::string::npos` for these values.
!!! warning "Invalidation"
The returned positions are only valid as long as the JSON value is not changed. The positions are *not* updated
when the JSON value is changed.
## Examples
??? example "Example 1: retrieving positions"
??? example "Example: retrieving positions"
```cpp
--8<-- "examples/diagnostic_positions.cpp"
@ -59,3 +83,4 @@ When the macro is not defined, the library will define it to its default value.
## Version history
- Added in version 3.12.0.

88
docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md
View File

@ -3,13 +3,19 @@
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE</h1>
```cpp
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...) // (1)
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT(type, base_type, member...) // (2)
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, base_type, member...) // (3)
// (1)
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...)
// (2)
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)
// (3)
#define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, base_type, member...)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(type, base_type, member...) // (4)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, base_type, member...) // (5)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE(type, base_type, member...) // (6)
// (4)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(type, base_type, member...)
// (5)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)
// (6)
#define NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE(type, base_type, member...)
```
These macros can be used to simplify the serialization/deserialization of derived types if you want to use a JSON
@ -25,12 +31,23 @@ The first parameter is the name of the derived class/struct,
the second parameter is the name of the base class/struct and all remaining parameters name the members.
The base type **must** be already serializable/deserializable.
- Macros 1 and 3 will use [`at`](../basic_json/at.md) during deserialization and will throw
- Macros 1 and 4 will use [`at`](../basic_json/at.md) during deserialization and will throw
[`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
- Macros 2 and 4 will use [`value`](../basic_json/value.md) during deserialization and fall back to the default value for the
- Macros 2 and 5 will use [`value`](../basic_json/value.md) during deserialization and fall back to the default value for the
respective type of the member variable if a key in the JSON object is missing. The generated `from_json()` function
default constructs an object and uses its values as the defaults when calling the `value` function.
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------|
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE** |
## Parameters
`type` (in)
@ -64,7 +81,7 @@ Macros 3 and 6 add one function to the namespace which take care of the serializ
void to_json(nlohmann::json&, const type&);
```
In first two cases cases they call the `to_json`/`from_json` functions of the base type
In first two cases, they call the `to_json`/`from_json` functions of the base type
before serializing/deserializing the members of the derived type:
```cpp
@ -82,7 +99,7 @@ void from_json(const nlohmann::json& j, B& b) {
}
```
In the third case only `to_json` will be called:
In the third case, only `to_json` will be called:
```cpp
class A { /* ... */ };
@ -98,40 +115,55 @@ void to_json(nlohmann::json& j, const B& b) {
!!! info "Prerequisites"
- Macros 1, 2 and 3 have the same prerequisites of NLOHMANN_DEFINE_TYPE_INTRUSIVE.
- Macros 4, 5 and 6 have the same prerequisites of NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE.
- Macros 1, 2, and 3 have the same prerequisites of [NLOHMANN_DEFINE_TYPE_INTRUSIVE](nlohmann_define_type_intrusive.md).
- Macros 4, 5, and 6 have the same prerequisites of [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE](nlohmann_define_type_non_intrusive.md).
- Serialization/deserialization of base types must be defined.
!!! warning "Implementation limits"
- See Implementation limits for NLOHMANN_DEFINE_TYPE_INTRUSIVE and NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE.
See Implementation limits for [NLOHMANN_DEFINE_TYPE_INTRUSIVE](nlohmann_define_type_intrusive.md) and
[NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE](nlohmann_define_type_non_intrusive.md), respectively.
## Examples
Example of `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE` usage:
??? example "NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE"
```cpp
class A {
double Aa;
double Ab;
NLOHMANN_DEFINE_TYPE_INTRUSIVE(A, Aa, Ab)
};
Consider the following complete example:
class B : public A {
int Ba;
int Bb;
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(B, A, Ba, Bb)
};
```
```cpp hl_lines="28"
--8<-- "examples/nlohmann_define_derived_type_intrusive_macro.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_define_derived_type_intrusive_macro.output"
```
Notes:
- `A` and `B` are default-constructible. This is a requirement for using the macro.
- `A` has private members and is not a derived class. Hence, macro `NLOHMANN_DEFINE_TYPE_INTRUSIVE` is used.
- As `B` is a derived class, `NLOHMANN_DEFINE_TYPE_INTRUSIVE` is not applicable, but
`NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE` must be used.
- The macro `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE` is used _inside_ the class use as
`NLOHMANN_DEFINE_TYPE_INTRUSIVE`.
## See also
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_intrusive.md)
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT /
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_intrusive.md)
for similar macros that can be defined _inside_ a non-derived type.
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_non_intrusive.md)
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT /
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_non_intrusive.md)
for similar macros that can be defined _outside_ a non-derived type.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history
1. Added in version 3.11.x.
2. Added in version 3.11.x.
3. Added in version 3.11.x.
4. Added in version 3.11.x.
5. Added in version 3.11.x.
6. Added in version 3.11.x.

18
docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md
View File

@ -19,6 +19,14 @@ parameter is the name of the class/struct, and all remaining parameters name the
default constructs an object and uses its values as the defaults when calling the `value` function.
3. Only defines the serialization. Useful in cases when the type does not have a default constructor and only serialization in required.
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------|
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_INTRUSIVE** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE** |
## Parameters
`type` (in)
@ -145,12 +153,18 @@ See examples below for the concrete generated code.
## See also
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE{_WITH_DEFAULT, _ONLY_SERIALIZE}](nlohmann_define_type_non_intrusive.md)
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_non_intrusive.md)
for a similar macro that can be defined _outside_ the type.
- [NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE,
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_derived_type.md) for similar macros for
derived types
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history
1. Added in version 3.9.0.
2. Added in version 3.11.0.
3. Added in version TODO.
3. Added in version 3.11.3.

18
docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md
View File

@ -19,6 +19,14 @@ parameter is the name of the class/struct, and all remaining parameters name the
default constructs an object and uses its values as the defaults when calling the `value` function.
3. Only defines the serialization. Useful in cases when the type does not have a default constructor and only serialization in required.
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------|
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE** |
## Parameters
`type` (in)
@ -146,12 +154,18 @@ See examples below for the concrete generated code.
## See also
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE{_WITH_DEFAULT, _ONLY_SERIALIZE}](nlohmann_define_type_intrusive.md)
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_intrusive.md)
for a similar macro that can be defined _inside_ the type.
- [NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE,
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT,
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_derived_type.md) for similar macros for
derived types
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history
1. Added in version 3.9.0.
2. Added in version 3.11.0.
3. Added in version TODO.
3. Added in version 3.11.3.

1
docs/mkdocs/docs/community/code_of_conduct.md Normal file
View File

@ -0,0 +1 @@
--8<-- "../../../.github/CODE_OF_CONDUCT.md"

1
docs/mkdocs/docs/community/contribution_guidelines.md Normal file
View File

@ -0,0 +1 @@
--8<-- "../../../.github/CONTRIBUTING.md"

122
docs/mkdocs/docs/community/governance.md Normal file
View File

@ -0,0 +1,122 @@
# Governance
The governance model for the JSON for Modern C++ project is a **Benevolent Dictator for Life (BDFL)** structure. As the
sole maintainer, [Niels Lohmann](https://github.com/nlohmann) is responsible for all key aspects of the project. The
project governance may evolve as the project grows, but any changes will be documented here and communicated to
contributors.
## Overview
This project is led by a benevolent dictator, [Niels Lohmann](https://github.com/nlohmann), and managed by the
community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general
strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the
benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in
a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active
engagement and contribution.
## Roles and responsibilities
### Benevolent dictator (project lead)
Typically, the benevolent dictator, or project lead, is self-appointed. However, because the community always has the
ability to fork, this person is fully answerable to the community. The project lead’s role is a difficult one: they set
the strategic objectives of the project and communicate these clearly to the community. They also have to understand the
community as a whole and strive to satisfy as many conflicting needs as possible, while ensuring that the project
survives in the long term.
In many ways, the role of the benevolent dictator is less about dictatorship and more about diplomacy. The key is to
ensure that, as the project expands, the right people are given influence over it and the community rallies behind the
vision of the project lead. The lead’s job is then to ensure that the committers (see below) make the right decisions on
behalf of the project. Generally speaking, as long as the committers are aligned with the project’s strategy, the
project lead will allow them to proceed as they desire.
### Committers
Committers are contributors who have made several valuable contributions to the project and are now relied upon to both
write code directly to the repository and screen the contributions of others. In many cases they are programmers but it
is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the
project, and will bring a level of expertise and understanding that earns them the respect of the community and the
project lead. The role of committer is not an official one, it is simply a position that influential members of the
community will find themselves in as the project lead looks to them for guidance and support.
Committers have no authority over the overall direction of the project. However, they do have the ear of the project
lead. It is a committer’s job to ensure that the lead is aware of the community’s needs and collective objectives, and
to help develop or elicit appropriate contributions to the project. Often, committers are given informal control over
their specific areas of responsibility, and are assigned rights to directly modify certain areas of the source code.
That is, although committers do not have explicit decision-making authority, they will often find that their actions are
synonymous with the decisions made by the lead.
### Contributors
Contributors are community members who either have no desire to become committers, or have not yet been given the
opportunity by the benevolent dictator. They make valuable contributions, such as those outlined in the list below, but
generally do not have the authority to make direct changes to the project code. Contributors engage with the project
through communication tools, such as email lists, and via reports and patches attached to issues in the issue tracker,
as detailed in our community tools document.
Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements
and no selection process. To become a contributor, a community member simply has to perform one or more actions that are
beneficial to the project.
Some contributors will already be engaging with the project as users, but will also find themselves doing one or more of
the following:
- supporting new users (current users often provide the most effective new user support)
- reporting bugs
- identifying requirements
- supplying graphics and web design
- programming
- assisting with project infrastructure
- writing documentation
- fixing bugs
- adding features
As contributors gain experience and familiarity with the project, they may find that the project lead starts relying on
them more and more. When this begins to happen, they gradually adopt the role of committer, as described above.
### Users
Users are community members who have a need for the project. They are the most important members of the community:
without them, the project would have no purpose. Anyone can be a user; there are no specific requirements.
Users should be encouraged to participate in the life of the project and the community as much as possible. User
contributions enable the project team to ensure that they are satisfying the needs of those users. Common user
activities include (but are not limited to):
- evangelising about the project
- informing developers of project strengths and weaknesses from a new user’s perspective
- providing moral support (a ‘thank you’ goes a long way)
- providing financial support
Users who continue to engage with the project and its community will often find themselves becoming more and more
involved. Such users may then go on to become contributors, as described above.
## Support
All participants in the community are encouraged to provide support for new users within the project management
infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that
all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring
guaranteed response times or results should therefore seek to purchase a support contract from a vendor. (Of course,
that vendor should be an active member of the community.) However, for those willing to engage with the project on its
own terms, and willing to help support other users, the community support channels are ideal.
## Contribution Process
Anyone can contribute to the project, regardless of their skills, as there are many ways to contribute. For instance, a
contributor might be active on the project mailing list and issue tracker, or might supply patches. The various ways of
contributing are described in more detail in our roles in open source document.
The developer mailing list is the most appropriate place for a contributor to ask for help when making their first
contribution.
## Decision-Making Process
The benevolent dictatorship model does not need a formal conflict resolution process, since the project lead’s word is
final. If the community chooses to question the wisdom of the actions of a committer, the project lead can review their
decisions by checking the email archives, and either uphold or reverse them.
---
!!! quote "Source"
The text was taken from http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel.

7
docs/mkdocs/docs/community/index.md Normal file
View File

@ -0,0 +1,7 @@
# Community
- [Code of Conduct](code_of_conduct.md) - the rules and norms of this project
- [Contribution Guidelines](contribution_guidelines.md) - guidelines how to contribute to this project
- [Governance](governance.md) - the governance model of this project
- [Quality Assurance](quality_assurance.md) - how quality of this project is assured
- [Security Policy](security_policy.md) - the security policy of the project

210
docs/mkdocs/docs/community/quality_assurance.md Normal file
View File

@ -0,0 +1,210 @@
# Quality assurance
Ensuring quality is paramount for this project, particularly because [numerous other projects](../home/customers.md)
depend on it. Each commit to the library undergoes rigorous checks against the following requirements, and any
violations will result in a failed build.
## C++ language compliance and compiler compatibility
!!! success "Requirement: Compiler support"
Any compiler with complete C++11 support can compile the library without warnings.
- [x] The library is compiled library with 50+ different C++ compilers with different operating systems and platforms,
including the oldest versions known to compile the library.
??? abstract "Compilers used in continuous integration"
| Compiler | Architecture | Operating System | CI |
|----------------------------------------------|--------------|--------------------------|-----------|
| AppleClang 14.0.0.14000029; Xcode 14.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 14.0.0.14000029; Xcode 14.2 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 14.0.3.14030022; Xcode 14.3.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 15.0.0.15000040; Xcode 15.0.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 15.0.0.15000100; Xcode 15.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 15.0.0.15000100; Xcode 15.2 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
| AppleClang 15.0.0.15000309; Xcode 15.3 | arm64 | macOS 14.7.2 (Sonoma) | GitHub |
| AppleClang 15.0.0.15000309; Xcode 15.4 | arm64 | macOS 14.7.2 (Sonoma) | GitHub |
| AppleClang 16.0.0.16000026; Xcode 16 | arm64 | macOS 15.2 (Sequoia) | GitHub |
| AppleClang 16.0.0.16000026; Xcode 16.1 | arm64 | macOS 15.2 (Sequoia) | GitHub |
| AppleClang 16.0.0.16000026; Xcode 16.2 | arm64 | macOS 15.2 (Sequoia) | GitHub |
| Clang 3.5.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 3.6.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 3.7.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 3.8.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 3.9.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 4.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 5.0.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 6.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 7.1.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 8.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 9.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 10.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 11.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 11.1.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 12.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 12.0.0 with MSVC-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 12.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 13.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 13.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 14.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 14.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 15.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
| Clang 15.0.7 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 16.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 17.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 18.1.8 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 19.1.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| Clang 20.0.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 4.8.5 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 4.9.3 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 5.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 6.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 7.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 8.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 9.3.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 9.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 9.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 10.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 11.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 11.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 12.2.0 (MinGW-W64 i686-ucrt-posix-dwarf) | x86_64 | Windows 10 (Build 17763) | GitHub |
| GNU 12.2.0 (MinGW-W64 x86_64-ucrt-posix-seh) | x86_64 | Windows 10 (Build 17763) | GitHub |
| GNU 12.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 13.3.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 14.2.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
| GNU 14.2.0 | arm64 | Linux 6.1.100 | Cirrus CI |
| MSVC 19.0.24241.7 | x86 | Windows 8.1 | AppVeyor |
| MSVC 19.16.27035.0 | x86 | Windows-10 (Build 14393) | AppVeyor |
| MSVC 19.29.30157.0 | x86 | Windows 10 (Build 17763) | GitHub |
| MSVC 19.29.30157.0 | x86_64 | Windows 10 (Build 17763) | GitHub |
| MSVC 19.29.30157.0 | x86 | Windows-10 (Build 17763) | AppVeyor |
| MSVC 19.42.34435.0 | x86 | Windows 10 (Build 20348) | GitHub |
| MSVC 19.42.34435.0 | x86_64 | Windows 10 (Build 20348) | GitHub |
- [x] The library is compiled with all C++ language revisions (C++11, C++14, C++17, C++20, C++23, and C++26) to detect
and fix language deprecations early.
- [x] The library is checked for compiler warnings:
- On Clang, `-Weverything` is used with 7 exceptions.
??? abstract "Clang warnings"
```cmake
--8<-- "../../../cmake/clang_flags.cmake"
```
- On GCC, 300+ warnings are enabled with 8 exceptions.
??? abstract "GCC warnings"
```cmake
--8<-- "../../../cmake/gcc_flags.cmake"
```
## C++ standard library compliance
!!! success "Requirement: No prerequisites"
The library has no prerequisites other than the Standard Template Library (STL).
- [x] The library compiled and tested with both [libc++](https://libcxx.llvm.org) and
[libstdc++](https://gcc.gnu.org/onlinedocs/libstdc++/) to detect subtle differences or incompatibilities.
- [x] The code checked with [Include What You Use (IWYU)](https://include-what-you-use.org) that all required standard
headers are included.
- [x] On Windows, the library is compiled with `<Windows.h>` being included to detect and avoid common bugs.
- [x] The library is compiled with exceptions disabled to support alternative means of error handling.
## Stable public API
!!! success "Requirement: Stable public API"
Any change to the library does not break the public API.
- [x] All public API functions are tested with a variety of arguments.
- [x] The library is compiled and tested with different template arguments for number, string, array, and object types.
- [x] All lines of the code base are covered by unit tests.
- [x] Every exception of the library is thrown in the test suite and the error messages and exception ids are checked.
!!! success "Requirement: Complete documentation"
The public API is extensively documented.
- [x] Every public API function has a dedicated page in the
[API reference documentation](https://json.nlohmann.me/api/basic_json/) with a self-contained code example.
- [x] All examples in the documentation are tested and changes in their output is treated as an error.
## Robust input processing
!!! success "Requirement: Standards compliance"
The library is compliant to JSON as defined in [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259).
- [x] The lexer is tested with all valid Unicode code points and all prefixes of all invalid Unicode code points.
- [x] The parser is tested against extensive correctness suites for JSON compliance.
- [x] In addition, the library is continuously fuzz-tested at [OSS-Fuzz](https://google.github.io/oss-fuzz/) where the
library is checked against billions of inputs.
## Static analysis
!!! success "Requirement: State-of-the-art code analysis"
The code is checked with state-of-the-art static code analysis tools.
- [x] The code is checked with the latest [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/).
??? abstract "Clang-Tidy configuration (.clang-tidy)"
```ini
--8<-- "../../../.clang-tidy"
```
- [x] The code is checked with the latest [Cppcheck](https://cppcheck.sourceforge.io) with all warnings enabled.
- [x] The code is checked with the latest [Clang Static Analyzer](https://clang-analyzer.llvm.org) with 89 enabled
rules.
- [x] The code is checked with [Infer](https://fbinfer.com).
- [x] The code is checked with [Codacy](https://app.codacy.com/gh/nlohmann/json/dashboard).
## Dynamic analysis
!!! success "Requirement: Correctness"
The library is checked for memory correctness and absence of undefined behavior.
- [x] The test suite is executed with enabled [runtime assertions](https://json.nlohmann.me/features/assertions/) to
check invariants and preconditions of functions to detect undefined behavior.
- [x] The test suite is executed with [Valgrind](https://valgrind.org) (Memcheck) to detect memory leaks.
- [x] The test suite is executed with [Sanitizers](https://github.com/google/sanitizers) (address sanitizer, undefined
behavior sanitizer, integer overflow detection, nullability violations).
## Style check
!!! success "Requirement: Common code style"
A common code style is used throughout all code files of the library.
- [x] The code is formatted with [Artistic Style](https://astyle.sourceforge.net) (astyle) against a style configuration
that is also enforced in the CI.
??? abstract "Astyle configuration (tools/astyle/.astylerc)"
```ini
--8<-- "../../../tools/astyle/.astylerc"
```
- [x] The code style is checked with [cpplint](https://github.com/cpplint/cpplint) with 61 enabled rules.
## Simple integration
!!! success "Requirement: Single header"
The library can be used by adding a single header to a C++ project.
- [x] An amalgamation script is used to check if the source code is exposed as self-contained single-header file.
- [x] The test suite is checked against the amalgamated source file as well as the individual source file.
!!! success "Requirement: CMake as primary development tool"
All library functions are exposed and usable by CMake.
- [x] All library options are exposed as [CMake options](https://json.nlohmann.me/integration/cmake/) and tested.
- [x] The library is tested against the earliest supported CMake version.

1
docs/mkdocs/docs/community/security_policy.md Normal file
View File

@ -0,0 +1 @@
--8<-- "../../../.github/SECURITY.md"

6
docs/mkdocs/docs/css/custom.css
View File

@ -1,4 +1,4 @@
/* disable ligatures in code and preformatted blocks */
code, pre {
font-variant-ligatures: none;
/* enable ligatures in code and preformatted blocks */
.md-typeset code, .md-typeset pre {
font-variant-ligatures: common-ligatures;
}

39
docs/mkdocs/docs/examples/README.cpp Normal file
View File

@ -0,0 +1,39 @@
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object
json j =
{
{"pi", 3.141},
{"happy", true},
{"name", "Niels"},
{"nothing", nullptr},
{
"answer", {
{"everything", 42}
}
},
{"list", {1, 0, 2}},
{
"object", {
{"currency", "USD"},
{"value", 42.99}
}
}
};
// add new values
j["new"]["key"]["value"] = {"another", "list"};
// count elements
auto s = j.size();
j["size"] = s;
// pretty print with indent of 4 spaces
std::cout << std::setw(4) << j << '\n';
}

27
docs/mkdocs/docs/examples/README.output Normal file
View File

@ -0,0 +1,27 @@
{
"answer": {
"everything": 42
},
"happy": true,
"list": [
1,
0,
2
],
"name": "Niels",
"new": {
"key": {
"value": [
"another",
"list"
]
}
},
"nothing": null,
"object": {
"currency": "USD",
"value": 42.99
},
"pi": 3.141,
"size": 8
}

26
docs/mkdocs/docs/examples/accept__string.cpp Normal file
View File

@ -0,0 +1,26 @@
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// a valid JSON text
auto valid_text = R"(
{
"numbers": [1, 2, 3]
}
)";
// an invalid JSON text
auto invalid_text = R"(
{
"strings": ["extra", "comma", ]
}
)";
std::cout << std::boolalpha
<< json::accept(valid_text) << ' '
<< json::accept(invalid_text) << '\n';
}

1
docs/mkdocs/docs/examples/accept__string.output Normal file
View File

@ -0,0 +1 @@
true false

19
docs/mkdocs/docs/examples/array.cpp Normal file
View File

@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON arrays
json j_no_init_list = json::array();
json j_empty_init_list = json::array({});
json j_nonempty_init_list = json::array({1, 2, 3, 4});
json j_list_of_pairs = json::array({ {"one", 1}, {"two", 2} });
// serialize the JSON arrays
std::cout << j_no_init_list << '\n';
std::cout << j_empty_init_list << '\n';
std::cout << j_nonempty_init_list << '\n';
std::cout << j_list_of_pairs << '\n';
}

4
docs/mkdocs/docs/examples/array.output Normal file
View File

@ -0,0 +1,4 @@
[]
[]
[1,2,3,4]
[["one",1],["two",2]]

10
docs/mkdocs/docs/examples/array_t.cpp Normal file
View File

@ -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;
}

1
docs/mkdocs/docs/examples/array_t.output Normal file
View File

@ -0,0 +1 @@
true

103
docs/mkdocs/docs/examples/at__json_pointer.cpp Normal file
View File

@ -0,0 +1,103 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON value
json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j.at("/number"_json_pointer) << '\n';
// output element with JSON pointer "/string"
std::cout << j.at("/string"_json_pointer) << '\n';
// output element with JSON pointer "/array"
std::cout << j.at("/array"_json_pointer) << '\n';
// output element with JSON pointer "/array/1"
std::cout << j.at("/array/1"_json_pointer) << '\n';
// writing access
// change the string
j.at("/string"_json_pointer) = "bar";
// output the changed string
std::cout << j["string"] << '\n';
// change an array element
j.at("/array/1"_json_pointer) = 21;
// output the changed array
std::cout << j["array"] << '\n';
// out_of_range.106
try
{
// try to use an array index with leading '0'
json::reference ref = j.at("/array/01"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.109
try
{
// try to use an array index that is not a number
json::reference ref = j.at("/array/one"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::reference ref = j.at("/array/4"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::reference ref = j.at("/array/-"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::reference ref = j.at("/number/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

12
docs/mkdocs/docs/examples/at__json_pointer.output Normal file
View File

@ -0,0 +1,12 @@
1
"foo"
[1,2]
2
"bar"
[1,21]
[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
[json.exception.parse_error.109] parse error: array index 'one' is not a number
[json.exception.out_of_range.401] array index 4 is out of range
[json.exception.out_of_range.402] array index '-' (2) is out of range
[json.exception.out_of_range.403] key 'foo' not found
[json.exception.out_of_range.404] unresolved reference token 'foo'

80
docs/mkdocs/docs/examples/at__json_pointer_const.cpp Normal file
View File

@ -0,0 +1,80 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON value
const json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j.at("/number"_json_pointer) << '\n';
// output element with JSON pointer "/string"
std::cout << j.at("/string"_json_pointer) << '\n';
// output element with JSON pointer "/array"
std::cout << j.at("/array"_json_pointer) << '\n';
// output element with JSON pointer "/array/1"
std::cout << j.at("/array/1"_json_pointer) << '\n';
// out_of_range.109
try
{
// try to use an array index that is not a number
json::const_reference ref = j.at("/array/one"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::const_reference ref = j.at("/array/4"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::const_reference ref = j.at("/array/-"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::const_reference ref = j.at("/number/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

9
docs/mkdocs/docs/examples/at__json_pointer_const.output Normal file
View File

@ -0,0 +1,9 @@
1
"foo"
[1,2]
2
[json.exception.parse_error.109] parse error: array index 'one' is not a number
[json.exception.out_of_range.401] array index 4 is out of range
[json.exception.out_of_range.402] array index '-' (2) is out of range
[json.exception.out_of_range.403] key 'foo' not found
[json.exception.out_of_range.404] unresolved reference token 'foo'

49
docs/mkdocs/docs/examples/at__keytype.c++17.cpp Normal file
View File

@ -0,0 +1,49 @@
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create JSON object
json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly" using string_view
std::cout << object.at("the ugly"sv) << '\n';
// change element with key "the bad" using string_view
object.at("the bad"sv) = "il cattivo";
// output changed array
std::cout << object << '\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
json str = "I am a string";
str.at("the good"sv) = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key using string_view
object.at("the fast"sv) = "il rapido";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

4
docs/mkdocs/docs/examples/at__keytype.c++17.output Normal file
View File

@ -0,0 +1,4 @@
"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.403] key 'the fast' not found

43
docs/mkdocs/docs/examples/at__keytype_const.c++17.cpp Normal file
View File

@ -0,0 +1,43 @@
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create JSON object
const json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly" using string_view
std::cout << object.at("the ugly"sv) << '\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
const json str = "I am a string";
std::cout << str.at("the good"sv) << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key using string_view
std::cout << object.at("the fast"sv) << '\n';
}
catch (const json::out_of_range& e)
{
std::cout << "out of range" << '\n';
}
}

3
docs/mkdocs/docs/examples/at__keytype_const.c++17.output Normal file
View File

@ -0,0 +1,3 @@
"il brutto"
[json.exception.type_error.304] cannot use at() with string
out of range

47
docs/mkdocs/docs/examples/at__object_t_key_type.cpp Normal file
View File

@ -0,0 +1,47 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON object
json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly"
std::cout << object.at("the ugly") << '\n';
// change element with key "the bad"
object.at("the bad") = "il cattivo";
// output changed array
std::cout << object << '\n';
// exception type_error.304
try
{
// use at() on a non-object type
json str = "I am a string";
str.at("the good") = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key
object.at("the fast") = "il rapido";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

4
docs/mkdocs/docs/examples/at__object_t_key_type.output Normal file
View File

@ -0,0 +1,4 @@
"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.403] key 'the fast' not found

41
docs/mkdocs/docs/examples/at__object_t_key_type_const.cpp Normal file
View File

@ -0,0 +1,41 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON object
const json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly"
std::cout << object.at("the ugly") << '\n';
// exception type_error.304
try
{
// use at() on a non-object type
const json str = "I am a string";
std::cout << str.at("the good") << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key
std::cout << object.at("the fast") << '\n';
}
catch (const json::out_of_range)
{
std::cout << "out of range" << '\n';
}
}

3
docs/mkdocs/docs/examples/at__object_t_key_type_const.output Normal file
View File

@ -0,0 +1,3 @@
"il brutto"
[json.exception.type_error.304] cannot use at() with string
out of range

42
docs/mkdocs/docs/examples/at__size_type.cpp Normal file
View File

@ -0,0 +1,42 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
// change element at index 1 (second element) to "second"
array.at(1) = "second";
// output changed array
std::cout << array << '\n';
// exception type_error.304
try
{
// use at() on a non-array type
json str = "I am a string";
str.at(0) = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write beyond the array limit
array.at(5) = "sixth";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

4
docs/mkdocs/docs/examples/at__size_type.output Normal file
View File

@ -0,0 +1,4 @@
"third"
["first","second","third","fourth"]
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range

36
docs/mkdocs/docs/examples/at__size_type_const.cpp Normal file
View File

@ -0,0 +1,36 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
const json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
// exception type_error.304
try
{
// use at() on a non-array type
const json str = "I am a string";
std::cout << str.at(0) << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read beyond the array limit
std::cout << array.at(5) << '\n';
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}

3
docs/mkdocs/docs/examples/at__size_type_const.output Normal file
View File

@ -0,0 +1,3 @@
"third"
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range

38
docs/mkdocs/docs/examples/back.cpp Normal file
View File

@ -0,0 +1,38 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_object_empty(json::value_t::object);
json j_array = {1, 2, 4, 8, 16};
json j_array_empty(json::value_t::array);
json j_string = "Hello, world";
// call back()
std::cout << j_boolean.back() << '\n';
std::cout << j_number_integer.back() << '\n';
std::cout << j_number_float.back() << '\n';
std::cout << j_object.back() << '\n';
//std::cout << j_object_empty.back() << '\n'; // undefined behavior
std::cout << j_array.back() << '\n';
//std::cout << j_array_empty.back() << '\n'; // undefined behavior
std::cout << j_string.back() << '\n';
// back() called on a null value
try
{
json j_null;
j_null.back();
}
catch (const json::invalid_iterator& e)
{
std::cout << e.what() << '\n';
}
}

7
docs/mkdocs/docs/examples/back.output Normal file
View File

@ -0,0 +1,7 @@
true
17
23.42
2
16
"Hello, world"
[json.exception.invalid_iterator.214] cannot get value

214
docs/mkdocs/docs/examples/basic_json__CompatibleType.cpp Normal file
View File

@ -0,0 +1,214 @@
#include <iostream>
#include <deque>
#include <list>
#include <forward_list>
#include <set>
#include <unordered_map>
#include <unordered_set>
#include <valarray>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// ============
// object types
// ============
// create an object from an object_t value
json::object_t object_value = { {"one", 1}, {"two", 2} };
json j_object_t(object_value);
// create an object from std::map
std::map<std::string, int> c_map
{
{"one", 1}, {"two", 2}, {"three", 3}
};
json j_map(c_map);
// create an object from std::unordered_map
std::unordered_map<const char*, double> c_umap
{
{"one", 1.2}, {"two", 2.3}, {"three", 3.4}
};
json j_umap(c_umap);
// create an object from std::multimap
std::multimap<std::string, bool> c_mmap
{
{"one", true}, {"two", true}, {"three", false}, {"three", true}
};
json j_mmap(c_mmap); // only one entry for key "three" is used
// create an object from std::unordered_multimap
std::unordered_multimap<std::string, bool> c_ummap
{
{"one", true}, {"two", true}, {"three", false}, {"three", true}
};
json j_ummap(c_ummap); // only one entry for key "three" is used
// serialize the JSON objects
std::cout << j_object_t << '\n';
std::cout << j_map << '\n';
std::cout << j_umap << '\n';
std::cout << j_mmap << '\n';
std::cout << j_ummap << "\n\n";
// ===========
// array types
// ===========
// create an array from an array_t value
json::array_t array_value = {"one", "two", 3, 4.5, false};
json j_array_t(array_value);
// create an array from std::vector
std::vector<int> c_vector {1, 2, 3, 4};
json j_vec(c_vector);
// create an array from std::valarray
std::valarray<short> c_valarray {10, 9, 8, 7};
json j_valarray(c_valarray);
// create an array from std::deque
std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
json j_deque(c_deque);
// create an array from std::list
std::list<bool> c_list {true, true, false, true};
json j_list(c_list);
// create an array from std::forward_list
std::forward_list<std::int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
json j_flist(c_flist);
// create an array from std::array
std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
json j_array(c_array);
// create an array from std::set
std::set<std::string> c_set {"one", "two", "three", "four", "one"};
json j_set(c_set); // only one entry for "one" is used
// create an array from std::unordered_set
std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
json j_uset(c_uset); // only one entry for "one" is used
// create an array from std::multiset
std::multiset<std::string> c_mset {"one", "two", "one", "four"};
json j_mset(c_mset); // both entries for "one" are used
// create an array from std::unordered_multiset
std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
json j_umset(c_umset); // both entries for "one" are used
// serialize the JSON arrays
std::cout << j_array_t << '\n';
std::cout << j_vec << '\n';
std::cout << j_valarray << '\n';
std::cout << j_deque << '\n';
std::cout << j_list << '\n';
std::cout << j_flist << '\n';
std::cout << j_array << '\n';
std::cout << j_set << '\n';
std::cout << j_uset << '\n';
std::cout << j_mset << '\n';
std::cout << j_umset << "\n\n";
// ============
// string types
// ============
// create string from a string_t value
json::string_t string_value = "The quick brown fox jumps over the lazy dog.";
json j_string_t(string_value);
// create a JSON string directly from a string literal
json j_string_literal("The quick brown fox jumps over the lazy dog.");
// create string from std::string
std::string s_stdstring = "The quick brown fox jumps over the lazy dog.";
json j_stdstring(s_stdstring);
// serialize the JSON strings
std::cout << j_string_t << '\n';
std::cout << j_string_literal << '\n';
std::cout << j_stdstring << "\n\n";
// ============
// number types
// ============
// create a JSON number from number_integer_t
json::number_integer_t value_integer_t = -42;
json j_integer_t(value_integer_t);
// create a JSON number from number_unsigned_t
json::number_integer_t value_unsigned_t = 17;
json j_unsigned_t(value_unsigned_t);
// create a JSON number from an anonymous enum
enum { enum_value = 17 };
json j_enum(enum_value);
// create values of different integer types
short n_short = 42;
int n_int = -23;
long n_long = 1024;
int_least32_t n_int_least32_t = -17;
uint8_t n_uint8_t = 8;
// create (integer) JSON numbers
json j_short(n_short);
json j_int(n_int);
json j_long(n_long);
json j_int_least32_t(n_int_least32_t);
json j_uint8_t(n_uint8_t);
// create values of different floating-point types
json::number_float_t v_ok = 3.141592653589793;
json::number_float_t v_nan = NAN;
json::number_float_t v_infinity = INFINITY;
// create values of different floating-point types
float n_float = 42.23;
float n_float_nan = 1.0f / 0.0f;
double n_double = 23.42;
// create (floating point) JSON numbers
json j_ok(v_ok);
json j_nan(v_nan);
json j_infinity(v_infinity);
json j_float(n_float);
json j_float_nan(n_float_nan);
json j_double(n_double);
// serialize the JSON numbers
std::cout << j_integer_t << '\n';
std::cout << j_unsigned_t << '\n';
std::cout << j_enum << '\n';
std::cout << j_short << '\n';
std::cout << j_int << '\n';
std::cout << j_long << '\n';
std::cout << j_int_least32_t << '\n';
std::cout << j_uint8_t << '\n';
std::cout << j_ok << '\n';
std::cout << j_nan << '\n';
std::cout << j_infinity << '\n';
std::cout << j_float << '\n';
std::cout << j_float_nan << '\n';
std::cout << j_double << "\n\n";
// =============
// boolean types
// =============
// create boolean values
json j_truth = true;
json j_falsity = false;
// serialize the JSON booleans
std::cout << j_truth << '\n';
std::cout << j_falsity << '\n';
}

39
docs/mkdocs/docs/examples/basic_json__CompatibleType.output Normal file
View File

@ -0,0 +1,39 @@
{"one":1,"two":2}
{"one":1,"three":3,"two":2}
{"one":1.2,"three":3.4,"two":2.3}
{"one":true,"three":false,"two":true}
{"one":true,"three":false,"two":true}
["one","two",3,4.5,false]
[1,2,3,4]
[10,9,8,7]
[1.2,2.3,3.4,5.6]
[true,true,false,true]
[12345678909876,23456789098765,34567890987654,45678909876543]
[1,2,3,4]
["four","one","three","two"]
["four","three","two","one"]
["four","one","one","two"]
["four","two","one","one"]
"The quick brown fox jumps over the lazy dog."
"The quick brown fox jumps over the lazy dog."
"The quick brown fox jumps over the lazy dog."
-42
17
17
42
-23
1024
-17
8
3.141592653589793
null
null
42.22999954223633
null
23.42
true
false

32
docs/mkdocs/docs/examples/basic_json__InputIt_InputIt.cpp Normal file
View File

@ -0,0 +1,32 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_array = {"alpha", "bravo", "charly", "delta", "easy"};
json j_number = 42;
json j_object = {{"one", "eins"}, {"two", "zwei"}};
// create copies using iterators
json j_array_range(j_array.begin() + 1, j_array.end() - 2);
json j_number_range(j_number.begin(), j_number.end());
json j_object_range(j_object.begin(), j_object.find("two"));
// serialize the values
std::cout << j_array_range << '\n';
std::cout << j_number_range << '\n';
std::cout << j_object_range << '\n';
// example for an exception
try
{
json j_invalid(j_number.begin() + 1, j_number.end());
}
catch (const json::invalid_iterator& e)
{
std::cout << e.what() << '\n';
}
}

4
docs/mkdocs/docs/examples/basic_json__InputIt_InputIt.output Normal file
View File

@ -0,0 +1,4 @@
["bravo","charly"]
42
{"one":"eins"}
[json.exception.invalid_iterator.204] iterators out of range

17
docs/mkdocs/docs/examples/basic_json__basic_json.cpp Normal file
View File

@ -0,0 +1,17 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON array
json j1 = {"one", "two", 3, 4.5, false};
// create a copy
json j2(j1);
// serialize the JSON array
std::cout << j1 << " = " << j2 << '\n';
std::cout << std::boolalpha << (j1 == j2) << '\n';
}

2
docs/mkdocs/docs/examples/basic_json__basic_json.output Normal file
View File

@ -0,0 +1,2 @@
["one","two",3,4.5,false] = ["one","two",3,4.5,false]
true

18
docs/mkdocs/docs/examples/basic_json__copyassignment.cpp Normal file
View File

@ -0,0 +1,18 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json a = 23;
json b = 42;
// copy-assign a to b
b = a;
// serialize the JSON arrays
std::cout << a << '\n';
std::cout << b << '\n';
}

2
docs/mkdocs/docs/examples/basic_json__copyassignment.output Normal file
View File

@ -0,0 +1,2 @@
23
23

21
docs/mkdocs/docs/examples/basic_json__list_init_t.cpp Normal file
View File

@ -0,0 +1,21 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_empty_init_list = json({});
json j_object = { {"one", 1}, {"two", 2} };
json j_array = {1, 2, 3, 4};
json j_nested_object = { {"one", {1}}, {"two", {1, 2}} };
json j_nested_array = { {{1}, "one"}, {{1, 2}, "two"} };
// serialize the JSON value
std::cout << j_empty_init_list << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_nested_object << '\n';
std::cout << j_nested_array << '\n';
}

5
docs/mkdocs/docs/examples/basic_json__list_init_t.output Normal file
View File

@ -0,0 +1,5 @@
{}
{"one":1,"two":2}
[1,2,3,4]
{"one":[1],"two":[1,2]}
[[[1],"one"],[[1,2],"two"]]

17
docs/mkdocs/docs/examples/basic_json__moveconstructor.cpp Normal file
View File

@ -0,0 +1,17 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON value
json a = 23;
// move contents of a to b
json b(std::move(a));
// serialize the JSON arrays
std::cout << a << '\n';
std::cout << b << '\n';
}

2
docs/mkdocs/docs/examples/basic_json__moveconstructor.output Normal file
View File

@ -0,0 +1,2 @@
null
23

16
docs/mkdocs/docs/examples/basic_json__nullptr_t.cpp Normal file
View File

@ -0,0 +1,16 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// implicitly create a JSON null value
json j1;
// explicitly create a JSON null value
json j2(nullptr);
// serialize the JSON null value
std::cout << j1 << '\n' << j2 << '\n';
}

2
docs/mkdocs/docs/examples/basic_json__nullptr_t.output Normal file
View File

@ -0,0 +1,2 @@
null
null

18
docs/mkdocs/docs/examples/basic_json__size_type_basic_json.cpp Normal file
View File

@ -0,0 +1,18 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array by creating copies of a JSON value
json value = "Hello";
json array_0 = json(0, value);
json array_1 = json(1, value);
json array_5 = json(5, value);
// serialize the JSON arrays
std::cout << array_0 << '\n';
std::cout << array_1 << '\n';
std::cout << array_5 << '\n';
}

3
docs/mkdocs/docs/examples/basic_json__size_type_basic_json.output Normal file
View File

@ -0,0 +1,3 @@
[]
["Hello"]
["Hello","Hello","Hello","Hello","Hello"]

25
docs/mkdocs/docs/examples/basic_json__value_t.cpp Normal file
View File

@ -0,0 +1,25 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create the different JSON values with default values
json j_null(json::value_t::null);
json j_boolean(json::value_t::boolean);
json j_number_integer(json::value_t::number_integer);
json j_number_float(json::value_t::number_float);
json j_object(json::value_t::object);
json j_array(json::value_t::array);
json j_string(json::value_t::string);
// serialize the JSON values
std::cout << j_null << '\n';
std::cout << j_boolean << '\n';
std::cout << j_number_integer << '\n';
std::cout << j_number_float << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_string << '\n';
}

7
docs/mkdocs/docs/examples/basic_json__value_t.output Normal file
View File

@ -0,0 +1,7 @@
null
false
0
0.0
{}
[]
""

16
docs/mkdocs/docs/examples/begin.cpp Normal file
View File

@ -0,0 +1,16 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
json array = {1, 2, 3, 4, 5};
// get an iterator to the first element
json::iterator it = array.begin();
// serialize the element that the iterator points to
std::cout << *it << '\n';
}

1
docs/mkdocs/docs/examples/begin.output Normal file
View File

@ -0,0 +1 @@
1

16
docs/mkdocs/docs/examples/binary.cpp Normal file
View File

@ -0,0 +1,16 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a binary vector
std::vector<std::uint8_t> vec = {0xCA, 0xFE, 0xBA, 0xBE};
// create a binary JSON value with subtype 42
json j = json::binary(vec, 42);
// output type and subtype
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
}

1
docs/mkdocs/docs/examples/binary.output Normal file
View File

@ -0,0 +1 @@
type: binary, subtype: 42

10
docs/mkdocs/docs/examples/binary_t.cpp Normal file
View File

@ -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;
}

1
docs/mkdocs/docs/examples/binary_t.output Normal file
View File

@ -0,0 +1 @@
true

10
docs/mkdocs/docs/examples/boolean_t.cpp Normal file
View File

@ -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;
}

1
docs/mkdocs/docs/examples/boolean_t.output Normal file
View File

@ -0,0 +1 @@
true

23
docs/mkdocs/docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp Normal file
View File

@ -0,0 +1,23 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
// (1) create empty container
auto c1 = byte_container_with_subtype();
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// (2) create container
auto c2 = byte_container_with_subtype(bytes);
// (3) create container with subtype
auto c3 = byte_container_with_subtype(bytes, 42);
std::cout << json(c1) << "\n" << json(c2) << "\n" << json(c3) << std::endl;
}

3
docs/mkdocs/docs/examples/byte_container_with_subtype__byte_container_with_subtype.output Normal file
View File

@ -0,0 +1,3 @@
{"bytes":[],"subtype":null}
{"bytes":[202,254,186,190],"subtype":null}
{"bytes":[202,254,186,190],"subtype":42}

21
docs/mkdocs/docs/examples/byte_container_with_subtype__clear_subtype.cpp Normal file
View File

@ -0,0 +1,21 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container with subtype
auto c1 = byte_container_with_subtype(bytes, 42);
std::cout << "before calling clear_subtype(): " << json(c1) << '\n';
c1.clear_subtype();
std::cout << "after calling clear_subtype(): " << json(c1) << '\n';
}

2
docs/mkdocs/docs/examples/byte_container_with_subtype__clear_subtype.output Normal file
View File

@ -0,0 +1,2 @@
before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}

19
docs/mkdocs/docs/examples/byte_container_with_subtype__has_subtype.cpp Normal file
View File

@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container
auto c1 = byte_container_with_subtype(bytes);
// create container with subtype
auto c2 = byte_container_with_subtype(bytes, 42);
std::cout << std::boolalpha << "c1.has_subtype() = " << c1.has_subtype()
<< "\nc2.has_subtype() = " << c2.has_subtype() << std::endl;
}

2
docs/mkdocs/docs/examples/byte_container_with_subtype__has_subtype.output Normal file
View File

@ -0,0 +1,2 @@
c1.has_subtype() = false
c2.has_subtype() = true

22
docs/mkdocs/docs/examples/byte_container_with_subtype__set_subtype.cpp Normal file
View File

@ -0,0 +1,22 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container without subtype
auto c = byte_container_with_subtype(bytes);
std::cout << "before calling set_subtype(42): " << json(c) << '\n';
// set the subtype
c.set_subtype(42);
std::cout << "after calling set_subtype(42): " << json(c) << '\n';
}

2
docs/mkdocs/docs/examples/byte_container_with_subtype__set_subtype.output Normal file
View File

@ -0,0 +1,2 @@
before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}

22
docs/mkdocs/docs/examples/byte_container_with_subtype__subtype.cpp Normal file
View File

@ -0,0 +1,22 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container
auto c1 = byte_container_with_subtype(bytes);
// create container with subtype
auto c2 = byte_container_with_subtype(bytes, 42);
std::cout << "c1.subtype() = " << c1.subtype()
<< "\nc2.subtype() = " << c2.subtype() << std::endl;
// in case no subtype is set, return special value
assert(c1.subtype() == static_cast<byte_container_with_subtype::subtype_type>(-1));
}

2
docs/mkdocs/docs/examples/byte_container_with_subtype__subtype.output Normal file
View File

@ -0,0 +1,2 @@
c1.subtype() = 18446744073709551615
c2.subtype() = 42

16
docs/mkdocs/docs/examples/cbegin.cpp Normal file
View File

@ -0,0 +1,16 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
const json array = {1, 2, 3, 4, 5};
// get an iterator to the first element
json::const_iterator it = array.cbegin();
// serialize the element that the iterator points to
std::cout << *it << '\n';
}

1
docs/mkdocs/docs/examples/cbegin.output Normal file
View File

@ -0,0 +1 @@
1

28
docs/mkdocs/docs/examples/cbor_tag_handler_t.cpp Normal file
View File

@ -0,0 +1,28 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// tagged byte string
std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};
// cbor_tag_handler_t::error throws
try
{
auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << std::endl;
}
// cbor_tag_handler_t::ignore ignores the tag
auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
std::cout << b_ignore_tag << std::endl;
// cbor_tag_handler_t::store stores the tag as binary subtype
auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
std::cout << b_store_tag << std::endl;
}

3
docs/mkdocs/docs/examples/cbor_tag_handler_t.output Normal file
View File

@ -0,0 +1,3 @@
[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
{"bytes":[202,254,186,190],"subtype":null}
{"bytes":[202,254,186,190],"subtype":66}

19
docs/mkdocs/docs/examples/cend.cpp Normal file
View File

@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
json array = {1, 2, 3, 4, 5};
// get an iterator to one past the last element
json::const_iterator it = array.cend();
// decrement the iterator to point to the last element
--it;
// serialize the element that the iterator points to
std::cout << *it << '\n';
}

1
docs/mkdocs/docs/examples/cend.output Normal file
View File

@ -0,0 +1 @@
5

34
docs/mkdocs/docs/examples/clear.cpp Normal file
View File

@ -0,0 +1,34 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hello, world";
// call clear()
j_null.clear();
j_boolean.clear();
j_number_integer.clear();
j_number_float.clear();
j_object.clear();
j_array.clear();
j_string.clear();
// serialize the cleared values()
std::cout << j_null << '\n';
std::cout << j_boolean << '\n';
std::cout << j_number_integer << '\n';
std::cout << j_number_float << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_string << '\n';
}

7
docs/mkdocs/docs/examples/clear.output Normal file
View File

@ -0,0 +1,7 @@
null
false
0
0.0
{}
[]
""

43
docs/mkdocs/docs/examples/contains__json_pointer.cpp Normal file
View File

@ -0,0 +1,43 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON value
json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
std::cout << std::boolalpha
<< j.contains("/number"_json_pointer) << '\n'
<< j.contains("/string"_json_pointer) << '\n'
<< j.contains("/array"_json_pointer) << '\n'
<< j.contains("/array/1"_json_pointer) << '\n'
<< j.contains("/array/-"_json_pointer) << '\n'
<< j.contains("/array/4"_json_pointer) << '\n'
<< j.contains("/baz"_json_pointer) << std::endl;
try
{
// try to use an array index with leading '0'
j.contains("/array/01"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
try
{
// try to use an array index that is not a number
j.contains("/array/one"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
}

7
docs/mkdocs/docs/examples/contains__json_pointer.output Normal file
View File

@ -0,0 +1,7 @@
true
true
true
true
false
false
false

20
docs/mkdocs/docs/examples/contains__keytype.c++17.cpp Normal file
View File

@ -0,0 +1,20 @@
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create some JSON values
json j_object = R"( {"key": "value"} )"_json;
json j_array = R"( [1, 2, 3] )"_json;
// call contains
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
"j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
"j_array contains 'key': " << j_array.contains("key"sv) << std::endl;
}

3
docs/mkdocs/docs/examples/contains__keytype.c++17.output Normal file
View File

@ -0,0 +1,3 @@
j_object contains 'key': true
j_object contains 'another': false
j_array contains 'key': false

18
docs/mkdocs/docs/examples/contains__object_t_key_type.cpp Normal file
View File

@ -0,0 +1,18 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create some JSON values
json j_object = R"( {"key": "value"} )"_json;
json j_array = R"( [1, 2, 3] )"_json;
// call contains
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key") << '\n' <<
"j_object contains 'another': " << j_object.contains("another") << '\n' <<
"j_array contains 'key': " << j_array.contains("key") << std::endl;
}

3
docs/mkdocs/docs/examples/contains__object_t_key_type.output Normal file
View File

@ -0,0 +1,3 @@
j_object contains 'key': true
j_object contains 'another': false
j_array contains 'key': false

20
docs/mkdocs/docs/examples/count__keytype.c++17.cpp Normal file
View File

@ -0,0 +1,20 @@
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create a JSON object
json j_object = {{"one", 1}, {"two", 2}};
// call count()
auto count_two = j_object.count("two"sv);
auto count_three = j_object.count("three"sv);
// print values
std::cout << "number of elements with key \"two\": " << count_two << '\n';
std::cout << "number of elements with key \"three\": " << count_three << '\n';
}

2
docs/mkdocs/docs/examples/count__keytype.c++17.output Normal file
View File

@ -0,0 +1,2 @@
number of elements with key "two": 1
number of elements with key "three": 0

18
docs/mkdocs/docs/examples/count__object_t_key_type.cpp Normal file
View File

@ -0,0 +1,18 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object
json j_object = {{"one", 1}, {"two", 2}};
// call count()
auto count_two = j_object.count("two");
auto count_three = j_object.count("three");
// print values
std::cout << "number of elements with key \"two\": " << count_two << '\n';
std::cout << "number of elements with key \"three\": " << count_three << '\n';
}

2
docs/mkdocs/docs/examples/count__object_t_key_type.output Normal file
View File

@ -0,0 +1,2 @@
number of elements with key "two": 1
number of elements with key "three": 0

16
docs/mkdocs/docs/examples/crbegin.cpp Normal file
View File

@ -0,0 +1,16 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
json array = {1, 2, 3, 4, 5};
// get an iterator to the reverse-beginning
json::const_reverse_iterator it = array.crbegin();
// serialize the element that the iterator points to
std::cout << *it << '\n';
}

1
docs/mkdocs/docs/examples/crbegin.output Normal file
View File

@ -0,0 +1 @@
5

19
docs/mkdocs/docs/examples/crend.cpp Normal file
View File

@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
json array = {1, 2, 3, 4, 5};
// get an iterator to the reverse-end
json::const_reverse_iterator it = array.crend();
// increment the iterator to point to the first element
--it;
// serialize the element that the iterator points to
std::cout << *it << '\n';
}

Some files were not shown because too many files have changed in this diff Show More