JSON Values

Introduction

JsonValue is a copy-on-write tree for JSON null, Boolean, integer, floating-point, string, array, and object values. JsonParseOptions controls limits and JsonFormatOptions controls compact or indented output. See Parsing and Rendering JSON Data for parsing, traversal, and serialization examples.

Text arguments accept String, StringEditor, and Core string literals directly, including when passed to set() or append(). Stored text retains its value if the original editor is changed later.

Interface

typedef util::List<JsonValue> erbsland::data::json::JsonArray: Ordered JSON array storage.

typedef text::StringMap<JsonValue> erbsland::data::json::JsonObject: Ordered JSON object storage.

class JsonFormatOptions

Options for serializing a JSON value.

Public Functions

inline constexpr unit::CpCount indentation() const noexcept: Get the spaces used for each indentation level; zero selects compact output.

inline constexpr JsonFormatOptions &setIndentation(const unit::CpCount value) noexcept: Set the spaces used for each indentation level.

inline constexpr text::EscapeAmount escapeAmount() const noexcept: Get the JSON string escape amount.

inline constexpr JsonFormatOptions &setEscapeAmount(const text::EscapeAmount value) noexcept: Set the JSON string escape amount.

Public Static Functions

static inline constexpr JsonFormatOptions compact() noexcept: Create compact formatting options.

static inline constexpr JsonFormatOptions pretty() noexcept: Create pretty formatting options using two spaces.

class JsonParseOptions

Safety limits for parsing JSON documents.

Public Functions

inline constexpr unit::ByteCount maximumInputLength() const noexcept: Get the maximum source length in bytes.

inline constexpr JsonParseOptions &setMaximumInputLength(const unit::ByteCount value) noexcept: Set the maximum source length in bytes.

inline constexpr unit::ItemCount maximumNesting() const noexcept: Get the maximum number of open container levels.

inline constexpr JsonParseOptions &setMaximumNesting(const unit::ItemCount value) noexcept: Set the maximum number of open container levels.

inline constexpr unit::ItemCount maximumValueCount() const noexcept: Get the maximum value count, including the root.

inline constexpr JsonParseOptions &setMaximumValueCount(const unit::ItemCount value) noexcept: Set the maximum value count, including the root.

inline constexpr unit::CpCount maximumStringLength() const noexcept: Get the maximum decoded key or string length in Unicode code points.

inline constexpr JsonParseOptions &setMaximumStringLength(const unit::CpCount value) noexcept: Set the maximum decoded key or string length in Unicode code points.

Public Static Attributes

static constexpr auto cDefaultMaximumInputLength = unit::ByteCount{16U * 1024U * 1024U}: Input limit.

static constexpr auto cDefaultMaximumNesting = unit::ItemCount{64U}: Nesting limit.

static constexpr auto cDefaultMaximumValueCount = unit::ItemCount{1'000'000U}: Value limit.

static constexpr auto cDefaultMaximumStringLength = unit::CpCount{8U * 1024U * 1024U}: text::String limit.

enum class erbsland::data::json::JsonType : uint8_t

The semantic type of a JSON value.

Values:

enumerator Null: The null value.

enumerator Bool: A boolean value.

enumerator Number: An integer or floating-point number.

enumerator Text: A Unicode string.

enumerator Array: An ordered array.

enumerator Object: A string-keyed object.

class JsonValue

A copy-on-write JSON value tree.

See: Text Documents and Rendering

Public Functions

JsonValue() noexcept = default: Create the null value.

JsonValue(bool value): Create a boolean value.

JsonValue(int64_t value): Create an integer number.

JsonValue(double value)

Create a floating-point number.

Parameters:: value – The floating-point number to store. Must be finite.

JsonValue(text::String value): Create a text value.

template<typename tText> inline JsonValue(tText &&value)

Create a text value from an implicitly convertible string, editor, or literal.

Parameters:: value – The text to store.

JsonValue(JsonArray value): Create an array value.

JsonValue(JsonObject value): Create an object value.

template<std::integral T> inline JsonValue(const T value)

Create an integer number from another integral type.

Parameters:: value – The integer to store. Must fit in int64_t.

JsonType type() const noexcept: Get the semantic JSON type.

bool is(JsonType expected) const noexcept: Test whether this value has the requested type.

bool isPrimitive() const noexcept: Test whether this value is null, boolean, number, or text.

unit::ItemCount itemCount() const noexcept: Get the number of array elements or object entries, or zero for a primitive.

JsonValue get(unit::ItemIndex index) const: Get an array element, or null if this is not an array or the index is invalid.

JsonValue getOrThrow(unit::ItemIndex index) const

Get an array element.

This value must be an array.

Parameters:: index – The array element index.
Throws:: err::OutOfRangeError – If the index does not identify an array element.

JsonValue get(const text::String &key) const: Get an object member, or null if this is not an object or the key is missing.

JsonValue getOrThrow(const text::String &key) const

Get an object member.

This value must be an object.

Parameters:: key – The member key.
Throws:: err::NotFoundError – If the requested key is absent.

template<typename T> std::optional<T> get() const: Get this value as a supported native type.

template<typename T> T get(T fallback) const: Get this value as a supported native type, or return a fallback.

template<typename T> T getOrThrow() const

Get this value as a supported native type.

This value must be representable as T.

std::optional<bool> getBool() const noexcept: Get a boolean value.

bool getBool(bool fallback) const noexcept: Get a boolean value or a fallback.

bool getBoolOrThrow() const

Get a boolean value.

This value must be a boolean.

std::optional<double> getNumber() const noexcept: Get a number as a double.

double getNumber(double fallback) const noexcept: Get a number as a double or a fallback.

double getNumberOrThrow() const

Get a number as a double.

This value must be a number.

std::optional<text::String> getText() const noexcept: Get a text value.

text::String getText(text::String fallback) const noexcept: Get a text value or a fallback.

text::String getTextOrThrow() const

Get a text value.

This value must be text.

JsonValue &set(unit::ItemIndex index, JsonValue value)

Replace an array element, or append when index == itemCount().

This value must be an array.

Parameters:

index – The element position. Must be at most itemCount(). The end position appends a new element.
value – The replacement or appended value.

JsonValue &set(const text::String &key, JsonValue value)

Insert or replace an object member.

This value must be an object.

JsonValue &append(JsonValue value)

Append an array element.

This value must be an array.

text::String toString(JsonFormatOptions options = {}) const: Serialize this value as valid JSON.

Public Static Functions

static auto fromString(const text::String &text, JsonParseOptions options = {}) noexcept -> std::optional<JsonValue>: Parse one complete JSON value.

Note

UTF-8 errors are ignored, validate the string before parsing if this is relevant.

static JsonValue fromStringOrThrow(const text::String &text, JsonParseOptions options = {})

Parse one complete JSON value.

Note

UTF-8 errors are ignored, validate the string before parsing if this is relevant.

Throws:: err::ParseError – If the document is invalid or exceeds configured limits.