Corrade::Utility::JsonToken class new in Git master

A single JSON token.

Represents an object, array, null, boolean, numeric or a string value in a JSON file. See the Json class documentation for more information.

Public types

enum class Type: std::uint64_t { Object, Array, Null, Bool, Number, String }
Token type.
enum class ParsedType: std::uint64_t { None = 0, Double, Float, UnsignedInt, Int, UnsignedLong, Long, Size, Other }
Parsed type.

Public functions

auto data() const -> Containers::StringView
Token data.
auto type() const -> Type
Token type.
auto isParsed() const -> bool
Whether the token value is parsed.
auto parsedType() const -> ParsedType
Parsed token type.
auto childCount() const -> std::size_t
Child token count.
auto children() const -> Containers::ArrayView<const JsonToken>
Child token tree.
auto firstChild() const -> const JsonToken*
First child token.
auto next() const -> const JsonToken*
Next token or next.
auto parent() const -> const JsonToken*
Parent token.
auto asObject() const -> JsonObjectView
Get an iterable object.
auto asArray() const -> JsonArrayView
Get an iterable array.
auto find(Containers::StringView key) const -> const JsonToken*
Find an object value by key.
auto find(std::size_t index) const -> const JsonToken*
Find an array value by index.
auto operator[](Containers::StringView key) const -> const JsonToken&
Access an object value by key.
auto operator[](std::size_t index) const -> const JsonToken&
Access an array value by index.
auto asNull() const -> std::nullptr_t
Get a parsed null value.
auto asBool() const -> bool
Get a parsed boolean value.
auto asDouble() const -> double
Get a parsed 64-bit floating-point value.
auto asFloat() const -> float
Get a parsed 32-bit floating-point value.
auto asUnsignedInt() const -> std::uint32_t
Get a parsed unsigned 32-bit integer value.
auto asInt() const -> std::int32_t
Get a parsed signed 32-bit integer value.
auto asUnsignedLong() const -> std::uint64_t
Get a parsed unsigned 52-bit integer value.
auto asLong() const -> std::int64_t
Get a parsed signed 53-bit integer value.
auto asSize() const -> std::size_t
Get a parsed size value.
auto asString() const -> Containers::StringView
Get a parsed string value.
auto asBoolArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const bool>
Get a parsed boolean array.
auto asDoubleArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const double>
Get a parsed 64-bit floating-point array.
auto asFloatArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const float>
Get a parsed 32-bit floating-point array.
auto asUnsignedIntArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const std::uint32_t>
Get a parsed unsigned 32-bit integer array.
auto asIntArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const std::int32_t>
Get a parsed signed 32-bit integer array.
auto asUnsignedLongArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const std::uint64_t>
Get a parsed unsigned 52-bit integer array.
auto asLongArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const std::int64_t>
Get a parsed signed 53-bit integer value array.
auto asSizeArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const std::size_t>
Get a parsed size array.

Enum documentation

enum class Corrade::Utility::JsonToken::Type: std::uint64_t

Token type.

Enumerators
Object

An object, {}. Its immediate children are Type::String keys, values are children of the keys. The keys can be in an arbitrary order and can contain duplicates. isParsed() is set always.

Array

An array, []. Its immediate children are values. isParsed() is set always.

Null

A null value. Unless isParsed() is set, the value is not guaranteed to be valid.

Bool

A true or false value. Unless isParsed() is set, the value is not guaranteed to be valid.

Number

A number. Unless isParsed() is set, the value is not guaranteed to be valid. JSON numbers are always 64-bit floating point values but you can choose whether to parse them as doubles or floats using Json::parseDoubles() or Json::parseFloats(). If an integer value is expected you can use Json::parseInts(), Json::parseUnsignedInts(), Json::parseLongs(), Json::parseUnsignedLongs() or Json::parseSizes() instead to implicitly check that they have a zero fractional part or additionally that they're also non-negative.

String

A string. Unless isParsed() is set, the value is not guaranteed to be valid.

enum class Corrade::Utility::JsonToken::ParsedType: std::uint64_t

Parsed type.

Enumerators
None

Not parsed yet.

Double

64-bit floating-point value.

Set if Json::Option::ParseDoubles is passed to Json::fromString() or Json::fromFile() or if Json::parseDoubles() is called later.

Float

32-bit floating-point value.

Set if Json::Option::ParseFloats is passed to Json::fromString() or Json::fromFile() or if Json::parseFloats() is called later. Double-precision values that can't be represented as a float are truncated.

UnsignedInt

32-bit unsigned integer value.

Set if Json::parseUnsignedInts() is called on a particular subtree. Except for invalid values, parsing fails also if any the values have a non-zero fractional part, if they have an exponent, if they're negative or if they can't fit into 32 bits.

Int

32-bit signed integer value.

Set if Json::parseInts() is called on a particular subtree. Except for invalid values, parsing fails also if any the values have a non-zero fractional part, if they have an exponent or if they can't fit into 32 bits.

UnsignedLong

52-bit unsigned integer value.

Set if Json::parseUnsignedLongs() is called on a particular subtree. Except for invalid values, parsing fails also fails if any the values have a non-zero fractional part, if they have an exponent, if they're negative or if they can't fit into 52 bits (which is the representable unsigned integer range in a JSON).

Long

53-bit signed integer value.

Set if Json::parseLongs() is called on a particular subtree. Except for invalid values, parsing fails also fails if any the values have a non-zero fractional part, if they have an exponent, if they're negative or if they can't fit into 53 bits (which is the representable signed integer range in a JSON).

Size

Size value. Alias to ParsedType::UnsignedInt or ParsedType::UnsignedLong depending on whether the system is 32-bit or 64-bit.

Other

An object, array, null, bool or a string value.

Function documentation

Containers::StringView Corrade::Utility::JsonToken::data() const

Token data.

Contains raw unparsed token data, including all child tokens (if any). The first byte implies type():

  • { is a Type::Object. Spans until and including the closing }. Child token tree is exposed through children(). Immediate children are keys, second-level children are values.
  • [ is a Type::Array. Spans until and including the closing ]. Child token tree is exposed through children().
  • n is a Type::Null. Not guaranteed to be a valid value if isParsed() is not set.
  • t or f is a Type::Bool. Not guaranteed to be a valid value if isParsed() is not set.
  • - or 0 to 9 is a Type::Number. Not guaranteed to be a valid value if isParsed() is not set.
  • " is a Type::String. If an object key, children() contains the value token tree, but the token data always spans only until and including the closing ". Not guaranteed to be a valid value and may contain escape sequences if isParsed() is not set.

Returned view points to data owned by the originating Json instance, or to the string passed to Json::fromString() if it was called with Containers::StringViewFlag::Global set. Due to implementation complexity reasons, the global flag is not preserved in the returned value here, only in case of asString().

bool Corrade::Utility::JsonToken::isParsed() const

Whether the token value is parsed.

If set, the value can be accessed directly by asObject(), asArray(), asNull(), asBool(), asDouble(), asFloat(), asUnsignedInt(), asInt(), asUnsignedLong(), asLong(), asSize() or asString() function based on type() and parsedType() and the call will not fail. If not set, the value has to be parsed first.

Tokens can be parsed during the initial run by passing Json::Option::ParseLiterals, ParseDoubles, ParseStringKeys or ParseStrings to Json::fromString() or Json::fromFile(); selectively later using Json::parseLiterals(), parseDoubles(), parseFloats(), parseUnsignedInts(), parseInts(), parseUnsignedLongs(), parseLongs(), parseSizes(), parseStringKeys() or parseStrings(); or on a per-token basis using Json::parseObject(), parseArray(), parseNull(), parseBool(), parseDouble(), parseFloat(), parseUnsignedInt(), parseInt(), parseUnsignedLong(), parseLong(), parseSize() or parseString().

ParsedType Corrade::Utility::JsonToken::parsedType() const

Parsed token type.

std::size_t Corrade::Utility::JsonToken::childCount() const

Child token count.

Number of all child tokens, including nested token trees. For Type::Null, Type::Bool, Type::Number and value Type::String always returns 0, for a Type::String that's an object key always returns 1.

Containers::ArrayView<const JsonToken> Corrade::Utility::JsonToken::children() const

Child token tree.

Contains all child tokens ordered in a depth-first manner as described in Tokenization and parsing process. Returned view points to data owned by the originating Json instance.

const JsonToken* Corrade::Utility::JsonToken::firstChild() const

First child token.

Returns first child token or nullptr if there are no child tokens. In particular, for a non-empty Type::Object the first immediate child is a Type::String, which then contains the value as a child token tree. Type::Null, Type::Bool and Type::Number tokens return nullptr always. Accessing the first child has a $ \mathcal{O}(1) $ complexity. Returned value doints to data owned by the originating Json instance.

const JsonToken* Corrade::Utility::JsonToken::next() const

Next token or next.

Return next token at the same or higher level, or a pointer to (one value after) the end. Accessing the next token has a $ \mathcal{O}(1) $ complexity. Returned value points to data owned by the originating Json instance.

const JsonToken* Corrade::Utility::JsonToken::parent() const

Parent token.

Returns parent token or nullptr if the token is the root token. Accessing the parent token is done by traversing the token list backwards and thus has a $ \mathcal{O}(n) $ complexity — where possible, it's encouraged to remember the parent instead of using this function. Returned value points to data owned by the originating Json instance.

JsonObjectView Corrade::Utility::JsonToken::asObject() const

Get an iterable object.

Expects that the token is a Type::Object and isParsed() is set, accessing JsonObjectItem::key() then expects that the key token has isParsed() set. See Iterating objects and arrays for more information. Iteration through object keys is performed using next(), which has a $ \mathcal{O}(1) $ complexity.

JsonArrayView Corrade::Utility::JsonToken::asArray() const

Get an iterable array.

Expects that the token is a Type::Array and isParsed() is set. See Iterating objects and arrays for more information. Iteration through array values is performed using next(), which has a $ \mathcal{O}(1) $ complexity.

const JsonToken* Corrade::Utility::JsonToken::find(Containers::StringView key) const

Find an object value by key.

Expects that the token is a Type::Object, isParsed() is set and its keys have isParsed() set as well. If key is found, returns the child token corresponding to its value, otherwise returns nullptr.

Note that there's no acceleration structure built at parse time and thus the operation has a $ \mathcal{O}(n) $ complexity, where $ n $ is the number of keys in given object. When looking up many keys in a larger object, it's thus recommended to iterate through asObject() than to repeatedly call this function.

const JsonToken* Corrade::Utility::JsonToken::find(std::size_t index) const

Find an array value by index.

Expects that the token is a Type::Array and isParsed() is set. If index is found, returns the corresponding token, otherwise returns nullptr.

Note that there's no acceleration structure built at parse time and thus the operation has a $ \mathcal{O}(n) $ complexity, where $ n $ is the number of items in given array. When looking up many indices in a larger array, it's thus recommended to iterate through asArray() than to repeatedly call this function.

const JsonToken& Corrade::Utility::JsonToken::operator[](Containers::StringView key) const

Access an object value by key.

Compared to find(Containers::StringView) const expects also that key exists.

const JsonToken& Corrade::Utility::JsonToken::operator[](std::size_t index) const

Access an array value by index.

Compared to find(std::size_t) const expects also that index exists.

std::nullptr_t Corrade::Utility::JsonToken::asNull() const

Get a parsed null value.

Expects that the token is Type::Null and isParsed() is set. If not, use Json::parseNull() instead.

bool Corrade::Utility::JsonToken::asBool() const

Get a parsed boolean value.

Expects that the token is Type::Bool and isParsed() is set. If not, use Json::parseBool() instead.

double Corrade::Utility::JsonToken::asDouble() const

Get a parsed 64-bit floating-point value.

Expects that the token is already parsed as a ParsedType::Double. If not, use Json::parseDouble() instead.

float Corrade::Utility::JsonToken::asFloat() const

Get a parsed 32-bit floating-point value.

Expects that the token is already parsed as a ParsedType::Float. If not, use Json::parseFloat() instead.

std::uint32_t Corrade::Utility::JsonToken::asUnsignedInt() const

Get a parsed unsigned 32-bit integer value.

Expects that the token is already parsed as a ParsedType::UnsignedInt. If not, use Json::parseUnsignedInt() instead.

std::int32_t Corrade::Utility::JsonToken::asInt() const

Get a parsed signed 32-bit integer value.

Expects that the token is already parsed as a ParsedType::Int. If not, use Json::parseInt() instead.

std::uint64_t Corrade::Utility::JsonToken::asUnsignedLong() const

Get a parsed unsigned 52-bit integer value.

Expects that the value is already parsed as a ParsedType::UnsignedLong. If not, use Json::parseUnsignedLong() instead.

std::int64_t Corrade::Utility::JsonToken::asLong() const

Get a parsed signed 53-bit integer value.

Expects that the token is already parsed as a ParsedType::Long. If not, use Json::parseLong() instead.

std::size_t Corrade::Utility::JsonToken::asSize() const

Get a parsed size value.

Expects that the value is already parsed as a ParsedType::Size. If not, use Json::parseSize() instead.

Containers::StringView Corrade::Utility::JsonToken::asString() const

Get a parsed string value.

Expects that the token is a Type::String and isParsed() is set. If not, use Json::parseString() instead. If Json::fromString() was called with a global literal and the string didn't contain any escape sequences, the returned view has Containers::StringViewFlag::Global set. If not, the view points to data owned by the originating Json instance.

Containers::StridedArrayView1D<const bool> Corrade::Utility::JsonToken::asBoolArray(std::size_t expectedSize = 0) const

Get a parsed boolean array.

Expects that the token is a Type::Array consisting of just Type::Bool tokens and exactly expectedSize elements if it's not 0, already parsed. If not, use Json::parseBoolArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const double> Corrade::Utility::JsonToken::asDoubleArray(std::size_t expectedSize = 0) const

Get a parsed 64-bit floating-point array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::Double. If not, use Json::parseDoubleArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const float> Corrade::Utility::JsonToken::asFloatArray(std::size_t expectedSize = 0) const

Get a parsed 32-bit floating-point array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::Float. If not, use Json::parseFloatArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const std::uint32_t> Corrade::Utility::JsonToken::asUnsignedIntArray(std::size_t expectedSize = 0) const

Get a parsed unsigned 32-bit integer array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::UnsignedInt. If not, use Json::parseUnsignedIntArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const std::int32_t> Corrade::Utility::JsonToken::asIntArray(std::size_t expectedSize = 0) const

Get a parsed signed 32-bit integer array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::Int. If not, use Json::parseIntArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const std::uint64_t> Corrade::Utility::JsonToken::asUnsignedLongArray(std::size_t expectedSize = 0) const

Get a parsed unsigned 52-bit integer array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::UnsignedLong. If not, use Json::parseUnsignedLongArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const std::int64_t> Corrade::Utility::JsonToken::asLongArray(std::size_t expectedSize = 0) const

Get a parsed signed 53-bit integer value array.

Expects that the token is a Type::Array consisting of just numeric tokens and exactly expectedSize elements if it's not 0, already parsed as ParsedType::Long. If not, use Json::parseLongArray() instead. The returned view points to data owned by the originating Json instance.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Containers::StridedArrayView1D<const std::size_t> Corrade::Utility::JsonToken::asSizeArray(std::size_t expectedSize = 0) const

Get a parsed size array.

Convenience function that calls into asUnsignedIntArray() on 32-bit targets and into asUnsignedLongArray() on 64-bit.

The expectedSize parameter is ignored on a CORRADE_NO_ASSERT build.

Debug& operator<<(Debug& debug, JsonToken::Type value)

Debug output operator.

Debug& operator<<(Debug& debug, JsonToken::ParsedType value)

Debug output operator.