Niels Lohmann
43e2d9c525
- API pages for get, get_to, get_string, number_token, and value of basic_json_view; JSON pointer overloads of operator[], at, and contains; links both ways with the basic_json pages - the feature page describes which conversions copy nothing - the examples show when the view helps: strings without copies, numbers exactly as written, and paths into a large text Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.0 KiB
nlohmann::basic_json_view::number_token
string_view_t number_token() const;
Returns the number exactly as it appears in the source text, without parsing or rounding it.
Return value
The number's token text, as a string_view_t into the document's
source() text -- for example #!cpp "1.50", #!cpp "1E2", #!cpp "-0", or an
integer literal with more digits than any number type holds (such as a 30-digit integer, which get<T>()
and materialize() can only represent approximately, as a number_float_t).
Exception safety
Strong exception safety: if an exception is thrown, there are no changes to the view or the document it refers to.
Exceptions
Throws type_error.302 if the value is not a number; example:
"type must be number, but is string".
This exception does not carry a JSON_DIAGNOSTICS path: the view has no
BasicJsonType value to point at, so the exception is created without one, even if BasicJsonType was built with
JSON_DIAGNOSTICS enabled.
Complexity
Constant.
Notes
BasicJsonType has no counterpart to this function: once a number is parsed into number_integer_t,
number_unsigned_t, or number_float_t, its original textual form (leading zeros aside, which are already rejected
by the grammar; trailing zeros in the fraction; the case and sign of the exponent; ...) is gone. number_token() is
useful precisely where that form must survive -- a price or an identifier that must be reproduced exactly, or a
number too large for any of BasicJsonType's number types to hold without loss.
The returned string_view_t always points into the document's
source() text -- numbers are never decoded into the document's separate string
buffer -- and is valid exactly as long as that text is, see the validity rules of basic_json_view.
Examples
??? example
The example below keeps a price and an order ID exactly as they were written in an incoming order, where
converting them with [`get<T>()`](get.md) would lose information: the price picks up floating-point rounding, and
the order ID -- more digits than a 64-bit integer holds -- can only be approximated as a `#!cpp double` once
`#!cpp materialize()`d.
```cpp
--8<-- "examples/basic_json_view__number_token.cpp"
```
Output:
```json
--8<-- "examples/basic_json_view__number_token.output"
```
See also
- get - convert the value to a given type
- get_string - the string, without a copy
BasicJsonType::number_integer_t,number_unsigned_t,number_float_t- the number types#!cpp get<T>()andmaterialize()convert into
Version history
- Added in version 3.13.0.