Fix documentation errors and clean up repository leftovers (#6140)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
1 parent
ac0d25f51c
commit
f6eb5e4fb1
25 files changed
+106
-134
No files matched your search
@@ -2,12 +2,21 @@
|
||||
|
||||
```cpp
|
||||
namespace std {
|
||||
void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
|
||||
void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2) noexcept(
|
||||
is_nothrow_move_constructible<nlohmann::basic_json>::value &&
|
||||
is_nothrow_move_assignable<nlohmann::basic_json>::value
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Exchanges the values of two JSON objects.
|
||||
|
||||
This specialization is only provided before C++20, which no longer allows specializing function templates in
|
||||
namespace `std`. With C++20 (and in generic code with any standard), use the idiom `#!cpp using std::swap; swap(j1, j2);`: it finds
|
||||
the [`swap`](swap.md) friend function (overload 2) by argument-dependent lookup. A qualified `#!cpp std::swap(j1, j2)`
|
||||
still compiles with C++20, but uses the generic `std::swap`, which swaps by three moves instead of exchanging the
|
||||
contents.
|
||||
|
||||
## Parameters
|
||||
|
||||
`j1` (in, out)
|
||||
@@ -18,7 +27,9 @@ Exchanges the values of two JSON objects.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
No-throw guarantee if the `noexcept` condition above holds: it holds unless moving the
|
||||
[`json_base_class_t`](json_base_class_t.md) can throw. With the default base class, this function never throws
|
||||
exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -57,3 +68,4 @@ void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Extended for arbitrary basic_json types in version 3.10.5.
|
||||
- Not provided with C++20 since version 3.9.0.
|
||||
@@ -75,8 +75,12 @@ void swap(typename binary_t::container_type& other);
|
||||
|
||||
## Exception safety
|
||||
|
||||
1. No-throw guarantee: this function never throws exceptions.
|
||||
2. No-throw guarantee: this function never throws exceptions.
|
||||
1. No-throw guarantee if the `noexcept` condition above holds: it holds unless moving the
|
||||
[`json_base_class_t`](json_base_class_t.md) can throw (moving the type tag and the stored value never throws).
|
||||
With the default base class, this function never throws exceptions.
|
||||
2. No-throw guarantee if the `noexcept` condition above holds: it holds unless moving the
|
||||
[`json_base_class_t`](json_base_class_t.md) can throw (moving the type tag and the stored value never throws).
|
||||
With the default base class, this function never throws exceptions.
|
||||
3. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
4. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
@@ -85,8 +89,8 @@ void swap(typename binary_t::container_type& other);
|
||||
|
||||
## Exceptions
|
||||
|
||||
1. No-throw guarantee: this function never throws exceptions.
|
||||
2. No-throw guarantee: this function never throws exceptions.
|
||||
1. Throws only what moving the [`json_base_class_t`](json_base_class_t.md) throws; nothing with the default base class.
|
||||
2. Throws only what moving the [`json_base_class_t`](json_base_class_t.md) throws; nothing with the default base class.
|
||||
3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
|
||||
arrays; example: `"cannot use swap(array_t&) with boolean"`
|
||||
4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
|
||||
|
||||
@@ -57,7 +57,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
## Exceptions
|
||||
|
||||
- Throws [`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if `use_type` is true and `use_size`
|
||||
is false, and `j` contains a non-empty array, object, or binary value.
|
||||
is false, and `j` contains a non-empty array, object, or binary value. Scalars and empty arrays, objects, or binary
|
||||
values do not throw.
|
||||
- Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
|
||||
not valid UTF-8 and `error_handler` is `strict` (the default only if
|
||||
[`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
|
||||
|
||||
@@ -66,7 +66,8 @@ has `erase`; calling it on a read-only `basic_json_document` fails to compile (`
|
||||
[`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) (a leading `#!cpp '0'`),
|
||||
[`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) (not a number),
|
||||
[`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) (too large for `size_type`), or
|
||||
[`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) (an empty token); otherwise (an
|
||||
[`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) (an empty token, or the token
|
||||
`#!cpp "-"`, which never names an existing element); otherwise (an
|
||||
object, or a primitive value the pointer's parent resolves to) throws what 1. throws.
|
||||
|
||||
Overloads 1. and 2. also throw [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202)
|
||||
|
||||
@@ -62,10 +62,9 @@ view.
|
||||
|
||||
!!! info "Overload 2 never throws"
|
||||
|
||||
Unlike [`BasicJsonType::contains(const json_pointer&)`](../basic_json/contains.md), which can throw for certain
|
||||
malformed pointers (for instance an empty array-index reference token), overload 2 never throws: a missing key,
|
||||
an out-of-range or malformed array index, a `#!cpp "-"` index, or a reference token used on a primitive all
|
||||
simply make it return `#!cpp false`.
|
||||
Like [`BasicJsonType::contains(const json_pointer&)`](../basic_json/contains.md), overload 2 never throws: a
|
||||
missing key, an out-of-range or malformed array index, a `#!cpp "-"` index, or a reference token used on a
|
||||
primitive all simply make it return `#!cpp false`.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -27,9 +27,10 @@ for (const auto [key, value] : v.items())
|
||||
}
|
||||
```
|
||||
|
||||
Note the `#!cpp const auto` (by value), not `#!cpp const auto&`: unlike `BasicJsonType::items()`, whose elements are
|
||||
references into an existing object, a view's `item` is produced on the fly for each step of the iteration, so there
|
||||
is nothing for a reference to bind to.
|
||||
Taking `item` by value (`#!cpp const auto`) is recommended: unlike `BasicJsonType::items()`, whose elements are
|
||||
references into an existing object, a view's `item` is produced on the fly for each step of the iteration and is
|
||||
cheap to copy. A `#!cpp const auto&` (as in the first snippet) also works, as it binds to that temporary, but a
|
||||
non-const `#!cpp auto&` does not compile.
|
||||
|
||||
## Return value
|
||||
|
||||
|
||||
@@ -7,6 +7,10 @@ bool operator==(const basic_json_view& lhs, const basic_json_view& rhs);
|
||||
// (2)
|
||||
bool operator==(const basic_json_view& lhs, const BasicJsonType& rhs);
|
||||
bool operator==(const BasicJsonType& lhs, const basic_json_view& rhs);
|
||||
|
||||
// (3)
|
||||
template<view_mode M>
|
||||
bool operator==(const basic_json_view& lhs, const basic_json_view<BasicJsonType, M>& rhs);
|
||||
```
|
||||
|
||||
1. Compares two views for equality: whether the values [`BasicJsonType::parse()`](../basic_json/parse.md) would
|
||||
@@ -14,8 +18,12 @@ bool operator==(const BasicJsonType& lhs, const basic_json_view& rhs);
|
||||
2. Compares a view and a `BasicJsonType` value for equality, in either order: whether the value `parse()` would
|
||||
produce for the view and the other operand are equal, according to `BasicJsonType`'s
|
||||
[`operator==`](../basic_json/operator_eq.md).
|
||||
3. Like overload 1, for two views of the same `BasicJsonType` but of different [view modes](../view_mode.md), in
|
||||
either order: a view of a read-only document (such as a [`json_view`](../json_view.md)) and a view of an editable
|
||||
document (such as a [`json_editable_view`](../json_editable_view.md)). This overload only takes part in overload
|
||||
resolution if `M` is not the mode of `lhs`.
|
||||
|
||||
Neither overload builds a `BasicJsonType` value for a view to do the comparison (see [Notes](#notes) below). Numbers
|
||||
No overload builds a `BasicJsonType` value for a view to do the comparison (see [Notes](#notes) below). Numbers
|
||||
compare by value across their types (`#!cpp 1 == 1.0`), and an object compares by its members, with duplicate keys
|
||||
resolved exactly as `parse()` resolves them — the last value, at the position of the first occurrence of the key.
|
||||
This is not what [`operator[]`](operator[].md) and the other lookups return for a duplicate key: they find the *first*
|
||||
|
||||
@@ -7,11 +7,17 @@ bool operator!=(const basic_json_view& lhs, const basic_json_view& rhs);
|
||||
// (2)
|
||||
bool operator!=(const basic_json_view& lhs, const BasicJsonType& rhs);
|
||||
bool operator!=(const BasicJsonType& lhs, const basic_json_view& rhs);
|
||||
|
||||
// (3)
|
||||
template<view_mode M>
|
||||
bool operator!=(const basic_json_view& lhs, const basic_json_view<BasicJsonType, M>& rhs);
|
||||
```
|
||||
|
||||
1. Compares two views for inequality. Returns `#!cpp !(lhs == rhs)`, see [operator==](operator_eq.md).
|
||||
2. Compares a view and a `BasicJsonType` value for inequality, in either order. Returns `#!cpp !(lhs == rhs)` (or,
|
||||
for the reversed order, `#!cpp !(rhs == lhs)`), see [operator==](operator_eq.md).
|
||||
3. Compares a read-only and an editable view of the same `BasicJsonType` for inequality, in either order. Returns
|
||||
`#!cpp !(lhs == rhs)`, see [operator==](operator_eq.md).
|
||||
|
||||
Since `operator!=` is defined as the negation of [`operator==`](operator_eq.md), it follows the same rules for
|
||||
special cases: for instance, since a [discarded](is_discarded.md) view is never equal to anything by default (see
|
||||
|
||||
@@ -15,6 +15,10 @@ materializing anything.
|
||||
- `#!cpp static_cast<std::size_t>(-1)` for a [discarded](is_discarded.md) view, and for a string that contains
|
||||
escapes — such a string was decoded once into the document's own buffer, so there is no single byte range in
|
||||
`source()` left to point at.
|
||||
- `#!cpp static_cast<std::size_t>(-1)` in an [editable document](../json_editable_document.md) for a value written
|
||||
by an edit ([`set`](../basic_json_document/set.md), [`push_back`](../basic_json_document/push_back.md),
|
||||
[`insert`](../basic_json_document/insert.md)), and for an array or object whose elements an edit added or removed.
|
||||
The values an edit did not touch keep their offsets.
|
||||
|
||||
## Exception safety
|
||||
|
||||
|
||||
@@ -8,8 +8,9 @@ using json_editable_document = basic_json_document<json, view_mode::editable>;
|
||||
|
||||
This type is an **editable** [`basic_json_document`](basic_json_document/index.md) of the default
|
||||
[`json`](json.md) specialization: in addition to everything [`json_document`](json_document.md) offers,
|
||||
[`set`](basic_json_document/set.md) and [`push_back`](basic_json_document/push_back.md) change values after
|
||||
parsing, without ever rewriting the source text — see [Edits](basic_json_document/index.md#edits) and
|
||||
[`set`](basic_json_document/set.md), [`push_back`](basic_json_document/push_back.md),
|
||||
[`insert`](basic_json_document/insert.md), and [`erase`](basic_json_document/erase.md) change values after parsing,
|
||||
without ever rewriting the source text — see [Edits](basic_json_document/index.md#edits) and
|
||||
[Editing a document](../features/json_view/editing.md).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -9,7 +9,8 @@ using json_editable_view = basic_json_view<json, view_mode::editable>;
|
||||
This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a
|
||||
[`json_editable_document`](json_editable_document.md). It offers the same read-only interface as
|
||||
[`json_view`](json_view.md); what is different is what it can be a view *of* — a value that
|
||||
[`set`](basic_json_document/set.md) and [`push_back`](basic_json_document/push_back.md) can change, with every view
|
||||
[`set`](basic_json_document/set.md), [`push_back`](basic_json_document/push_back.md),
|
||||
[`insert`](basic_json_document/insert.md), and [`erase`](basic_json_document/erase.md) can change, with every view
|
||||
still referring to it seeing the change, see [Edits](basic_json_document/index.md#edits).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -171,7 +171,7 @@ See the examples below for the concrete generated code.
|
||||
|
||||
The macro is equivalent to:
|
||||
|
||||
```cpp hl_lines="22 22 23 24 25 26 27 28"
|
||||
```cpp hl_lines="22 23 24 25 26 27 28"
|
||||
--8<-- "examples/nlohmann_define_type_intrusive_only_serialize_explicit.cpp"
|
||||
```
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ For further information please refer to the corresponding macros without `WITH_N
|
||||
|
||||
The macro is equivalent to:
|
||||
|
||||
```cpp hl_lines="16 17 18 19 20 21 22 23 24 25 26 27 28"
|
||||
```cpp hl_lines="16 17 18 19 20 21 22 23 24 25 26 27 28 29 30"
|
||||
--8<-- "examples/nlohmann_define_type_non_intrusive_with_names_explicit.cpp"
|
||||
```
|
||||
|
||||
|
||||
@@ -98,7 +98,7 @@ serialization fails by default. The fourth argument of `dump` selects an
|
||||
|
||||
## Using `std::format`, `std::print`, and `fmt`
|
||||
|
||||
Since version 3.12.0, JSON values can be formatted directly with C++20's
|
||||
Since version 3.13.0, JSON values can be formatted directly with C++20's
|
||||
[`std::format`](https://en.cppreference.com/w/cpp/utility/format/format) whenever the standard library provides the
|
||||
`<format>` header (controlled by [`JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md)). This is enabled by the
|
||||
[`std::formatter<basic_json>`](../api/basic_json/std_formatter.md) specialization, which also makes JSON values work with
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Recipes for Common Types
|
||||
|
||||
The library converts the standard containers, strings, numbers, tuples, `std::optional`, and `std::filesystem::path`
|
||||
(the last two since version 3.12.0, C++17) out of the box, and your own types once you write conversion functions or use
|
||||
The library converts the standard containers, strings, numbers, tuples, `std::optional` (since version 3.12.0), and
|
||||
`std::filesystem::path` (since version 3.10.5), the last two with C++17, out of the box, and your own types once you write conversion functions or use
|
||||
the macros (see [Arbitrary type conversions](arbitrary_types.md)). It deliberately does **not** convert smart pointers,
|
||||
`std::variant`, `std::chrono` types, or class hierarchies, because there is more than one reasonable JSON
|
||||
representation for each of them. This page shows a representation for each that you can copy and adapt.
|
||||
|
||||
@@ -987,7 +987,9 @@ contains other characters (e.g., `1a`), or `-` where it cannot be used.
|
||||
|
||||
The JSON Patch operations 'remove' and 'move' cannot be applied to the root element of the JSON value. The exception is
|
||||
also thrown when the parent or a reference token of an empty JSON Pointer is requested, for instance by
|
||||
[`back`](../api/json_pointer/back.md) or [`pop_back`](../api/json_pointer/pop_back.md).
|
||||
[`front`](../api/json_pointer/front.md), [`back`](../api/json_pointer/back.md),
|
||||
[`pop_front`](../api/json_pointer/pop_front.md), or [`pop_back`](../api/json_pointer/pop_back.md), and when
|
||||
[`basic_json_document::erase`](../api/basic_json_document/erase.md) is called with an empty JSON Pointer.
|
||||
|
||||
!!! failure "Example message"
|
||||
|
||||
@@ -1263,9 +1265,9 @@ A JSON Patch operation 'test' failed. The unsuccessful operation is also printed
|
||||
### json.exception.other_error.502
|
||||
|
||||
[`to_ubjson`](../api/basic_json/to_ubjson.md) and [`to_bjdata`](../api/basic_json/to_bjdata.md) were called with
|
||||
`use_type = true` but `use_size = false`, and the value contains a non-empty array or object (or, with BJData Draft 3,
|
||||
any binary value). UBJSON requires a size marker (`#`) after a type marker (`$`); scalars and empty arrays or objects
|
||||
do not throw.
|
||||
`use_type = true` but `use_size = false`, and the value contains a non-empty array, object, or binary value (with
|
||||
BJData Draft 3, any binary value, including an empty one). UBJSON requires a size marker (`#`) after a type marker
|
||||
(`$`); scalars and empty arrays or objects do not throw.
|
||||
|
||||
!!! failure "Example message"
|
||||
|
||||
|
||||
Reference in new issue
Block a user