Corrade::Utility::JsonToken class new in Git master
#include <Corrade/Utility/Json.h>

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 commonArrayType() const -> Containers::Optional<Type>: Common array type.
auto isParsed() const -> bool: Whether the token value is parsed.
auto parsedType() const -> ParsedType: Parsed token type.
auto commonParsedArrayType() const -> Containers::Optional<ParsedType>: Common parsed array 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 asBitArray(std::size_t expectedSize = 0) const -> Containers::StridedBitArrayView1D: Get a parsed boolean array.
auto asBoolArray(std::size_t expectedSize = 0) const -> Containers::StridedArrayView1D<const bool> deprecated in Git master: 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.
auto asStringArray(std::size_t expectedSize = 0) const -> Containers::StringIterable: Get a parsed string 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. See also children(), firstChild(), next()
Array	An array, `[]`. Its immediate children are values. isParsed() is set always. See also children(), firstChild(), next()
Null	A `null` value. Unless isParsed() is set, the value is not guaranteed to be valid. See also asNull(), Json::Option::ParseLiterals, Json::parseLiterals(), Json::parseNull()
Bool	A `true` or `false` value. Unless isParsed() is set, the value is not guaranteed to be valid. See also asBool(), Json::Option::ParseLiterals, Json::parseLiterals(), Json::parseBool()
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. See also asDouble(), asFloat(), asUnsignedInt(), asInt(), asUnsignedLong(), asLong(), asSize(), Json::Option::ParseDoubles, Json::Option::ParseFloats, Json::parseDouble(), Json::parseFloat(), Json::parseUnsignedInt(), Json::parseInt(), Json::parseUnsignedLong(), Json::parseLong(), Json::parseSize()
String	A string. Unless isParsed() is set, the value is not guaranteed to be valid. See also asString(), Json::Option::ParseStringKeys, Json::Option::ParseStrings, Json::parseStringKeys(), Json::parseStrings(), Json::parseString()

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. See also ParsedType::Size, Json::parseSizes()
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). See also ParsedType::Size, Json::parseSizes()
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. See also Json::parseSizes()
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().

Containers::Optional<Type> Corrade::Utility::JsonToken::commonArrayType() const

Common array type.

Returns a type of the array tokens or Containers::NullOpt if the array is heterogeneous or empty. Expects that type() is JsonToken::Type::Array, but isParsed() doesn't have to be set.

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.

Containers::Optional<ParsedType> Corrade::Utility::JsonToken::commonParsedArrayType() const

Common parsed array type.

Returns a parsed type of the array tokens or Containers::NullOpt if the array is not parsed at all, only partially, to a heterogeneous ParsedType or is empty. Expects that type() is JsonToken::Type::Array. The returned value is never ParsedType::None, however ParsedType::Other can be returned also if the array is a combination of nulls and bools, for example — use this function in combination with commonArrayType() to distinguish that case. The returned value is independent from isParsed() being set or not.

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. For an array with a common type that isn't Type::Object and Type::Array returns the array size.

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 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 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 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 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 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 complexity, where 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 complexity, where 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::StridedBitArrayView1D Corrade::Utility::JsonToken::asBitArray(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::parseBitArray() instead. The returned view points to data owned by the originating Json instance.