mirror of
https://github.com/nlohmann/json.git
synced 2026-10-25 15:28:54 +00:00
Add json_document and json_view: node index, parser, and document (#5620)
* Add json_document and json_view: node index, parser, and document Add json_document and json_view, a read-only, zero-copy index of a JSON text, as the first public slice of the zero-copy view (#5295). A parse produces a flat array of 16-byte nodes in document order, one per value and one per object key. Strings stay in the source text; escaped strings are decoded into an arena. Integers are converted while their digits are in the cache; floats keep only their digit layout and are converted on read. Containers store the size of their subtree, so a reader can step over one in constant time. A document makes a handful of allocations, however many values it has. The parser accepts exactly what json::parse accepts, with every combination of ignore_comments and ignore_trailing_commas, with and without a trailing NUL, and under JSON_STRICT_NUL_HANDLING. It is portable C++11 and does not depend on byte order. basic_json_document adds parse, parse_copy, accept, read (reuses a document's memory), root, is_discarded, source, owns_source, node_count, memory_usage, and shrink_to_fit. basic_json_view adds type, the is_* queries, operator bool, size, empty, materialize, and source_offset. A parse error throws the same exception basic_json::parse would throw for the same input, message and position included. detail::abi_config keeps JSON_STRICT_NUL_HANDLING and JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON readable after json.hpp undefines them, in the ABI namespace so they always match the basic_json in use. A NUL byte that ends a // comment is the end of the input, as in parse() since #5696. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix document_data for old Clang (3.4-3.6) Drop the empty braced NSDMIs of the std::string members: old Clang rejects the defaulted constructor when it is used by a member initializer before the end of the class definition. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Exclude libstdc++'s string_view comparison from the sign-change check basic_string_view::_S_compare stores the difference of two lengths in a signed difference_type on purpose, which -fsanitize=integer reports for every comparison with a shorter view (test-json_view_cpp17). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Reject integer lengths in json_document::parse parse(ptr, len) compiled: len converted to allow_exceptions, and ptr was read as a C string, past the end of a buffer without a terminating NUL. Delete the overloads of parse, parse_copy, accept, and read that take an integer other than bool where the flags are expected. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Copy const rvalue strings and document the accepted inputs json_document::parse(std::move(const_string)) failed to compile with "no matching read_kind": only a non-const rvalue std::string can be moved from. Treat a const rvalue as a copied byte container. parse() does not accept everything BasicJsonType::parse() does: a FILE* and pointers to or arrays of wide characters are rejected at compile time. List the supported inputs instead. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Remove the conversion to bool from json_view explicit operator bool meant "refers to a value", which silently differs from what a basic_json converts to. Use !v.is_discarded() instead. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Delete json_document::root() on temporary documents auto v = json_document::parse(text).root() compiled and left the view dangling. Delete the overload for rvalue documents, take a named document in the tests, and document the lifetime rule. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Store node integers by halves on big-endian targets The non-little-endian path of the node writer wrote the integer's native word over len and next, so len got the high half there. Compose and split the value explicitly (len is the low half, next the high half); the little-endian path stays a plain memcpy. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Check the node array size for overflow reserve(n) and the growth of the index computed n * sizeof(node) without a check, which wraps around on 32-bit targets for inputs of about 1 GiB and allocates a too small array. Throw std::bad_alloc for a count beyond the address space and clamp the growth step to it. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * State the exact input size limit of json_document The check rejects inputs of 0xFFFFFFF0 bytes or more, but the exception message and the documentation said 4 GiB. Name the limit once (max_input_size), and state 4 GiB minus 16 bytes in the message and the documentation. Test the limit with a container that only claims the size. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Remove the unused legacy_discarded_value_comparison from abi_config Nothing reads it: the view does not compare values. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Align the banner comment of json_view.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fuzz json_document with exact-size buffers and parse options The fuzzer only parsed a std::string with default options. Also parse an exact-size byte vector, which has no NUL after its last byte and takes the bounds-checked path, and derive ignore_comments and ignore_trailing_commas from the first input byte, comparing against json::parse and json::accept with the same options. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Give document_data a user-provided constructor Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix clang-tidy findings in unit-json_view_builder.cpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Annotate intentional patterns in unit-json_view.cpp for clang-tidy Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Suppress Flawfinder's read() finding on the deleted overload Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Check the steps of the deep-nesting test separately Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make max_input_size a function (GCC -Wunused-const-variable) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make json_view.hpp pass include-what-you-use ci_single_binaries runs IWYU with --error on every header. For json_view.hpp it suggested adding <array> (std::array is used), the headers that json.hpp already provides (abi_config, abi_macros, input_adapters, json_pointer, cpp_future, string_concat, value_t, json_fwd), and <version> for std::nullptr_t, and removing <cstddef>. - include <array> - keep <cstddef> (nullptr_t, size_t; IWYU attributes them to <version> and <cstring>) - tell IWYU not to suggest the headers that json.hpp provides: the amalgamated json_view.hpp only includes json.hpp, so including them here would duplicate their definitions - export json.hpp, keep macro_unscope.hpp, and drop the unused forward declaration of the document class Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Read the node array base after emit() in the view builder's open() emit() moves the node array when it grows, and the subtraction read base in the same expression, so the order was unspecified. MSVC Release builds without forced inlining read the old base; the container index then pointed outside the array and close() wrote out of bounds. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Silence a clang-tidy use-after-move finding in the json_view test const_text is const, so std::move does not move from it; the second call is part of the const rvalue test. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address the review of the view builder and document Changes promised in the replies to the review of #5620: - read() reuses the owned copy: a copied input (an rvalue byte container, a stream, FILE*, wide characters, an iterator range) is appended to the cleared owned buffer instead of a fresh std::string being move-assigned over it. A moved-in std::string still replaces it. - The error replay runs the library parser with a SAX handler that stores nothing and throws the reported exception, instead of BasicJsonType::parse(), which built a DOM up to the error. - Pointers to and arrays of wide characters, and FILE*, take the input adapter path (converted to UTF-8 into an owned buffer) instead of failing a static_assert. Wide pointers are NUL-terminated. - Streams are read in blocks through rdbuf() into the buffer, instead of character by character through the input adapter; eofbit is set at the end, as by the library's stream adapter. - tape/tape_size/tape_cap are now nodes/node_count/node_capacity. - The builder's members get descriptive, m_-prefixed names. - The shallow frame stack is a std::array (in a wrapper with a user-provided constructor: -Weffc++ wants the member initialized, and value-initializing the 64 frames costs up to 30 % on small documents). - The value dispatch macro has no NEXT parameter; the switch is left with break, and the macro is undefined after its last use. - literal() and digits_exceed() deduce the length from the string literal; each literal has one helper; the two `if (!is_float)` blocks are merged. - arena_ensure() sits right before the writes; the decode arena is a std::vector<char>. - The builder records the deepest nesting, and materialize() sizes its stack from it once (growing it only if a subtree is deeper). - Comment fixes (hex4, slow_string, the NUL rule, put_utf8, 0 - m, the arena resize, grow()) and formatting (macro backslashes, digit cases, one power of ten per line, value_t assertion next to is_container()). - build_with's template parameters follow the builder's order. Greg's idea of keeping the source offset in `off` and the arena offset in `next` for escaped strings was measured and not adopted: string access got 7-18 % slower with a select, and 3.5-18 % slower with a branch-free field pick (Apple M-series, clang -O3), parsing was unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Apply the review's wording fixes to the json_view documentation - Copying is disabled because of its cost, not because of two documents borrowing the same buffer; the unique_ptr follows from move-only. - Inputs: streams, FILE*, and wide characters (strings, arrays, pointers) are all supported and owned; point to parse_copy() for owned copies. - The error replay only runs for failing input, builds no values, and is skipped with allow_exceptions = false. - read() writes copied inputs into the previous owned copy. - Views can dangle like std::string_view, and why there is no shared/weak pointer design. - The 4 GiB limit (16-byte nodes, 16-byte scanner steps), streams being read to the end first, which macros apply, why materialize() has no source positions, and wording nits (accept() vs basic_json::accept(), is_binary, is_discarded, see-also lists, size table, "back into"). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say that json_view converts integers while parsing Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address the review: null inline nodes, trait spelling, and max() in json_view - inline_nodes is null when the document has no inline nodes, instead of pointing past the end of the allocation; shrink_to_fit() no longer passes it to memcpy() for an empty node array - is_byte_char and is_wide_char use conjunction/disjunction, which astyle leaves unspaced - append_stream() uses (std::max) for the count read Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Include materialize.hpp in the view builder test The test calls detail::view::materialize(), which only the single header pulled in; the multiple-header build (JSON_TEST_USING_MULTIPLE_HEADERS) failed with "'materialize' is not a member of detail::view". Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Rename emit() in the view builder for Qt compatibility Qt defines emit as an empty macro, so a Qt header included before json_view.hpp broke the declaration of the builder's emit(), see issue #5865. It is now called push_node(). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Do not copy an empty run into an unallocated arena memcpy() must not be passed a null pointer even for zero bytes, which arena_run() did for an empty run while the arena was still empty (ci_test_clang_sanitizer: "null pointer passed as argument 1" in builder.hpp). Only the slow path can see such a run. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Exclude the view builder test from Infer's reports Infer's std::unique_ptr model confuses the values that the test's build() helper returns by value and reports USE_AFTER_DELETE for one of them after the destructor of an unrelated temporary (ci_infer, 12 reports, all in tests/src/unit-json_view_builder.cpp). AddressSanitizer is clean on the same tests. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Skip the deleted-overload checks of json_view on MSVC 2015 MSVC 2015 does not treat selecting a deleted function in decltype as a substitution failure, so is_detected reports the deleted parse/parse_copy/accept/read(ptr, len) overloads as callable and the static_asserts in "integer arguments do not compile" fail (AppVeyor VS2015 jobs). Calling them still fails to compile there. Guard the negative checks as unit-delete_deprecated_functions.cpp does. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and 
GitHub committed
1 parent
a4974e72c1
commit
122d718330
146 files changed
+10787
-17
No files matched your search
@@ -0,0 +1,50 @@
|
||||
# <small>nlohmann::basic_json_view::</small>basic_json_view
|
||||
|
||||
```cpp
|
||||
basic_json_view() noexcept = default;
|
||||
```
|
||||
|
||||
Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded` and
|
||||
[`is_discarded()`](is_discarded.md) is `#!cpp true`.
|
||||
|
||||
This is the only constructor a caller can use directly. Every other view is obtained from a
|
||||
[`basic_json_document`](../basic_json_document/index.md), via [`root()`](../basic_json_document/root.md) or (once
|
||||
element access is added) from navigating into a container.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this constructor never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
`basic_json_view` is trivially copyable (it holds two pointers), so a default-constructed view can be used as a
|
||||
placeholder for "no value yet" and later be assigned a real view.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows the default constructor and that a `basic_json_view` is a small, copyable handle.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__basic_json_view.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__basic_json_view.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_discarded](is_discarded.md) - return whether the view is invalid
|
||||
- [root](../basic_json_document/root.md) - the view of a document's root value
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,61 @@
|
||||
# <small>nlohmann::basic_json_view::</small>empty
|
||||
|
||||
```cpp
|
||||
bool empty() const noexcept;
|
||||
```
|
||||
|
||||
Checks whether [`size()`](size.md) is `0`, as [`BasicJsonType::empty()`](../basic_json/empty.md) would for the same
|
||||
value.
|
||||
|
||||
## Return value
|
||||
|
||||
The return value depends on the type and is defined as follows:
|
||||
|
||||
| Value type | return value |
|
||||
|----------------------|-----------------|
|
||||
| null | `#!cpp true` |
|
||||
| discarded | `#!cpp true` |
|
||||
| boolean | `#!cpp false` |
|
||||
| string | `#!cpp false` |
|
||||
| number | `#!cpp false` |
|
||||
| object | `#!cpp object_t::empty()` |
|
||||
| array | `#!cpp array_t::empty()` |
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::empty()`](../basic_json/empty.md), this does not return whether a string value is empty -- it
|
||||
is `#!cpp false` for any string, regardless of its length.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below uses [`size()`](size.md) and `empty()` to decide whether a parsed message is worth acting on,
|
||||
without materializing it into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__size_empty.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__size_empty.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [size](size.md) - return the number of elements
|
||||
- [`BasicJsonType::empty`](../basic_json/empty.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,81 @@
|
||||
# <small>nlohmann::</small>basic_json_view
|
||||
|
||||
<small>Defined in header `<nlohmann/json_view.hpp>`</small>
|
||||
|
||||
```cpp
|
||||
template<typename BasicJsonType>
|
||||
class basic_json_view;
|
||||
```
|
||||
|
||||
A read-only handle to one value of a [`basic_json_document`](../basic_json_document/index.md): two pointers (a pointer
|
||||
to the document and a pointer into its index), trivially copyable. A view is valid as long as
|
||||
|
||||
- the document is alive,
|
||||
- the document has not been re-parsed with [`read()`](../basic_json_document/read.md) (or
|
||||
[`parse()`](../basic_json_document/parse.md) into it) or shrunk with
|
||||
[`shrink_to_fit()`](../basic_json_document/shrink_to_fit.md) since the view was taken, and
|
||||
- if the document borrows its source text, that text is still alive.
|
||||
|
||||
Moving the document itself does not invalidate its views: the index is heap-allocated independently of the
|
||||
`basic_json_document` object.
|
||||
|
||||
`basic_json_view` provides the read-only part of the `BasicJsonType` interface: the type-inspection functions, and
|
||||
[`materialize()`](materialize.md) to build the `BasicJsonType` value of a subtree on demand. It does not (yet) provide
|
||||
element access, iteration, `get<T>()`, JSON Pointer support, `dump()`, or comparison.
|
||||
|
||||
## Template parameters
|
||||
|
||||
`BasicJsonType`
|
||||
: a specialization of [`basic_json`](../basic_json/index.md), matching the
|
||||
[`basic_json_document`](../basic_json_document/index.md) the view was taken from.
|
||||
|
||||
## Specializations
|
||||
|
||||
- [**json_view**](../json_view.md) - views of a [`json_document`](../json_document.md)
|
||||
- [**ordered_json_view**](../ordered_json_view.md) - views of an [`ordered_json_document`](../ordered_json_document.md)
|
||||
|
||||
## Member types
|
||||
|
||||
- **value_t** - the JSON type enumeration, see [`basic_json::value_t`](../basic_json/value_t.md)
|
||||
- **string_t**, **number_integer_t**, **number_unsigned_t**, **number_float_t**, **json_pointer** - the corresponding
|
||||
member types of `BasicJsonType`
|
||||
- **size_type** - `#!cpp std::size_t`
|
||||
- **string_view_t** - `#!cpp std::string_view` on C++17 and newer, a minimal internal substitute otherwise
|
||||
|
||||
## Member functions
|
||||
|
||||
- [(constructor)](basic_json_view.md)
|
||||
|
||||
### Object inspection
|
||||
|
||||
- [**type**](type.md) - return the type of the value
|
||||
- [**is_null**](is_null.md) - return whether the value is null
|
||||
- [**is_boolean**](is_boolean.md) - return whether the value is a boolean
|
||||
- [**is_number**](is_number.md) - return whether the value is a number
|
||||
- [**is_number_integer**](is_number_integer.md) - return whether the value is an integer number
|
||||
- [**is_number_unsigned**](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [**is_number_float**](is_number_float.md) - return whether the value is a floating-point number
|
||||
- [**is_string**](is_string.md) - return whether the value is a string
|
||||
- [**is_array**](is_array.md) - return whether the value is an array
|
||||
- [**is_object**](is_object.md) - return whether the value is an object
|
||||
- [**is_binary**](is_binary.md) - return whether the value is a binary array (always `#!cpp false`)
|
||||
- [**is_primitive**](is_primitive.md) - return whether the type is primitive
|
||||
- [**is_structured**](is_structured.md) - return whether the type is structured
|
||||
- [**is_discarded**](is_discarded.md) - return whether the view is invalid
|
||||
|
||||
### Capacity
|
||||
|
||||
- [**size**](size.md) - return the number of elements
|
||||
- [**empty**](empty.md) - return whether the value has no elements
|
||||
|
||||
### Conversion
|
||||
|
||||
- [**materialize**](materialize.md) - build the `BasicJsonType` value of this subtree
|
||||
|
||||
### Source access
|
||||
|
||||
- [**source_offset**](source_offset.md) - byte offset of this value in the document's source text
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,47 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_array
|
||||
|
||||
```cpp
|
||||
bool is_array() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is an array.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is an array, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured
|
||||
- [size](size.md) - the number of elements
|
||||
- [empty](empty.md) - whether there are no elements
|
||||
- [`BasicJsonType::is_array`](../basic_json/is_array.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,47 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_binary
|
||||
|
||||
```cpp
|
||||
bool is_binary() const noexcept;
|
||||
```
|
||||
|
||||
This function always returns `#!cpp false`: a document is only ever parsed from JSON text, never from CBOR or the other
|
||||
binary formats, and a JSON text has no binary values, so a view can never refer to one. The function exists for
|
||||
interface parity with [`BasicJsonType::is_binary`](../basic_json/is_binary.md).
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp false`, always.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_binary`](../basic_json/is_binary.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,45 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_boolean
|
||||
|
||||
```cpp
|
||||
bool is_boolean() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is a boolean.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is a boolean, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_boolean`](../basic_json/is_boolean.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,55 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_discarded
|
||||
|
||||
```cpp
|
||||
bool is_discarded() const noexcept;
|
||||
```
|
||||
|
||||
Returns whether this view is invalid, i.e. does not refer to a value. This is the case for a default-constructed
|
||||
view (see [(constructor)](basic_json_view.md)), and for [`root()`](../basic_json_document/root.md) of a document
|
||||
that is itself [discarded](../basic_json_document/is_discarded.md) -- in particular, the root of a failed
|
||||
[`parse()`](../basic_json_document/parse.md) with `allow_exceptions` set to `#!cpp false`.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the view or its document is discarded, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
A `basic_json_view` is not convertible to `#!cpp bool`: such a conversion would mean "refers to a value", whereas
|
||||
`basic_json` converts to the `#!cpp bool` it holds, so the same code would silently behave differently. Test
|
||||
`#!cpp !v.is_discarded()` explicitly.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [(constructor)](basic_json_view.md) - the default constructor creates a discarded view
|
||||
- [is_discarded (basic_json_document)](../basic_json_document/is_discarded.md) - return whether the last parse failed
|
||||
- [`BasicJsonType::is_discarded`](../basic_json/is_discarded.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,45 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_null
|
||||
|
||||
```cpp
|
||||
bool is_null() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is `#!json null`.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is `#!json null`, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [type](type.md) - return the type of the value
|
||||
- [`BasicJsonType::is_null`](../basic_json/is_null.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,47 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_number
|
||||
|
||||
```cpp
|
||||
bool is_number() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is a number, i.e. an integer, unsigned integer, or floating-point value. It is defined as `#!cpp is_number_integer() || is_number_float()`.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is a number, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [is_number_float](is_number_float.md) - return whether the value is a floating-point number
|
||||
- [`BasicJsonType::is_number`](../basic_json/is_number.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,51 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_number_float
|
||||
|
||||
```cpp
|
||||
bool is_number_float() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is a floating-point number.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is `#!cpp value_t::number_float`, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::parse`](../basic_json/parse.md), an integer literal that does not fit into the 64-bit
|
||||
integer type is classified as a floating-point number, so `is_number_float()` can be `#!cpp true` even for an
|
||||
integer-looking token in the source text.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number](is_number.md) - return whether the value is a number
|
||||
- [`BasicJsonType::is_number_float`](../basic_json/is_number_float.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,51 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_number_integer
|
||||
|
||||
```cpp
|
||||
bool is_number_integer() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is an integer or unsigned integer number.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is `#!cpp value_t::number_integer` or `#!cpp value_t::number_unsigned`, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::is_number_integer`](../basic_json/is_number_integer.md), this includes unsigned integer
|
||||
values; use [`is_number_unsigned`](is_number_unsigned.md) to test for those specifically.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number](is_number.md) - return whether the value is a number
|
||||
- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
|
||||
- [`BasicJsonType::is_number_integer`](../basic_json/is_number_integer.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,45 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_number_unsigned
|
||||
|
||||
```cpp
|
||||
bool is_number_unsigned() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is an unsigned integer number.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is `#!cpp value_t::number_unsigned`, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
|
||||
- [`BasicJsonType::is_number_unsigned`](../basic_json/is_number_unsigned.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,47 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_object
|
||||
|
||||
```cpp
|
||||
bool is_object() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is an object.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is an object, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured
|
||||
- [size](size.md) - the number of elements
|
||||
- [empty](empty.md) - whether there are no elements
|
||||
- [`BasicJsonType::is_object`](../basic_json/is_object.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,46 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_primitive
|
||||
|
||||
```cpp
|
||||
bool is_primitive() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is primitive, i.e. `#!json null`, a boolean, a number, or a string. It is defined as `#!cpp is_null() || is_string() || is_boolean() || is_number()`.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is primitive, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_structured](is_structured.md) - return whether the type is structured (the complement of this function, for a
|
||||
non-discarded view)
|
||||
- [`BasicJsonType::is_primitive`](../basic_json/is_primitive.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,46 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_string
|
||||
|
||||
```cpp
|
||||
bool is_string() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is a string.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is a string, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [source_offset](source_offset.md) - byte offset of this value in the source text, which differs for strings: an
|
||||
escaped string has none
|
||||
- [`BasicJsonType::is_string`](../basic_json/is_string.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,46 @@
|
||||
# <small>nlohmann::basic_json_view::</small>is_structured
|
||||
|
||||
```cpp
|
||||
bool is_structured() const noexcept;
|
||||
```
|
||||
|
||||
This function returns `#!cpp true` if and only if the value is structured, i.e. an array or an object. It is defined as `#!cpp is_array() || is_object()`.
|
||||
|
||||
## Return value
|
||||
|
||||
`#!cpp true` if the type is structured, `#!cpp false` otherwise.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_primitive](is_primitive.md) - return whether the type is primitive
|
||||
- [size](size.md), [empty](empty.md) - the number of elements, and whether there are none
|
||||
- [`BasicJsonType::is_structured`](../basic_json/is_structured.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,70 @@
|
||||
# <small>nlohmann::basic_json_view::</small>materialize
|
||||
|
||||
```cpp
|
||||
BasicJsonType materialize() const;
|
||||
```
|
||||
|
||||
Builds the `BasicJsonType` value of this subtree: the value [`BasicJsonType::parse()`](../basic_json/parse.md) would
|
||||
have produced for the same source text, allocated for the first time by this call.
|
||||
|
||||
## Return value
|
||||
|
||||
The `BasicJsonType` value of this subtree, or a discarded `BasicJsonType` value (`#!cpp BasicJsonType(value_t::discarded)`)
|
||||
if the view is [discarded](is_discarded.md).
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: there are no changes to the view or the document it refers to (nothing about either is mutated by
|
||||
this function).
|
||||
|
||||
## Exceptions
|
||||
|
||||
May throw `#!cpp std::bad_alloc` (via `BasicJsonType`'s allocator) if constructing the result fails.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the size of the subtree.
|
||||
|
||||
## Notes
|
||||
|
||||
`materialize()` replays the subtree through the same SAX builder [`BasicJsonType::parse()`](../basic_json/parse.md)
|
||||
uses, so the result matches it exactly -- including, for an object, that a repeated key keeps only its
|
||||
last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion
|
||||
would be; the JSON nesting depth is limited only by available memory, as for `BasicJsonType::parse()` itself.
|
||||
|
||||
Unlike parsing with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) enabled, the values
|
||||
produced by `materialize()` do not carry source positions. The index has the start offset of every value, but not the
|
||||
end of arrays, objects, and escaped strings, which the positions also need.
|
||||
|
||||
Calling `materialize()` on the same view repeatedly builds a new, independent `BasicJsonType` value each time; it
|
||||
never caches the result.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below skips messages that are not useful -- a discarded value, or an empty array -- using only
|
||||
[`is_array()`](is_array.md) and [`empty()`](empty.md), and calls `materialize()` only for the messages that are
|
||||
actually used, so no `BasicJsonType` value (and none of its per-element allocations) is ever built for the
|
||||
skipped ones.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__materialize.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__materialize.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [root](../basic_json_document/root.md) - the view of a document's root value
|
||||
- [`BasicJsonType::parse`](../basic_json/parse.md) - build a `BasicJsonType` value directly from a JSON text
|
||||
- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values (not
|
||||
produced by `materialize()`)
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,60 @@
|
||||
# <small>nlohmann::basic_json_view::</small>size
|
||||
|
||||
```cpp
|
||||
size_type size() const noexcept;
|
||||
```
|
||||
|
||||
Returns the number of elements, as [`BasicJsonType::size()`](../basic_json/size.md) would for the same value.
|
||||
|
||||
## Return value
|
||||
|
||||
The return value depends on the type and is defined as follows:
|
||||
|
||||
| Value type | return value |
|
||||
|------------|---------------------------|
|
||||
| null | `0` |
|
||||
| discarded | `0` |
|
||||
| boolean | `1` |
|
||||
| string | `1` |
|
||||
| number | `1` |
|
||||
| object | number of key/value pairs |
|
||||
| array | number of elements |
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant: for an object or array, the element count is stored in the index, not counted on demand.
|
||||
|
||||
## Notes
|
||||
|
||||
As for [`BasicJsonType::size()`](../basic_json/size.md), this does not return the length of a string value -- it is
|
||||
`1` for a string, regardless of its length.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below uses `size()` and [`empty()`](empty.md) to decide whether a parsed message is worth acting on,
|
||||
without materializing it into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__size_empty.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__size_empty.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [empty](empty.md) - return whether the value has no elements
|
||||
- [`BasicJsonType::size`](../basic_json/size.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,55 @@
|
||||
# <small>nlohmann::basic_json_view::</small>source_offset
|
||||
|
||||
```cpp
|
||||
std::size_t source_offset() const noexcept;
|
||||
```
|
||||
|
||||
Returns the byte offset of this value in the document's [`source()`](../basic_json_document/source.md) text, without
|
||||
materializing anything.
|
||||
|
||||
## Return value
|
||||
|
||||
- For a string with no escapes, a number, `#!json true`/`#!json false`/`#!json null`, an array, or an object: the
|
||||
byte offset of the first byte of the value's token (for a string: the first byte after the opening quote) in
|
||||
[`source()`](../basic_json_document/source.md).
|
||||
- `#!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.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
This is a raw offset, not a length: the API does not (yet) expose how many bytes the token occupies in the source
|
||||
text, so `source_offset()` alone is enough to report *where* a value came from (for an error message, for syntax
|
||||
highlighting, ...) but not to slice its exact text back out of [`source()`](../basic_json_document/source.md) for a
|
||||
string, whose token length is not the same as its decoded [`size()`](size.md).
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__source_offset.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__source_offset.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [source](../basic_json_document/source.md) - the parsed text
|
||||
- [is_string](is_string.md) - return whether the value is a string
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -0,0 +1,53 @@
|
||||
# <small>nlohmann::basic_json_view::</small>type
|
||||
|
||||
```cpp
|
||||
value_t type() const noexcept;
|
||||
```
|
||||
|
||||
Returns the type of the value this view refers to, as a value from the [`value_t`](../basic_json/value_t.md)
|
||||
enumeration -- the same enumeration [`BasicJsonType::type()`](../basic_json/type.md) uses.
|
||||
|
||||
## Return value
|
||||
|
||||
The type of the value; `#!cpp value_t::discarded` for a [discarded](is_discarded.md) view.
|
||||
|
||||
## Exception safety
|
||||
|
||||
No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant.
|
||||
|
||||
## Notes
|
||||
|
||||
Unlike [`BasicJsonType::type()`](../basic_json/type.md), this function can never return `#!cpp value_t::binary`: a
|
||||
JSON text has no binary values, so `type()` only distinguishes the eight ordinary JSON value types (plus
|
||||
`#!cpp discarded`).
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below classifies several parsed documents by the type of their root value, without materializing any
|
||||
of them into a `BasicJsonType` value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json_view__type_predicates.cpp"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json_view__type_predicates.output"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_null](is_null.md), [is_boolean](is_boolean.md), [is_number](is_number.md), [is_string](is_string.md),
|
||||
[is_array](is_array.md), [is_object](is_object.md) - type-specific predicates built on `type()`
|
||||
- [`BasicJsonType::type`](../basic_json/type.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
Reference in new issue
Block a user