Niels Lohmann
731f1b5bfb
* json_view: view_mode enum instead of bool Editable, node_kind for node::kind basic_json_document and basic_json_view take a view_mode (read_only, the default, or editable) instead of a bool: basic_json_document<json, true> did not say what true means. The shortcut aliases are unchanged. The kind of a node is a node_kind (the value_t values plus link, 10 as before), which removes the static_cast<std::uint8_t>(value_t::...) of every comparison. The node and image layouts are unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * json_view: node_kind in the node writers, spell out read_only, comment fixes The builder and the edit functions take and store a node_kind instead of casting a value_t; the numbering assertions and the comments now speak of node_kind, and the link kind notes that it follows value_t::discarded. The read-only aliases name view_mode::read_only like the editable ones. view_mode.md says the mode is a compile-time property of the type. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * json_view: views of read-only documents convert to editable views A read-only document has no edits, so a view of it reads correctly as a view of an editable document before its first edit. The implicit conversion lets a function taking a json_editable_view accept the views of both modes. There is no conversion the other way: a read-only view of an editable document would read wrong values after the next edit. The mode comparisons in the cross-mode operator==/!= use an is_other_mode trait, which astyle keeps compact. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.6 KiB
nlohmann::view_mode
Defined in header <nlohmann/json_view.hpp>
enum class view_mode : std::uint8_t
{
read_only,
editable
};
The second template parameter of basic_json_document and
basic_json_view: whether a document can be changed after parsing, and whether a view is
of such a document.
read_only- the default: the document is parsed once and then only read. It carries none of the bookkeeping edits need, and
calling
set,push_back,insert, oreraseon it fails to compile. editable- the document also offers
set,push_back,insert, anderase; its views see every edit, see Edits.
The shortcuts name both modes: json_document and json_view are read-only,
json_editable_document and json_editable_view are editable
(and likewise for ordered_json).
Notes
The mode is a compile-time property of the document's and the view's type, not a setting of a call. A read-only view
reads a container in place, while a view of an editable document follows the links that edits leave behind. A view of
a read-only document converts implicitly to a view of an editable document of the same BasicJsonType: a read-only
document has no edits, so the converted view reads it like an editable document before its first edit (at the cost of
one check per access). There is no conversion the other way, because a read-only view of an editable document would
read wrong values after the next edit.
A function that takes a json_editable_view therefore accepts the views of both modes. A
function template deduces the mode from its argument instead, without conversions, so it names the modes it accepts in
its signature:
// views of editable documents only
template<typename BasicJsonType>
void f(basic_json_view<BasicJsonType, view_mode::editable> v);
// views of read-only documents only
template<typename BasicJsonType>
void f(basic_json_view<BasicJsonType, view_mode::read_only> v);
// either
template<typename BasicJsonType, view_mode Mode>
void f(basic_json_view<BasicJsonType, Mode> v);
A function that takes a json_view accepts neither an ordered_json_view
nor a json_editable_view. Views of the two modes compare with
operator==.
Examples
??? example
The example below shows a function template that accepts the views of both modes, one that accepts only views of
editable documents, and a function taking a `json_editable_view` that also accepts a view of a read-only document.
```cpp
--8<-- "examples/view_mode.cpp"
```
Output:
```
--8<-- "examples/view_mode.output"
```
See also
- basic_json_document - a parsed JSON text
- basic_json_view - a handle to one value of a document
- json_editable_document - an editable document of
json - (constructor) - the conversion from a read-only to an editable view
Version history
Added in version 3.13.0.