A forward-only JSON array. More...

#include <array.h>

Public Member Functions
simdjson_inline	array () noexcept=default
	Create a new invalid 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< size_t >	count_elements () &noexcept
	This method scans the array and counts the number of elements.

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

simdjson_result< bool >	reset () &noexcept
	Reset the iterator so that we are pointing back at the beginning of the array.

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

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

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

simdjson_inline	array (const value_iterator &iter) noexcept
	Create an array at the given Internal array creation.

Static Protected Member Functions
static simdjson_inline simdjson_result< array >	start (value_iterator &iter) noexcept
	Begin array iteration.

static simdjson_inline simdjson_result< array >	start_root (value_iterator &iter) noexcept
	Begin array iteration from the root.

static simdjson_inline simdjson_result< array >	started (value_iterator &iter) noexcept
	Begin array iteration.

Protected Attributes
value_iterator	iter {}
	Iterator marking current position.

Detailed Description

A forward-only JSON array.

Definition at line 18 of file array.h.

Constructor & Destructor Documentation

◆ array() [1/2]

simdjson_inline simdjson::SIMDJSON_IMPLEMENTATION::ondemand::array::array ( )

defaultnoexcept

Create a new invalid array.

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

◆ array() [2/2]

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

protectednoexcept

Create an array at the given Internal array creation.

Call array::start() or array::started() instead of this.

Parameters

iter	The iterator. Must either be at the start of the first element with iter.is_alive() == true, or past the [] with is_alive() == false if the array is empty. Will be moved into the resulting array.

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

Member Function Documentation

◆ at()

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

noexcept

Get the value at the given index.

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 219 of file array-inl.h.

◆ at_path()

simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::array::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.

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 167 of file array-inl.h.

◆ at_pointer()

simdjson_result< value > simdjson::SIMDJSON_IMPLEMENTATION::ondemand::array::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("/0/foo/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 array instance: there is no rewind and no invalidation.

You may only call at_pointer on an array after it has been created, but before it has been first accessed. When calling at_pointer on an array, the pointer is advanced to the location indicated by the JSON pointer (in case of success). It is no longer possible to call at_pointer on the same array.

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 131 of file array-inl.h.

◆ begin()

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

noexcept

Begin array iteration.

Part of the std::iterable interface.

Definition at line 79 of file array-inl.h.

◆ consume()

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

protectednoexcept

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

Definition at line 88 of file array-inl.h.

◆ count_elements()

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

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

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

◆ end()

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

noexcept

Sentinel representing the end of the array.

Part of the std::iterable interface.

Definition at line 85 of file array-inl.h.

◆ for_each_at_path_with_wildcard()

template<typename Func >

error_code simdjson::SIMDJSON_IMPLEMENTATION::ondemand::array::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 array elements.

Parameters

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

Returns: error_code indicating success or failure

Definition at line 179 of file array-inl.h.

◆ is_empty()

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

noexcept

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

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

Definition at line 120 of file array-inl.h.

◆ raw_json()

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

noexcept

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

It points inside the original document.

Definition at line 94 of file array-inl.h.

◆ reset()

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

inlinenoexcept

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

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

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

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

◆ start()

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

staticprotectednoexcept

Begin array iteration.

Parameters

iter	The iterator. Must be where the initial [ is expected. Will be moved into the resulting array. @error INCORRECT_TYPE if the iterator is not at [.

Definition at line 61 of file array-inl.h.

◆ start_root()

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

staticprotectednoexcept

Begin array iteration from the root.

Parameters

iter	The iterator. Must be where the initial [ is expected. Will be moved into the resulting array. @error INCORRECT_TYPE if the iterator is not at [. @error TAPE_ERROR if there is no closing ] at the end of the document.

Definition at line 68 of file array-inl.h.

◆ started()

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

staticprotectednoexcept

Begin array iteration.

This version of the method should be called after the initial [ has been verified, and is intended for use by switch statements that check the type of a value.

Parameters

iter	The iterator. Must be after the initial [. Will be moved into the resulting array.

Definition at line 73 of file array-inl.h.

Member Data Documentation

◆ iter

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

protected

Iterator marking current position.

iter.is_alive() == false indicates iteration is complete.

Definition at line 230 of file array.h.

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

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ array() [1/2]

◆ array() [2/2]

Member Function Documentation

◆ at()

◆ at_path()

◆ at_pointer()

◆ begin()

◆ consume()

◆ count_elements()

◆ end()

◆ for_each_at_path_with_wildcard()

◆ is_empty()

◆ raw_json()

◆ reset()

◆ start()

◆ start_root()

◆ started()

Member Data Documentation

◆ iter