A JSON document. More...

#include <document.h>

Public Member Functions
simdjson_inline	document () noexcept=default
	Create a new invalid document.

simdjson_inline	document (const document &other) noexcept=delete

simdjson_inline	document (document &&other) noexcept=default

simdjson_inline document &	operator= (const document &other) noexcept=delete

simdjson_inline document &	operator= (document &&other) noexcept=default

simdjson_inline simdjson_result< array >	get_array () &noexcept
	Cast this JSON value to an array.

simdjson_inline simdjson_result< object >	get_object () &noexcept
	Cast this JSON value to an object.

simdjson_inline simdjson_result< uint64_t >	get_uint64 () noexcept
	Cast this JSON value to an unsigned integer.

simdjson_inline simdjson_result< uint64_t >	get_uint64_in_string () noexcept
	Cast this JSON value (inside string) to an unsigned integer.

simdjson_inline simdjson_result< int64_t >	get_int64 () noexcept
	Cast this JSON value to a signed integer.

simdjson_inline simdjson_result< int64_t >	get_int64_in_string () noexcept
	Cast this JSON value (inside string) to a signed integer.

simdjson_inline simdjson_result< uint32_t >	get_uint32 () noexcept
	Cast this JSON value to a 32-bit unsigned integer.

simdjson_inline simdjson_result< int32_t >	get_int32 () noexcept
	Cast this JSON value to a 32-bit signed integer.

simdjson_inline simdjson_result< double >	get_double () noexcept
	Cast this JSON value to a double.

simdjson_inline simdjson_result< double >	get_double_in_string () noexcept
	Cast this JSON value (inside string) to a double.

simdjson_inline simdjson_result< std::string_view >	get_string (bool allow_replacement=false) noexcept
	Cast this JSON value to a string.

template<typename string_type >
simdjson_warn_unused simdjson_inline error_code	get_string (string_type &receiver, bool allow_replacement=false) noexcept
	Attempts to fill the provided std::string reference with the parsed value of the current string.

simdjson_inline simdjson_result< std::string_view >	get_wobbly_string () noexcept
	Cast this JSON value to a string.

simdjson_inline simdjson_result< raw_json_string >	get_raw_json_string () noexcept
	Cast this JSON value to a raw_json_string.

simdjson_inline simdjson_result< bool >	get_bool () noexcept
	Cast this JSON value to a bool.

simdjson_inline simdjson_result< value >	get_value () noexcept
	Cast this JSON value to a value when the document is an object or an array.

simdjson_inline simdjson_result< bool >	is_null () noexcept
	Checks if this JSON value is null.

template<typename T >
simdjson_inline simdjson_result< T >	get () &noexcept
	Get this value as the given type.

template<typename T >
simdjson_inline simdjson_result< T >	get () &&noexcept

template<typename T >
simdjson_warn_unused simdjson_inline error_code	get (T &out) &noexcept
	Get this value as the given type.

template<typename T >
simdjson_deprecated simdjson_inline error_code	get (T &out) &&noexcept

template<class T >
simdjson_inline	operator T () &noexcept(false)
	Cast this JSON value to an instance of type T.

template<class T >
simdjson_deprecated simdjson_inline	operator T () &&noexcept(false)

simdjson_inline	operator array () &noexcept(false)
	Cast this JSON value to an array.

simdjson_inline	operator object () &noexcept(false)
	Cast this JSON value to an object.

simdjson_inline	operator uint64_t () noexcept(false)
	Cast this JSON value to an unsigned integer.

simdjson_inline	operator int64_t () noexcept(false)
	Cast this JSON value to a signed integer.

simdjson_inline	operator double () noexcept(false)
	Cast this JSON value to a double.

simdjson_inline	operator std::string_view () noexcept(false) simdjson_lifetime_bound
	Cast this JSON value to a string.

simdjson_inline	operator raw_json_string () noexcept(false) simdjson_lifetime_bound
	Cast this JSON value to a raw_json_string.

simdjson_inline	operator bool () noexcept(false)
	Cast this JSON value to a bool.

simdjson_inline	operator value () noexcept(false)
	Cast this JSON value to a value when the document is an object or an array.

simdjson_inline simdjson_result< size_t >	count_elements () &noexcept
	This method scans the array and counts the number of elements.

simdjson_inline simdjson_result< size_t >	count_fields () &noexcept
	This method scans the object and counts the number of key-value pairs.

simdjson_inline simdjson_result< value >	at (size_t index) &noexcept
	Get the value at the given index in the array.

simdjson_inline simdjson_result< array_iterator >	begin () &noexcept
	Begin array iteration.

simdjson_inline simdjson_result< array_iterator >	end () &noexcept
	Sentinel representing the end of the array.

simdjson_inline simdjson_result< value >	find_field (std::string_view key) &noexcept
	Look up a field by name on an object (order-sensitive).

simdjson_inline simdjson_result< value >	find_field (const char *key) &noexcept

simdjson_inline simdjson_result< value >	find_field_unordered (std::string_view key) &noexcept
	Look up a field by name on an object, without regard to key order.

simdjson_inline simdjson_result< value >	find_field_unordered (const char *key) &noexcept

simdjson_inline simdjson_result< value >	operator[] (std::string_view key) &noexcept

simdjson_inline simdjson_result< value >	operator[] (const char *key) &noexcept

simdjson_result< value >	operator[] (int) &noexcept=delete

simdjson_inline simdjson_result< json_type >	type () noexcept
	Get the type of this JSON value.

simdjson_inline simdjson_result< bool >	is_scalar () noexcept
	Checks whether the document is a scalar (string, number, null, Boolean).

simdjson_inline simdjson_result< bool >	is_string () noexcept
	Checks whether the document is a string.

simdjson_inline bool	is_negative () noexcept
	Checks whether the document is a negative number.

simdjson_inline simdjson_result< bool >	is_integer () noexcept
	Checks whether the document is an integer number.

simdjson_inline simdjson_result< number_type >	get_number_type () noexcept
	Determine the number type (integer or floating-point number) as quickly as possible.

simdjson_warn_unused simdjson_inline simdjson_result< number >	get_number () noexcept
	Attempt to parse an ondemand::number.

simdjson_inline simdjson_result< std::string_view >	raw_json_token () noexcept
	Get the raw JSON for this token.

void	rewind () noexcept
	Reset the iterator inside the document instance so we are pointing back at the beginning of the document, as if it had just been created.

std::string	to_debug_string () noexcept
	Returns debugging information.

bool	is_alive () noexcept
	Some unrecoverable error conditions may render the document instance unusable.

simdjson_result< const char * >	current_location () const noexcept
	Returns the current location in the document if in bounds.

bool	at_end () const noexcept
	Returns true if this document has been fully parsed.

simdjson_inline int32_t	current_depth () const noexcept
	Returns the current depth in the document if in bounds.

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

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

template<typename Func >
simdjson_inline error_code	for_each_at_path_with_wildcard (std::string_view json_path, Func &&callback) noexcept
	Call the provided callback for each value matching the given JSONPath expression with wildcard support.

simdjson_inline simdjson_result< std::string_view >	raw_json () noexcept
	Consumes the document and returns a string_view instance corresponding to the document as represented in JSON.

template<>
simdjson_inline simdjson_result< array >	get () &noexcept

template<>
simdjson_inline simdjson_result< object >	get () &noexcept

template<>
simdjson_inline simdjson_result< raw_json_string >	get () &noexcept

template<>
simdjson_inline simdjson_result< std::string_view >	get () &noexcept

template<>
simdjson_inline simdjson_result< double >	get () &noexcept

template<>
simdjson_inline simdjson_result< uint64_t >	get () &noexcept

template<>
simdjson_inline simdjson_result< int64_t >	get () &noexcept

template<>
simdjson_inline simdjson_result< uint32_t >	get () &noexcept

template<>
simdjson_inline simdjson_result< int32_t >	get () &noexcept

template<>
simdjson_inline simdjson_result< bool >	get () &noexcept

template<>
simdjson_inline simdjson_result< value >	get () &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (array &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (object &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (raw_json_string &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (std::string_view &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (double &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (uint64_t &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (int64_t &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (uint32_t &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (int32_t &out) &noexcept

template<>
simdjson_warn_unused simdjson_inline error_code	get (bool &out) &noexcept

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

template<>
simdjson_deprecated simdjson_inline simdjson_result< raw_json_string >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< std::string_view >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< double >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< uint64_t >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< int64_t >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< bool >	get () &&noexcept

template<>
simdjson_deprecated simdjson_inline simdjson_result< value >	get () &&noexcept

Protected Member Functions
simdjson_warn_unused simdjson_inline error_code	consume () noexcept
	Consumes the document.

simdjson_inline	document (ondemand::json_iterator &&iter) noexcept

simdjson_inline const uint8_t *	text (uint32_t idx) const noexcept

simdjson_inline value_iterator	resume_value_iterator () noexcept

simdjson_inline value_iterator	get_root_value_iterator () noexcept

simdjson_inline simdjson_result< object >	start_or_resume_object () noexcept

Static Protected Member Functions
static simdjson_inline document	start (ondemand::json_iterator &&iter) noexcept

Protected Attributes
json_iterator	iter {}
	Current position in the document.

Static Protected Attributes
static constexpr depth_t	DOCUMENT_DEPTH = 0
	document depth is always 0

Detailed Description

A JSON document.

It holds a json_iterator instance.

Used by tokens to get text, and string buffer location.

You must keep the document around during iteration.

Definition at line 24 of file document.h.

Constructor & Destructor Documentation

◆ document() [1/2]

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::document ( )

defaultnoexcept

Create a new invalid document.

Exists so you can declare a variable and later assign to it before use.

◆ document() [2/2]

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::document ( ondemand::json_iterator && iter )

protectednoexcept

Definition at line 25 of file document-inl.h.

Member Function Documentation

◆ at()

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::at ( size_t index ) &

noexcept

Get the value at the given index in the array.

This function has linear-time complexity. This function should only be called once on an array instance since the array iterator is not reset between each call.

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 236 of file document-inl.h.

◆ at_end()

bool simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::at_end ( ) const

inlinenoexcept

Returns true if this document has been fully parsed.

If you have consumed the whole document and at_end() returns false, then there may be trailing content.

Definition at line 51 of file document-inl.h.

◆ at_path()

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::at_path ( std::string_view json_path )

noexcept

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)

Key values are matched exactly, without unescaping or Unicode normalization. We do a byte-by-byte comparison. E.g.

const padded_string json = "{\"\\u00E9\":123}"_padded; auto doc = parser.iterate(json); doc.at_path(".\\u00E9") == 123 doc.at_path((const char*)u8".\u00E9") returns an error (NO_SUCH_FIELD)

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 351 of file document-inl.h.

◆ at_pointer()

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::at_pointer ( std::string_view json_pointer )

noexcept

Get the value associated with the given JSON pointer.

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

ondemand::parser parser; auto json = R"({ "foo": { "a": [ 10, 20, 30 ] }})"_padded; auto doc = parser.iterate(json); doc.at_pointer("/foo/a/1") == 20

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

ondemand::parser parser; auto json = R"({ "": { "a": [ 10, 20, 30 ] }})"_padded; auto doc = parser.iterate(json); doc.at_pointer("//a/1") == 20

Key values are matched exactly, without unescaping or Unicode normalization. We do a byte-by-byte comparison. E.g.

const padded_string json = "{\"\\u00E9\":123}"_padded; auto doc = parser.iterate(json); doc.at_pointer("/\\u00E9") == 123 doc.at_pointer((const char*)u8"/\u00E9") returns an error (NO_SUCH_FIELD)

Note that at_pointer() automatically calls rewind between each call. Thus all values, objects and arrays that you have created so far (including unescaped strings) are invalidated. After calling at_pointer, you need to consume the result: string values should be stored in your own variables, arrays should be decoded and stored in your own array-like structures and so forth.

Also note that at_pointer() relies on find_field() which implies that we do not unescape keys when matching

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
SCALAR_DOCUMENT_AS_VALUE if the json_pointer is empty and the document is not a scalar (see is_scalar() function).

Definition at line 333 of file document-inl.h.

◆ begin()

simdjson_inline simdjson_result< array_iterator > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::begin ( ) &

noexcept

Begin array iteration.

Part of the std::iterable interface.

Definition at line 240 of file document-inl.h.

◆ consume()

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::consume ( )

protectednoexcept

Consumes the document.

Definition at line 266 of file document-inl.h.

◆ count_elements()

simdjson_inline simdjson_result< size_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::count_elements ( ) &

noexcept

This method scans the array and counts the number of elements.

The count_elements method should always be called before you have begun iterating through the array: it is expected that you are pointing at the beginning of the array. The runtime complexity is linear in the size of the array. After calling this function, if successful, the array is 'rewinded' at its beginning as if it had never been accessed. If the JSON is malformed (e.g., there is a missing comma), then an error is returned and it is no longer safe to continue. Note that count_elements() does not validate the JSON values, only the structure of the array.

Definition at line 222 of file document-inl.h.

◆ count_fields()

simdjson_inline simdjson_result< size_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::count_fields ( ) &

noexcept

This method scans the object and counts the number of key-value pairs.

The count_fields method should always be called before you have begun iterating through the object: it is expected that you are pointing at the beginning of the object. The runtime complexity is linear in the size of the object. After calling this function, if successful, the object is 'rewinded' at its beginning as if it had never been accessed. If the JSON is malformed (e.g., there is a missing comma), then an error is returned and it is no longer safe to continue.

To check that an object is empty, it is more performant to use the is_empty() method.

Definition at line 229 of file document-inl.h.

◆ current_depth()

int32_t simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::current_depth ( ) const

inlinenoexcept

Returns the current depth in the document if in bounds.

E.g., 0 = finished with document 1 = document root value (could be [ or {, not yet known) 2 = , or } inside root array/object 3 = key or value inside root array/object.

Definition at line 47 of file document-inl.h.

◆ current_location()

simdjson_result< const char * > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::current_location ( ) const

inlinenoexcept

Returns the current location in the document if in bounds.

Definition at line 43 of file document-inl.h.

◆ end()

simdjson_inline simdjson_result< array_iterator > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::end ( ) &

noexcept

Sentinel representing the end of the array.

Part of the std::iterable interface.

Definition at line 243 of file document-inl.h.

◆ find_field() [1/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::find_field ( const char * key ) &

noexcept

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

◆ find_field() [2/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::find_field ( std::string_view key ) &

noexcept

Look up a field by name on an object (order-sensitive).

By order-sensitive, we mean that fields must be accessed in the order they appear in the JSON text (although you can skip fields). See find_field_unordered() and operator[] for an order-insensitive version.

The following code reads z, then y, then x, and thus will not retrieve x or y if fed the JSON { "x": 1, "y": 2, "z": 3 }:

simdjson::ondemand::parser parser;
auto obj = parser.parse(R"( { "x": 1, "y": 2, "z": 3 } )"_padded);
double z = obj.find_field("z");
double y = obj.find_field("y");
double x = obj.find_field("x");

Raw Keys: The lookup will be done against the raw key, and will not unescape keys. e.g. object["a"] will match { "a": 1 }, but will not match { "\u0061": 1 }.

You must consume the fields on an object one at a time. A request for a new key invalidates previous field values: it makes them unsafe. E.g., the array given by content["bids"].get_array() should not be accessed after you have called content["asks"].get_array(). You can detect such mistakes by first compiling and running the code in Debug mode (or with the macro SIMDJSON_DEVELOPMENT_CHECKS set to 1): an OUT_OF_ORDER_ITERATION error is generated.

You are expected to access keys only once. You should access the value corresponding to a key a single time. Doing object["mykey"].to_string()and then again object["mykey"].to_string() is an error.

Parameters

key	The key to look up.

Returns: The value of the field, or NO_SUCH_FIELD if the field is not in the object.

Definition at line 247 of file document-inl.h.

◆ find_field_unordered() [1/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::find_field_unordered ( const char * key ) &

noexcept

Definition at line 256 of file document-inl.h.

◆ find_field_unordered() [2/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::find_field_unordered ( std::string_view key ) &

noexcept

Look up a field by name on an object, without regard to key order.

Performance Notes: This is a bit less performant than find_field(), though its effect varies and often appears negligible. It starts out normally, starting out at the last field; but if the field is not found, it scans from the beginning of the object to see if it missed it. That missing case has a non-cache-friendly bump and lots of extra scanning, especially if the object in question is large. The fact that the extra code is there also bumps the executable size.

We default operator[] on find_field_unordered() for convenience. It is the default because it would be highly surprising (and hard to debug) if the default behavior failed to look up a field just because it was in the wrong order–and many APIs assume this. Therefore, you must be explicit if you want to treat objects as out of order.

Use find_field() if you are sure fields will be in order (or are willing to treat it as if the field was not there when they are not in order).

You must consume the fields on an object one at a time. A request for a new key invalidates previous field values: it makes them unsafe. E.g., the array given by content["bids"].get_array() should not be accessed after you have called content["asks"].get_array(). You can detect such mistakes by first compiling and running the code in Debug mode (or with the macro SIMDJSON_DEVELOPMENT_CHECKS set to 1): an OUT_OF_ORDER_ITERATION error is generated.

You are expected to access keys only once. You should access the value corresponding to a key a single time. Doing object["mykey"].to_string() and then again object["mykey"].to_string() is an error.

Parameters

key	The key to look up.

Returns: The value of the field, or NO_SUCH_FIELD if the field is not in the object.

Definition at line 253 of file document-inl.h.

◆ for_each_at_path_with_wildcard()

template<typename Func >

simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::for_each_at_path_with_wildcard	(	std::string_view	json_path,
		Func &&	callback
	)

noexcept

Call the provided callback for each value matching the given JSONPath expression with wildcard support.

Supports wildcard patterns like "$.array[*]" or "$.object.*" to match multiple elements.

The document will be consumed after this call.

Parameters

json_path	JSONPath expression with wildcards
callback	Function called for each matching value

Returns: error_code indicating success or failure

Get this value as the given type.

Supported types: object, array, raw_json_string, string_view, uint64_t, int64_t, double, bool

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

Returns: A value of the given type, parsed from the JSON.; INCORRECT_TYPE If the JSON value is not the given type.

Definition at line 189 of file document-inl.h.

◆ get() [29/32]

template<typename T >

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get ( T & out ) &

inlinenoexcept

Get this value as the given type.

Supported types: object, array, raw_json_string, string_view, uint64_t, int64_t, double, bool, value

Be mindful that the document instance must remain in scope while you are accessing object, array and value instances.

Parameters

out	This is set to a value of the given type, parsed from the JSON. If there is an error, this may not be initialized.

Returns: INCORRECT_TYPE If the JSON value is of the given type.; SUCCESS If the parse succeeded and the out parameter was set to the value.

Definition at line 252 of file document.h.

◆ get() [30/32]

template<>

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get ( uint32_t & out ) &

noexcept

Definition at line 193 of file document-inl.h.

◆ get() [31/32]

template<>

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get ( uint64_t & out ) &

noexcept

Definition at line 191 of file document-inl.h.

◆ get() [32/32]

template<>

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get ( value & out ) &

noexcept

Definition at line 196 of file document-inl.h.

◆ get_array()

simdjson_inline simdjson_result< array > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_array ( ) &

noexcept

Cast this JSON value to an array.

Returns: An object that can be used to iterate the array.; INCORRECT_TYPE If the JSON value is not an array.

Definition at line 107 of file document-inl.h.

◆ get_bool()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_bool ( )

noexcept

Cast this JSON value to a bool.

Returns: A bool value.; INCORRECT_TYPE if the JSON value is not true or false.

Definition at line 167 of file document-inl.h.

◆ get_double()

simdjson_inline simdjson_result< double > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_double ( )

noexcept

Cast this JSON value to a double.

Returns: A double.; INCORRECT_TYPE If the JSON value is not a valid floating-point number.

Definition at line 148 of file document-inl.h.

◆ get_double_in_string()

simdjson_inline simdjson_result< double > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_double_in_string ( )

noexcept

Cast this JSON value (inside string) to a double.

Returns: A double.; INCORRECT_TYPE If the JSON value is not a valid floating-point number.

Definition at line 151 of file document-inl.h.

◆ get_int32()

simdjson_inline simdjson_result< int32_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_int32 ( )

noexcept

Cast this JSON value to a 32-bit signed integer.

Calls get_int64() and checks that the result fits in an int32_t.

Returns: A 32-bit signed integer.; INCORRECT_TYPE If the JSON value is not an integer.; NUMBER_OUT_OF_RANGE If the value does not fit in an int32_t.

Definition at line 142 of file document-inl.h.

◆ get_int64()

simdjson_inline simdjson_result< int64_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_int64 ( )

noexcept

Cast this JSON value to a signed integer.

Returns: A signed 64-bit integer.; INCORRECT_TYPE If the JSON value is not a 64-bit integer.

Definition at line 130 of file document-inl.h.

◆ get_int64_in_string()

simdjson_inline simdjson_result< int64_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_int64_in_string ( )

noexcept

Cast this JSON value (inside string) to a signed integer.

Returns: A signed 64-bit integer.; INCORRECT_TYPE If the JSON value is not a 64-bit integer.

Definition at line 133 of file document-inl.h.

◆ get_number()

simdjson_inline simdjson_result< number > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_number ( )

noexcept

Attempt to parse an ondemand::number.

An ondemand::number may contain an integer value or a floating-point value, the simdjson library will autodetect the type. Thus it is a dynamically typed number. Before accessing the value, you must determine the detected type.

number.get_number_type() is number_type::signed_integer if we have an integer in [-9223372036854775808,9223372036854775808) You can recover the value by calling number.get_int64() and you have that number.is_int64() is true.

number.get_number_type() is number_type::unsigned_integer if we have an integer in [9223372036854775808,18446744073709551616) You can recover the value by calling number.get_uint64() and you have that number.is_uint64() is true.

Otherwise, number.get_number_type() has value number_type::floating_point_number and we have a binary64 number. You can recover the value by calling number.get_double() and you have that number.is_double() is true.

You must check the type before accessing the value: it is an error to call "get_int64()" when number.get_number_type() is not number_type::signed_integer and when number.is_int64() is false.

Definition at line 323 of file document-inl.h.

◆ get_number_type()

simdjson_inline simdjson_result< number_type > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_number_type ( )

noexcept

Determine the number type (integer or floating-point number) as quickly as possible.

This function does not fully validate the input. It is useful when you only need to classify the numbers, without parsing them.

If you are planning to retrieve the value or you need full validation, consider using the get_number() method instead: it will fully parse and validate the input, and give you access to the type: get_number().get_number_type().

get_number_type() is number_type::unsigned_integer if we have an integer greater or equal to 9223372036854775808 and no larger than 18446744073709551615. get_number_type() is number_type::signed_integer if we have an integer that is less than 9223372036854775808 and greater or equal to -9223372036854775808. get_number_type() is number_type::big_integer if we have an integer outside of those ranges (either larger than 18446744073709551615 or smaller than -9223372036854775808). Otherwise, get_number_type() has value number_type::floating_point_number

This function requires processing the number string, but it is expected to be faster than get_number().get_number_type() because it is does not parse the number value.

Returns: the type of the number

Definition at line 319 of file document-inl.h.

◆ get_object()

simdjson_inline simdjson_result< object > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_object ( ) &

noexcept

Cast this JSON value to an object.

Returns: An object that can be used to look up or iterate fields.; INCORRECT_TYPE If the JSON value is not an object.

Definition at line 111 of file document-inl.h.

◆ get_raw_json_string()

simdjson_inline simdjson_result< raw_json_string > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_raw_json_string ( )

noexcept

Cast this JSON value to a raw_json_string.

The string is guaranteed to be valid UTF-8, and may have escapes in it (e.g. \ or
).

Returns: A pointer to the raw JSON for the given string.; INCORRECT_TYPE if the JSON value is not a string.

Definition at line 164 of file document-inl.h.

◆ get_root_value_iterator()

simdjson_inline value_iterator simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_root_value_iterator ( )

protectednoexcept

Definition at line 62 of file document-inl.h.

◆ get_string() [1/2]

simdjson_inline simdjson_result< std::string_view > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_string ( bool allow_replacement = false )

noexcept

Cast this JSON value to a string.

The string is guaranteed to be valid UTF-8.

Important: Calling get_string() twice on the same document is an error.

Parameters

Whether to allow a replacement character for unmatched surrogate pairs.

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.; INCORRECT_TYPE if the JSON value is not a string.

Definition at line 154 of file document-inl.h.

◆ get_string() [2/2]

template<typename string_type >

simdjson_warn_unused simdjson_inline error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_string	(	string_type &	receiver,
		bool	allow_replacement = `false`
	)

noexcept

Attempts to fill the provided std::string reference with the parsed value of the current string.

The string is guaranteed to be valid UTF-8.

Important: a value should be consumed once. Calling get_string() twice on the same value is an error.

Performance: This method may be slower than get_string() or get_string(bool) because it may need to allocate memory. We recommend you avoid allocating an std::string unless you need to.

Returns: INCORRECT_TYPE if the JSON value is not a string. Otherwise, we return SUCCESS.

Definition at line 158 of file document-inl.h.

◆ get_uint32()

simdjson_inline simdjson_result< uint32_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_uint32 ( )

noexcept

Cast this JSON value to a 32-bit unsigned integer.

Calls get_uint64() and checks that the result fits in a uint32_t.

Returns: A 32-bit unsigned integer.; INCORRECT_TYPE If the JSON value is not an unsigned integer.; NUMBER_OUT_OF_RANGE If the value does not fit in a uint32_t.

Definition at line 136 of file document-inl.h.

◆ get_uint64()

simdjson_inline simdjson_result< uint64_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_uint64 ( )

noexcept

Cast this JSON value to an unsigned integer.

We decided that calling 'get_double()' on the JSON document '1.233 blabla' should give an error, so we check for trailing content.

Returns: A signed 64-bit integer.; INCORRECT_TYPE If the JSON value is not a 64-bit unsigned integer.

We want to disallow trailing content. Thus, in several implementations below, we pass a 'true' parameter value to a get_root_value_iterator() method: this indicates that we disallow trailing content.

Definition at line 124 of file document-inl.h.

◆ get_uint64_in_string()

simdjson_inline simdjson_result< uint64_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_uint64_in_string ( )

noexcept

Cast this JSON value (inside string) to an unsigned integer.

Returns: A signed 64-bit integer.; INCORRECT_TYPE If the JSON value is not a 64-bit unsigned integer.

Definition at line 127 of file document-inl.h.

◆ get_value()

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_value ( )

noexcept

Cast this JSON value to a value when the document is an object or an array.

You must not have begun iterating through the object or array. When SIMDJSON_DEVELOPMENT_CHECKS is set to 1 (which is the case when building in Debug mode by default), and you have already begun iterating, you will get an OUT_OF_ORDER_ITERATION error. If you have begun iterating, you can use rewind() to reset the document to its initial state before calling this method.

Returns: A value if a JSON array or object cannot be found.; SCALAR_DOCUMENT_AS_VALUE error is the document is a scalar (see is_scalar() function).

Definition at line 72 of file document-inl.h.

◆ get_wobbly_string()

simdjson_inline simdjson_result< std::string_view > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::get_wobbly_string ( )

noexcept

Cast this JSON value to a string.

The string is not guaranteed to be valid UTF-8. See https://simonsapin.github.io/wtf-8/

Important: Calling get_wobbly_string() twice on the same document is an error.

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.; INCORRECT_TYPE if the JSON value is not a string.

Definition at line 161 of file document-inl.h.

◆ is_alive()

bool simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_alive ( )

inlinenoexcept

Some unrecoverable error conditions may render the document instance unusable.

The is_alive() method returns true when the document is still suitable.

Definition at line 56 of file document-inl.h.

◆ is_integer()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_integer ( )

noexcept

Checks whether the document is an integer number.

Note that this requires to partially parse the number string. If the value is determined to be an integer, it may still not parse properly as an integer in subsequent steps (e.g., it might overflow).

Returns: true if the number if negative.

Definition at line 315 of file document-inl.h.

◆ is_negative()

simdjson_inline bool simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_negative ( )

noexcept

Checks whether the document is a negative number.

Returns: true if the number if negative.

Definition at line 311 of file document-inl.h.

◆ is_null()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_null ( )

noexcept

Checks if this JSON value is null.

If and only if the value is null, then it is consumed (we advance). If we find a token that begins with 'n' but is not 'null', then an error is returned.

Returns: Whether the value is null.; INCORRECT_TYPE If the JSON value begins with 'n' and is not 'null'.

Definition at line 170 of file document-inl.h.

◆ is_scalar()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_scalar ( )

noexcept

Checks whether the document is a scalar (string, number, null, Boolean).

Returns false when there it is an array or object.

Returns: true if the type is string, number, null, Boolean @error TAPE_ERROR when the JSON value is a bad token like "}" "," or "alse".

Definition at line 295 of file document-inl.h.

◆ is_string()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::is_string ( )

noexcept

Checks whether the document is a string.

Returns: true if the type is string @error TAPE_ERROR when the JSON value is a bad token like "}" "," or "alse".

Definition at line 304 of file document-inl.h.

◆ operator array()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator array ( ) &

Cast this JSON value to an array.

Returns: An object that can be used to iterate the array.

Exceptions

simdjson_error(INCORRECT_TYPE) If the JSON value is not an array.

Definition at line 211 of file document-inl.h.

◆ operator bool()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator bool ( )

Cast this JSON value to a bool.

Returns: A bool value.

Exceptions

simdjson_error(INCORRECT_TYPE) if the JSON value is not true or false.

Definition at line 218 of file document-inl.h.

◆ operator double()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator double ( )

Cast this JSON value to a double.

Returns: A double.

Exceptions

simdjson_error(INCORRECT_TYPE) If the JSON value is not a valid floating-point number.

Definition at line 215 of file document-inl.h.

◆ operator int64_t()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator int64_t ( )

Cast this JSON value to a signed integer.

Returns: A signed 64-bit integer.

Exceptions

simdjson_error(INCORRECT_TYPE) If the JSON value is not a 64-bit integer.

Definition at line 214 of file document-inl.h.

◆ operator object()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator object ( ) &

Cast this JSON value to an object.

Returns: An object that can be used to look up or iterate fields.

Exceptions

simdjson_error(INCORRECT_TYPE) If the JSON value is not an object.

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

◆ operator raw_json_string()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator raw_json_string ( )

Cast this JSON value to a raw_json_string.

The string is guaranteed to be valid UTF-8, and may have escapes in it (e.g. \ or
).

Returns: A pointer to the raw JSON for the given string.

Exceptions

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

Definition at line 217 of file document-inl.h.

◆ operator std::string_view()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator std::string_view ( )

Cast this JSON value 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.

Exceptions

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

Definition at line 216 of file document-inl.h.

◆ operator T() [1/2]

template<class T >

simdjson_deprecated simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator T ( ) &&

explicit

Definition at line 208 of file document-inl.h.

◆ operator T() [2/2]

template<class T >

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator T ( ) &

explicit

Cast this JSON value to an instance of type T.

The programmer is responsible for providing an implementation of get<T> for the type T, if T is not one of the types supported by the library (object, array, raw_json_string, string_view, uint64_t, etc.)

See https://github.com/simdjson/simdjson/blob/master/doc/basics.md#adding-support-for-custom-types

Returns: An instance of type T

Definition at line 210 of file document-inl.h.

◆ operator uint64_t()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator uint64_t ( )

Cast this JSON value to an unsigned integer.

Returns: A signed 64-bit integer.

Exceptions

simdjson_error(INCORRECT_TYPE) If the JSON value is not a 64-bit unsigned integer.

Definition at line 213 of file document-inl.h.

◆ operator value()

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::operator value ( )

Cast this JSON value to a value when the document is an object or an array.

You must not have begun iterating through the object or array. When SIMDJSON_DEVELOPMENT_CHECKS is defined, and you have already begun iterating, you will get an OUT_OF_ORDER_ITERATION error. If you have begun iterating, you can use rewind() to reset the document to its initial state before calling this method.

Returns: A value value if a JSON array or object cannot be found.

Exceptions

SCALAR_DOCUMENT_AS_VALUE error is the document is a scalar (see is_scalar() function).

Definition at line 219 of file document-inl.h.

◆ operator[]() [1/2]

Definition at line 65 of file document-inl.h.

◆ to_debug_string()

std::string simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::to_debug_string ( )

inlinenoexcept

Returns debugging information.

Definition at line 39 of file document-inl.h.

◆ type()

simdjson_inline simdjson_result< json_type > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::type ( )

noexcept

Get the type of this JSON value.

It does not validate or consume the value. E.g., you must still call "is_null()" to check that a value is null even if "type()" returns json_type::null.

The answer can be one of simdjson::ondemand::json_type::object, simdjson::ondemand::json_type::array, simdjson::ondemand::json_type::string, simdjson::ondemand::json_type::number, simdjson::ondemand::json_type::boolean, simdjson::ondemand::json_type::null.

Starting with simdjson 4.0, this function will return simdjson::ondemand::json_type::unknown given a bad token. This allows you to identify a case such as {"key": NaN} and identify the NaN value. The simdjson::ondemand::json_type::unknown value should only happen with non-valid JSON.

NOTE: If you're only expecting a value to be one type (a typical case), it's generally better to just call .get_double, .get_string, etc. and check for INCORRECT_TYPE (or just let it throw an exception).

Prior to simdjson 4.0, this function would return an error given a bad token. Starting with simdjson 4.0, it will return simdjson::ondemand::json_type::unknown. This allows you to identify a case such as {"key": NaN} and identify the NaN value. The simdjson::ondemand::json_type::unknown value should only happen with non-valid JSON.

Definition at line 291 of file document-inl.h.

Member Data Documentation

◆ DOCUMENT_DEPTH

constexpr depth_t simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::DOCUMENT_DEPTH = 0

staticconstexprprotected

document depth is always 0

Definition at line 820 of file document.h.

◆ iter

json_iterator simdjson::SIMDJSON_IMPLEMENTATION::ondemand::document::iter {}

protected

Current position in the document.

Definition at line 819 of file document.h.

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

include/simdjson/generic/ondemand/document.h
include/simdjson/generic/ondemand/document-inl.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ document() [1/2]

◆ document() [2/2]

Member Function Documentation

◆ at()

◆ at_end()

◆ at_path()

◆ at_pointer()

◆ begin()

◆ consume()

◆ count_elements()

◆ count_fields()

◆ current_depth()

◆ current_location()

◆ end()

◆ find_field() [1/2]

◆ find_field() [2/2]

◆ find_field_unordered() [1/2]

◆ find_field_unordered() [2/2]

◆ for_each_at_path_with_wildcard()

◆ get() [1/32]

◆ get() [2/32]

◆ get() [3/32]

◆ get() [4/32]

◆ get() [5/32]

◆ get() [6/32]

◆ get() [7/32]

◆ get() [8/32]

◆ get() [9/32]

◆ get() [10/32]

◆ get() [11/32]

◆ get() [12/32]

◆ get() [13/32]

◆ get() [14/32]

◆ get() [15/32]

◆ get() [16/32]

◆ get() [17/32]

◆ get() [18/32]

◆ get() [19/32]

◆ get() [20/32]

◆ get() [21/32]

◆ get() [22/32]

◆ get() [23/32]

◆ get() [24/32]

◆ get() [25/32]

◆ get() [26/32]

◆ get() [27/32]

◆ get() [28/32]

◆ get() [29/32]

◆ get() [30/32]

◆ get() [31/32]

◆ get() [32/32]

◆ get_array()

◆ get_bool()

◆ get_double()

◆ get_double_in_string()

◆ get_int32()

◆ get_int64()

◆ get_int64_in_string()

◆ get_number()

◆ get_number_type()

◆ get_object()

◆ get_raw_json_string()

◆ get_root_value_iterator()

◆ get_string() [1/2]

◆ get_string() [2/2]

◆ get_uint32()

◆ get_uint64()

◆ get_uint64_in_string()

◆ get_value()

◆ get_wobbly_string()

◆ is_alive()

◆ is_integer()

◆ is_negative()