A JSON element. More...

#include <element.h>

Public Member Functions
simdjson_inline	element () noexcept
	Create a new, invalid element.

simdjson_inline element_type	type () const noexcept
	The type of this element.

simdjson_result< array >	get_array () const noexcept
	Cast this element to an array.

simdjson_result< object >	get_object () const noexcept
	Cast this element to an object.

simdjson_result< const char * >	get_c_str () const noexcept
	Cast this element to a null-terminated C string.

simdjson_result< size_t >	get_string_length () const noexcept
	Gives the length in bytes of the string.

simdjson_result< std::string_view >	get_string () const noexcept
	Cast this element to a string.

simdjson_result< int64_t >	get_int64 () const noexcept
	Cast this element to a signed integer.

simdjson_result< uint64_t >	get_uint64 () const noexcept
	Cast this element to an unsigned integer.

simdjson_result< double >	get_double () const noexcept
	Cast this element to a double floating-point.

simdjson_result< bool >	get_bool () const noexcept
	Cast this element to a bool.

bool	is_array () const noexcept
	Whether this element is a json array.

bool	is_object () const noexcept
	Whether this element is a json object.

bool	is_string () const noexcept
	Whether this element is a json string.

bool	is_int64 () const noexcept
	Whether this element is a json number that fits in a signed 64-bit integer.

bool	is_uint64 () const noexcept
	Whether this element is a json number that fits in an unsigned 64-bit integer.

bool	is_double () const noexcept
	Whether this element is a json number that fits in a double.

bool	is_number () const noexcept
	Whether this element is a json number.

bool	is_bool () const noexcept
	Whether this element is a json `true` or `false`.

bool	is_null () const noexcept
	Whether this element is a json `null`.

template<typename T >
simdjson_inline bool	is () const noexcept
	Tell whether the value can be cast to provided type (T).

template<typename T >
simdjson_result< T >	get () const noexcept
	Get the value as the provided type (T).

template<typename T >
simdjson_warn_unused simdjson_inline error_code	get (T &value) const noexcept
	Get the value as the provided type (T).

template<typename T >
void	tie (T &value, error_code &error) &&noexcept
	Get the value as the provided type (T), setting error if it's not the given type.

	operator bool () const noexcept(false)
	Read this element as a boolean.

	operator const char * () const noexcept(false)
	Read this element as a null-terminated UTF-8 string.

	operator std::string_view () const noexcept(false)
	Read this element as a null-terminated UTF-8 string.

	operator uint64_t () const noexcept(false)
	Read this element as an unsigned integer.

	operator int64_t () const noexcept(false)
	Read this element as an signed integer.

	operator double () const noexcept(false)
	Read this element as an double.

	operator array () const noexcept(false)
	Read this element as a JSON array.

	operator object () const noexcept(false)
	Read this element as a JSON object (key/value pairs).

dom::array::iterator	begin () const noexcept(false)
	Iterate over each element in this array.

dom::array::iterator	end () const noexcept(false)
	Iterate over each element in this array.

simdjson_result< element >	operator[] (std::string_view key) const noexcept
	Get the value associated with the given key.

simdjson_result< element >	operator[] (const char *key) const noexcept
	Get the value associated with the given key.

simdjson_result< element >	operator[] (int) const noexcept=delete

simdjson_result< element >	at_pointer (const std::string_view json_pointer) const noexcept
	Get the value associated with the given JSON pointer.

simdjson_result< std::vector< element > >	at_path_with_wildcard (const std::string_view json_path) const noexcept

simdjson_result< element >	at_path (std::string_view json_path) const noexcept
	Get the value associated with the given JSONPath expression.

simdjson_result< element >	at (const std::string_view json_pointer) const noexcept
	Version 0.4 of simdjson used an incorrect interpretation of the JSON Pointer standard and allowed the following :

simdjson_result< element >	at (size_t index) const noexcept
	Get the value at the given index.

simdjson_result< element >	at_key (std::string_view key) const noexcept
	Get the value associated with the given key.

simdjson_result< element >	at_key_case_insensitive (std::string_view key) const noexcept
	Get the value associated with the given key in a case-insensitive manner.

bool	operator< (const element &other) const noexcept
	operator< defines a total order for element allowing to use them in ordered C++ STL containers

bool	operator== (const element &other) const noexcept
	operator== allows to verify if two element values reference the same JSON item

template<>
simdjson_warn_unused simdjson_inline error_code	get (element &value) const noexcept

template<>
simdjson_result< array >	get () const noexcept

template<>
simdjson_result< object >	get () const noexcept

template<>
simdjson_result< const char * >	get () const noexcept

template<>
simdjson_result< int64_t >	get () const noexcept

template<>
simdjson_result< uint64_t >	get () const noexcept

template<>
simdjson_result< double >	get () const noexcept

template<>
simdjson_result< bool >	get () const noexcept

Detailed Description

A JSON element.

References an element in a JSON document, representing a JSON null, boolean, string, number, array or object.

Definition at line 33 of file element.h.

Constructor & Destructor Documentation

◆ element()

simdjson_inline simdjson::dom::element::element ( )

noexcept

Create a new, invalid element.

Definition at line 203 of file element-inl.h.

Member Function Documentation

◆ at() [1/2]

simdjson_result< element > simdjson::dom::element::at ( const std::string_view json_pointer ) const

inlinenoexcept

Version 0.4 of simdjson used an incorrect interpretation of the JSON Pointer standard and allowed the following :

dom::parser parser; element doc = parser.parse(R"({ "foo": { "a": [ 10, 20, 30 ] }})"_padded); doc.at("foo/a/1") == 20

Though it is intuitive, it is not compliant with RFC 6901 https://tools.ietf.org/html/rfc6901

For standard compliance, use the at_pointer function instead.

Returns

The value associated with the given JSON pointer, or:

NO_SUCH_FIELD if a field does not exist in an object
INDEX_OUT_OF_BOUNDS if an array index is larger than an array length
INCORRECT_TYPE if a non-integer is used to access an array
INVALID_JSON_POINTER if the JSON pointer is invalid and cannot be parsed

Definition at line 448 of file element-inl.h.

◆ at() [2/2]

simdjson_result< element > simdjson::dom::element::at ( size_t index ) const

inlinenoexcept

Get the value at the given index.

Returns

The value at the given index, or:

INDEX_OUT_OF_BOUNDS if the array index is larger than an array length

Definition at line 455 of file element-inl.h.

◆ at_key()

simdjson_result< element > simdjson::dom::element::at_key ( std::string_view key ) const

inlinenoexcept

Get the value associated with the given key.

The key will be matched against unescaped JSON:

dom::parser parser; int64_t(parser.parse(R"({ "a
": 1 })"_padded)["a\n"]) == 1 parser.parse(R"({ "a
": 1 })"_padded)["a\\n"].get_uint64().error() == NO_SUCH_FIELD

Returns

The value associated with this field, or:

NO_SUCH_FIELD if the field does not exist in the object

Definition at line 458 of file element-inl.h.

◆ at_key_case_insensitive()

simdjson_result< element > simdjson::dom::element::at_key_case_insensitive ( std::string_view key ) const

inlinenoexcept

Get the value associated with the given key in a case-insensitive manner.

Note: The key will be matched against unescaped JSON.

Returns

The value associated with this field, or:

NO_SUCH_FIELD if the field does not exist in the object

Definition at line 461 of file element-inl.h.

◆ at_path()

simdjson_result< element > simdjson::dom::element::at_path ( std::string_view json_path ) const

inlinenoexcept

Get the value associated with the given JSONPath expression.

We only support JSONPath queries that trivially convertible to JSON Pointer queries: key names and array indices.

https://www.rfc-editor.org/rfc/rfc9535 (RFC 9535)

Returns

The value associated with the given JSONPath expression, or:

INVALID_JSON_POINTER if the JSONPath to JSON Pointer conversion fails
NO_SUCH_FIELD if a field does not exist in an object
INDEX_OUT_OF_BOUNDS if an array index is larger than an array length
INCORRECT_TYPE if a non-integer is used to access an array

Definition at line 441 of file element-inl.h.

◆ at_path_with_wildcard()

simdjson_result< std::vector< element > > simdjson::dom::element::at_path_with_wildcard ( const std::string_view json_path ) const

inlinenoexcept

Definition at line 428 of file element-inl.h.

◆ at_pointer()

simdjson_result< element > simdjson::dom::element::at_pointer ( const std::string_view json_pointer ) const

inlinenoexcept

Get the value associated with the given JSON pointer.

We use the RFC 6901 https://tools.ietf.org/html/rfc6901 standard.

dom::parser parser; element doc = parser.parse(R"({ "foo": { "a": [ 10, 20, 30 ] }})"_padded); doc.at_pointer("/foo/a/1") == 20 doc.at_pointer("/foo")["a"].at(1) == 20 doc.at_pointer("")["foo"]["a"].at(1) == 20

It is allowed for a key to be the empty string:

dom::parser parser; object obj = parser.parse(R"({ "": { "a": [ 10, 20, 30 ] }})"_padded); obj.at_pointer("//a/1") == 20

Returns

The value associated with the given JSON pointer, or:

NO_SUCH_FIELD if a field does not exist in an object
INDEX_OUT_OF_BOUNDS if an array index is larger than an array length
INCORRECT_TYPE if a non-integer is used to access an array
INVALID_JSON_POINTER if the JSON pointer is invalid and cannot be parsed

Definition at line 407 of file element-inl.h.

◆ begin()

array::iterator simdjson::dom::element::begin ( ) const

inline

Iterate over each element in this array.

Returns: The beginning of the iteration.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not an array

Definition at line 374 of file element-inl.h.

◆ end()

array::iterator simdjson::dom::element::end ( ) const

inline

Iterate over each element in this array.

Returns: The end of the iteration.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not an array

Definition at line 377 of file element-inl.h.

◆ get() [1/10]

template<>

simdjson_result< bool > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [2/10]

template<>

simdjson_result< array > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [3/10]

template<>

simdjson_result< object > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [4/10]

template<>

simdjson_result< const char * > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [5/10]

template<>

simdjson_result< int64_t > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [6/10]

template<>

simdjson_result< uint64_t > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [7/10]

template<>

simdjson_result< double > simdjson::dom::element::get ( ) const

inlinenoexcept

Definition at line 336 of file element-inl.h.

◆ get() [8/10]

template<typename T >

simdjson_result< T > simdjson::dom::element::get ( ) const

inlinenoexcept

Get the value as the provided type (T).

Supported types:

Boolean: bool
Number: double, uint64_t, int64_t
String: std::string_view, const char *
Array: dom::array
Object: dom::object

You may use get_double(), get_bool(), get_uint64(), get_int64(), get_object(), get_array() or get_string() instead.

Template Parameters

T	bool, double, uint64_t, int64_t, std::string_view, const char *, dom::array, dom::object

Returns: The value cast to the given type, or: INCORRECT_TYPE if the value cannot be cast to the given type.

Definition at line 213 of file element.h.

◆ get() [9/10]

template<>

simdjson_warn_unused simdjson_inline error_code simdjson::dom::element::get ( element & value ) const

noexcept

Definition at line 326 of file element-inl.h.

◆ get() [10/10]

template<typename T >

simdjson_warn_unused simdjson_inline error_code simdjson::dom::element::get ( T & value ) const

noexcept

Get the value as the provided type (T).

Supported types:

Boolean: bool
Number: double, uint64_t, int64_t
String: std::string_view, const char *
Array: dom::array
Object: dom::object

Template Parameters

T	bool, double, uint64_t, int64_t, std::string_view, const char *, dom::array, dom::object

Parameters

value The variable to set to the value. May not be set if there is an error.

Returns: The error that occurred, or SUCCESS if there was no error.

Definition at line 321 of file element-inl.h.

◆ get_array()

simdjson_result< array > simdjson::dom::element::get_array ( ) const

inlinenoexcept

Cast this element to an array.

Returns: An object that can be used to iterate the array, or: INCORRECT_TYPE if the JSON element is not an array.

Definition at line 301 of file element-inl.h.

◆ get_bool()

simdjson_result< bool > simdjson::dom::element::get_bool ( ) const

inlinenoexcept

Cast this element to a bool.

Returns: A bool value. Returns INCORRECT_TYPE if the JSON element is not a boolean.

Definition at line 212 of file element-inl.h.

◆ get_c_str()

simdjson_result< const char * > simdjson::dom::element::get_c_str ( ) const

inlinenoexcept

Cast this element to a null-terminated C string.

The string is guaranteed to be valid UTF-8.

The length of the string is given by get_string_length(). Because JSON strings may contain null characters, it may be incorrect to use strlen to determine the string length.

It is possible to get a single string_view instance which represents both the string content and its length: see get_string().

Returns: A pointer to a null-terminated UTF-8 string. This string is stored in the parser and will be invalidated the next time it parses a document or when it is destroyed. Returns INCORRECT_TYPE if the JSON element is not a string.

Definition at line 221 of file element-inl.h.

◆ get_double()

simdjson_result< double > simdjson::dom::element::get_double ( ) const

inlinenoexcept

Cast this element to a double floating-point.

Returns: A double value. Returns INCORRECT_TYPE if the JSON element is not a number.

Definition at line 279 of file element-inl.h.

◆ get_int64()

simdjson_result< int64_t > simdjson::dom::element::get_int64 ( ) const

inlinenoexcept

Cast this element to a signed integer.

Returns: A signed 64-bit integer. Returns INCORRECT_TYPE if the JSON element is not an integer, or NUMBER_OUT_OF_RANGE if it is negative.

Definition at line 264 of file element-inl.h.

◆ get_object()

simdjson_result< object > simdjson::dom::element::get_object ( ) const

inlinenoexcept

Cast this element to an object.

Returns: An object that can be used to look up or iterate the object's fields, or: INCORRECT_TYPE if the JSON element is not an object.

Definition at line 310 of file element-inl.h.

◆ get_string()

simdjson_result< std::string_view > simdjson::dom::element::get_string ( ) const

inlinenoexcept

Cast this element to a string.

The string is guaranteed to be valid UTF-8.

Returns: An UTF-8 string. The string is stored in the parser and will be invalidated the next time it parses a document or when it is destroyed. Returns INCORRECT_TYPE if the JSON element is not a string.

Definition at line 241 of file element-inl.h.

◆ get_string_length()

simdjson_result< size_t > simdjson::dom::element::get_string_length ( ) const

inlinenoexcept

Gives the length in bytes of the string.

It is possible to get a single string_view instance which represents both the string content and its length: see get_string().

Returns: A string length in bytes. Returns INCORRECT_TYPE if the JSON element is not a string.

Definition at line 231 of file element-inl.h.

◆ get_uint64()

simdjson_result< uint64_t > simdjson::dom::element::get_uint64 ( ) const

inlinenoexcept

Cast this element to an unsigned integer.

Returns: An unsigned 64-bit integer. Returns INCORRECT_TYPE if the JSON element is not an integer, or NUMBER_OUT_OF_RANGE if it is too large.

Definition at line 250 of file element-inl.h.

◆ is()

template<typename T >

simdjson_inline bool simdjson::dom::element::is ( ) const

noexcept

Tell whether the value can be cast to provided type (T).

Supported types:

Boolean: bool
Number: double, uint64_t, int64_t
String: std::string_view, const char *
Array: dom::array
Object: dom::object

Template Parameters

T	bool, double, uint64_t, int64_t, std::string_view, const char *, dom::array, dom::object

Definition at line 336 of file element-inl.h.

◆ is_array()

bool simdjson::dom::element::is_array ( ) const

inlinenoexcept

Whether this element is a json array.

Equivalent to is<array>().

Definition at line 350 of file element-inl.h.

◆ is_bool()

bool simdjson::dom::element::is_bool ( ) const

inlinenoexcept

Whether this element is a json true or false.

Equivalent to is<bool>().

Definition at line 356 of file element-inl.h.

◆ is_double()

bool simdjson::dom::element::is_double ( ) const

inlinenoexcept

Whether this element is a json number that fits in a double.

Equivalent to is<double>().

Definition at line 355 of file element-inl.h.

◆ is_int64()

bool simdjson::dom::element::is_int64 ( ) const

inlinenoexcept

Whether this element is a json number that fits in a signed 64-bit integer.

Equivalent to is<int64_t>().

Definition at line 353 of file element-inl.h.

◆ is_null()

bool simdjson::dom::element::is_null ( ) const

inlinenoexcept

Whether this element is a json null.

Definition at line 359 of file element-inl.h.

◆ is_number()

bool simdjson::dom::element::is_number ( ) const

inlinenoexcept

Whether this element is a json number.

Both integers and floating points will return true.

Definition at line 357 of file element-inl.h.

◆ is_object()

bool simdjson::dom::element::is_object ( ) const

inlinenoexcept

Whether this element is a json object.

Equivalent to is<object>().

Definition at line 351 of file element-inl.h.

◆ is_string()

bool simdjson::dom::element::is_string ( ) const

inlinenoexcept

Whether this element is a json string.

Equivalent to is<std::string_view>() or is<const char *>().

Definition at line 352 of file element-inl.h.

◆ is_uint64()

bool simdjson::dom::element::is_uint64 ( ) const

inlinenoexcept

Whether this element is a json number that fits in an unsigned 64-bit integer.

Equivalent to is<uint64_t>().

Definition at line 354 of file element-inl.h.

◆ operator array()

simdjson::dom::element::operator array ( ) const

inline

Read this element as a JSON array.

Returns: The JSON array.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not an array

Definition at line 371 of file element-inl.h.

◆ operator bool()

simdjson::dom::element::operator bool ( ) const

inline

Read this element as a boolean.

Returns: The boolean value

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not a boolean.

Definition at line 365 of file element-inl.h.

◆ operator const char *()

simdjson::dom::element::operator const char * ( ) const

inlineexplicit

Read this element as a null-terminated UTF-8 string.

Be mindful that JSON allows strings to contain null characters.

Does not convert other types to a string; requires that the JSON type of the element was an actual string.

Returns: The string value.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not a string.

Definition at line 366 of file element-inl.h.

◆ operator double()

simdjson::dom::element::operator double ( ) const

inline

Read this element as an double.

Returns: The double value.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not a number

Definition at line 370 of file element-inl.h.

◆ operator int64_t()

simdjson::dom::element::operator int64_t ( ) const

inline

Read this element as an signed integer.

Returns: The integer value.

Exceptions

simdjson_error(INCORRECT_TYPE)	if the JSON element is not an integer
simdjson_error(NUMBER_OUT_OF_RANGE)	if the integer does not fit in 64 bits

Definition at line 369 of file element-inl.h.

◆ operator object()

simdjson::dom::element::operator object ( ) const

inline

Read this element as a JSON object (key/value pairs).

Returns: The JSON object.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not an object

Definition at line 372 of file element-inl.h.

◆ operator std::string_view()

simdjson::dom::element::operator std::string_view ( ) const

inline

Read this element as a null-terminated UTF-8 string.

Does not convert other types to a string; requires that the JSON type of the element was an actual string.

Returns: The string value.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON element is not a string.

Definition at line 367 of file element-inl.h.

◆ operator uint64_t()

simdjson::dom::element::operator uint64_t ( ) const

inline

Read this element as an unsigned integer.

Returns: The integer value.

Exceptions

simdjson_error(INCORRECT_TYPE)	if the JSON element is not an integer
simdjson_error(NUMBER_OUT_OF_RANGE)	if the integer does not fit in 64 bits or is negative

Definition at line 368 of file element-inl.h.

◆ operator<()

bool simdjson::dom::element::operator< ( const element & other ) const

inlinenoexcept

operator< defines a total order for element allowing to use them in ordered C++ STL containers

Returns: TRUE if the key appears before the other one in the tape

Definition at line 464 of file element-inl.h.

◆ operator==()

bool simdjson::dom::element::operator== ( const element & other ) const

inlinenoexcept

operator== allows to verify if two element values reference the same JSON item

Returns: TRUE if the two values references the same JSON element

Definition at line 467 of file element-inl.h.

◆ operator[]() [1/2]

simdjson_result< element > simdjson::dom::element::operator[] ( const char * key ) const

inlinenoexcept

Get the value associated with the given key.

The key will be matched against unescaped JSON:

dom::parser parser; int64_t(parser.parse(R"({ "a
": 1 })"_padded)["a\n"]) == 1 parser.parse(R"({ "a
": 1 })"_padded)["a\\n"].get_uint64().error() == NO_SUCH_FIELD

Returns

The value associated with this field, or:

NO_SUCH_FIELD if the field does not exist in the object
INCORRECT_TYPE if this is not an object

Definition at line 386 of file element-inl.h.

◆ operator[]() [2/2]

simdjson_result< element > simdjson::dom::element::operator[] ( std::string_view key ) const

inlinenoexcept

Get the value associated with the given key.

The key will be matched against unescaped JSON:

dom::parser parser; int64_t(parser.parse(R"({ "a
": 1 })"_padded)["a\n"]) == 1 parser.parse(R"({ "a
": 1 })"_padded)["a\\n"].get_uint64().error() == NO_SUCH_FIELD

Returns

The value associated with this field, or:

NO_SUCH_FIELD if the field does not exist in the object
INCORRECT_TYPE if this is not an object

Definition at line 383 of file element-inl.h.

◆ tie()

template<typename T >

void simdjson::dom::element::tie	(	T &	value,
		error_code &	error
	)		&&

inlinenoexcept

Get the value as the provided type (T), setting error if it's not the given type.

Supported types:

Boolean: bool
Number: double, uint64_t, int64_t
String: std::string_view, const char *
Array: dom::array
Object: dom::object

Template Parameters

T	bool, double, uint64_t, int64_t, std::string_view, const char *, dom::array, dom::object

Parameters

value	The variable to set to the given type. value is undefined if there is an error.
error	The variable to store the error. error is set to error_code::SUCCEED if there is an error.

Definition at line 331 of file element-inl.h.

◆ type()

element_type simdjson::dom::element::type ( ) const

inlinenoexcept

The type of this element.

Definition at line 206 of file element-inl.h.

The documentation for this class was generated from the following files:

include/simdjson/dom/element.h
include/simdjson/dom/element-inl.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ element()

Member Function Documentation

◆ at() [1/2]

◆ at() [2/2]

◆ at_key()

◆ at_key_case_insensitive()

◆ at_path()

◆ at_path_with_wildcard()

◆ at_pointer()

◆ begin()

◆ end()

◆ get() [1/10]

◆ get() [2/10]

◆ get() [3/10]

◆ get() [4/10]

◆ get() [5/10]

◆ get() [6/10]

◆ get() [7/10]

◆ get() [8/10]

◆ get() [9/10]

◆ get() [10/10]

◆ get_array()

◆ get_bool()

◆ get_c_str()

◆ get_double()

◆ get_int64()

◆ get_object()

◆ get_string()

◆ get_string_length()

◆ get_uint64()

◆ is()

◆ is_array()

◆ is_bool()

◆ is_double()

◆ is_int64()

◆ is_null()

◆ is_number()

◆ is_object()

◆ is_string()

◆ is_uint64()

◆ operator array()

◆ operator bool()

◆ operator const char *()

◆ operator double()

◆ operator int64_t()

◆ operator object()

◆ operator std::string_view()

◆ operator uint64_t()

◆ operator<()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ tie()

◆ type()