Niels Lohmann
6a852ab96d
* Split the json_view feature page into sub-pages
The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.
The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.
Internal links across the documentation point to the new pages.
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
* Docs: fix stale comments and trim repeated text in json_view pages
- fig-jsonview.js/.css: point the header comments at the new pages
- reading.md: views' strings are valid as long as the document (and a
borrowed source text), as lifetime.md says
- reading.md, generic_code.md: link to differences.md instead of
restating the member-order and repeated-key rules
- differences.md: drop the third mention of ordering comparisons, name
rbegin()/rend() in the iterator row
- exceptions.md: link editable documents to editing.md
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---------
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.9 KiB
2.9 KiB
nlohmann::basic_json_view::get_to
template<typename T>
T& get_to(T& v) const;
Converts the value to T and stores it in v, in one of three ways:
- For the types that
get<T>()converts directly — arithmetic types,#!cpp bool,#!cpp std::nullptr_t,string_view_t,#!cpp std::basic_string,BasicJsonType,basic_json_view, vectors of these, and maps of views —vis assigned:#!cpp v = get<T>(). - For a type whose
from_json()accepts views (seeget<T>()), thatfrom_json()is called with the view and the existingv, without building aBasicJsonTypevalue. - For every other type, the subtree is built into a
BasicJsonTypevalue and#!cpp materialize().get_to(v)is called, i.e.from_json()is invoked with the existingv, exactly asBasicJsonType::get_to()does.
Template parameters
T- the type to convert the value to
Parameters
v(out)- the variable to store the converted value in
Return value
v, allowing calls to chain
Exception safety
- For the directly converted types: strong exception safety. If an exception is thrown,
vis not modified. - For every other type: as for
BasicJsonType::get_to().materialize()throws beforevis touched, but afrom_json()that throws may leavevpartly modified.
Exceptions
- For the directly converted types: whatever
get<T>()throws for the same value andT. - For every other type: whatever
materialize()andBasicJsonType::get_to()throw.
Complexity
- For the directly converted types: whatever
get<T>()has for the sameT. - For every other type: that of
materialize(), plus that ofBasicJsonType::get_to().
Notes
The difference between the two ways matters for a from_json() that sets only the fields present in the JSON: since
it runs on the existing v, the other fields of v keep their values, whereas assigning get<T>() would replace
them with those of a default-constructed T.
Examples
??? example
The example below reads several fields of a service configuration directly into existing variables, then uses
the returned reference to fold the `#!cpp host`/`#!cpp port` pair into a single string in the same expression.
```cpp
--8<-- "examples/basic_json_view__get_to.cpp"
```
Output:
```json
--8<-- "examples/basic_json_view__get_to.output"
```
See also
get- convert the value to a given typeBasicJsonType::get_to- the corresponding function ofbasic_json- Zero-copy JSON views - which conversions avoid building a basic_json value
Version history
- Added in version 3.13.0.