A forward-only JSON object field iterator. More...

#include <object.h>

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

simdjson_inline simdjson_result< object_iterator >	begin () noexcept
	Get an iterator to the start of the object.

simdjson_inline simdjson_result< object_iterator >	end () noexcept

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 (std::string_view 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 (std::string_view key) &&noexcept

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

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

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

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

template<typename Func >
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_result< bool >	reset () &noexcept
	Reset the iterator so that we are pointing back at the beginning of the object.

simdjson_result< bool >	is_empty () &noexcept
	This method scans the beginning of the object and checks whether the object is empty.

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< std::string_view >	raw_json () noexcept
	Consumes the object and returns a string_view instance corresponding to the object as represented in JSON.

Protected Member Functions
simdjson_warn_unused simdjson_inline error_code	consume () noexcept
	Go to the end of the object, no matter where you are right now.

simdjson_inline	object (const value_iterator &iter) noexcept

simdjson_warn_unused simdjson_inline error_code	find_field_raw (const std::string_view key) noexcept

Static Protected Member Functions
static simdjson_inline simdjson_result< object >	start (value_iterator &iter) noexcept

static simdjson_inline simdjson_result< object >	start_root (value_iterator &iter) noexcept

static simdjson_inline simdjson_result< object >	started (value_iterator &iter) noexcept

static simdjson_inline object	resume (const value_iterator &iter) noexcept

Protected Attributes
value_iterator	iter {}

Detailed Description

A forward-only JSON object field iterator.

Definition at line 21 of file object.h.

Constructor & Destructor Documentation

◆ object() [1/2]

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::object ( )

defaultnoexcept

Create a new invalid object.

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

◆ object() [2/2]

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::object ( const value_iterator & iter )

protectednoexcept

Definition at line 117 of file object-inl.h.

Member Function Documentation

◆ at_path()

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

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.

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 172 of file object-inl.h.

◆ at_pointer()

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

inlinenoexcept

Get the value associated with the given JSON pointer.

We use the RFC 6901 https://tools.ietf.org/html/rfc6901 standard, interpreting the current node as the root of its own JSON document.

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

Note that at_pointer() called on the document automatically calls the document's rewind method between each call. It invalidates all previously accessed arrays, objects and values that have not been consumed. Yet it is not the case when calling at_pointer on an object instance: there is no rewind and no invalidation.

You may call at_pointer more than once on an object, but each time the pointer is advanced to be within the value matched by the key indicated by the JSON pointer query. Thus any preceding key (as well as the current key) can no longer be used with following JSON pointer calls.

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

Definition at line 132 of file object-inl.h.

◆ begin()

simdjson_inline simdjson_result< object_iterator > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::begin ( )

noexcept

Get an iterator to the start of the object.

We recommend using a range-based for loop.

Using the iterator directly is also possible but error-prone and discouraged. In particular, you must dereference the iterator exactly once per iteration (before calling '++'). Doing otherwise is unsafe and may lead to errors. You are responsible for ensuring

Definition at line 122 of file object-inl.h.

◆ consume()

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

protectednoexcept

Go to the end of the object, no matter where you are right now.

whenever you are pointing at a key, calling skip_child() is unsafe because you will hit a string and you will assume that it is string value, and this mistake will lead you to make bad depth computation.

We want to 'consume' the key. We could really just do _json_iter->return_current_and_advance(); at this point, but, for clarity, we will use the high-level API to eat the key. We assume that the compiler optimizes away most of the work.

Definition at line 74 of file object-inl.h.

◆ count_fields()

simdjson_inline simdjson_result< size_t > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::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.

Performance hint: You should only call count_fields() as a last resort as it may require scanning the document twice or more.

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

◆ end()

simdjson_inline simdjson_result< object_iterator > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::end ( )

noexcept

Definition at line 128 of file object-inl.h.

◆ find_field() [1/2]

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

noexcept

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

◆ find_field() [2/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::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");

If you have multiple fields with a matching key ({"x": 1, "x": 1}) be mindful that only one field is returned.

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. The value instance you get from content["bids"] becomes invalid when you call content["asks"]. 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.

If you expect to have keys with escape characters, please review our documentation.

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 47 of file object-inl.h.

◆ find_field_unordered() [1/2]

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

noexcept

Definition at line 32 of file object-inl.h.

◆ find_field_unordered() [2/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::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).

If you have multiple fields with a matching key ({"x": 1, "x": 1}) be mindful that only one field is returned.

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. The value instance you get from content["bids"] becomes invalid when you call content["asks"]. 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.

If you expect to have keys with escape characters, please review our documentation.

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 23 of file object-inl.h.

◆ for_each_at_path_with_wildcard()

template<typename Func >

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

inlinenoexcept

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

Supports wildcard patterns like ".*" to match all object fields.

Parameters

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

Returns: error_code indicating success or failure

Definition at line 186 of file object-inl.h.

◆ is_empty()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::is_empty ( ) &

inlinenoexcept

This method scans the beginning of the object and checks whether the object is empty.

The runtime complexity is constant time. 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.

Definition at line 228 of file object-inl.h.

◆ operator[]() [1/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::operator[] ( std::string_view key ) &&

noexcept

Definition at line 44 of file object-inl.h.

◆ operator[]() [2/2]

simdjson_inline simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::operator[] ( std::string_view key ) &

noexcept

Definition at line 41 of file object-inl.h.

◆ raw_json()

simdjson_inline simdjson_result< std::string_view > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::raw_json ( )

noexcept

Consumes the object and returns a string_view instance corresponding to the object as represented in JSON.

It points inside the original byte array containing the JSON document.

Definition at line 100 of file object-inl.h.

◆ reset()

simdjson_inline simdjson_result< bool > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::reset ( ) &

inlinenoexcept

Reset the iterator so that we are pointing back at the beginning of the object.

You should still consume values only once even if you can iterate through the object more than once. If you unescape a string or a key within the object more than once, you have unsafe code. Note that rewinding an object means that you may need to reparse it anew: it is not a free operation.

Returns: true if the object contains some elements (not empty)

Definition at line 235 of file object-inl.h.

◆ resume()

simdjson_inline object simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::resume ( const value_iterator & iter )

staticprotectednoexcept

Definition at line 113 of file object-inl.h.

◆ start()

simdjson_inline simdjson_result< object > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::start ( value_iterator & iter )

staticprotectednoexcept

Definition at line 66 of file object-inl.h.

◆ start_root()

simdjson_inline simdjson_result< object > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::start_root ( value_iterator & iter )

staticprotectednoexcept

Definition at line 70 of file object-inl.h.

◆ started()

simdjson_inline simdjson_result< object > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::started ( value_iterator & iter )

staticprotectednoexcept

Definition at line 108 of file object-inl.h.

Member Data Documentation

◆ iter

value_iterator simdjson::SIMDJSON_IMPLEMENTATION::ondemand::object::iter {}

protected

Definition at line 309 of file object.h.

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

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ object() [1/2]

◆ object() [2/2]

Member Function Documentation

◆ at_path()

◆ at_pointer()

◆ begin()

◆ consume()

◆ count_fields()

◆ 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()

◆ is_empty()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ raw_json()

◆ reset()

◆ resume()

◆ start()

◆ start_root()

◆ started()

Member Data Documentation

◆ iter