SnowBank SDK SnowBank SDK
EN

JsonObject.ReadOnly

Namespace: SnowBank.Data.Json · class

Operations for read-only JSON objects

Methods

Create

static JsonObject Create()

Returns a read-only empty object, that cannot be modified

This method will always return the same Empty singleton.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer)

Creates a new empty read-only JSON object

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.

For a mutable object, see

static JsonObject Create((string, JsonValue) item)

Creates a new immutable JSON object with a single field

  • item — Name and value of the field

Returns: JSON object of size 1, that cannot be modified.

For a mutable object, see Create

static JsonObject Create(IDictionary<string, JsonValue> items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(ReadOnlySpan<KeyValuePair<string, JsonValue>> items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(ReadOnlySpan<(string, JsonValue)> items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(KeyValuePair<string, JsonValue>[] items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create((string, JsonValue)[] items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEnumerable<KeyValuePair<string, JsonValue>> items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEnumerable<(string, JsonValue)> items)

Creates a new JSON object with the specified items

  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(string key0, JsonValue value0)

Creates a new immutable JSON object with a single field

  • key0 — Name of the field
  • value0 — Value of the field

Returns: JSON object of size 1, that cannot be modified.

For a mutable object, see

static JsonObject Create((string, JsonValue) item1, (string, JsonValue) item2)

Creates a new immutable JSON object with 2 fields

  • item1 — Name and value of the first field
  • item2 — Name and value of the second field

Returns: JSON object of size 2, that cannot be modified.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, ReadOnlySpan<KeyValuePair<string, JsonValue>> items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, ReadOnlySpan<(string, JsonValue)> items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, KeyValuePair<string, JsonValue>[] items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, (string, JsonValue)[] items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, IEnumerable<KeyValuePair<string, JsonValue>> items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create(IEqualityComparer<string> comparer, IEnumerable<(string, JsonValue)> items)

Creates a new JSON object with the specified items

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Map of key/values to copy

Returns: New JSON object with the same elements in items

Adding or removing items in this new object will not modify items (and vice versa), but any change to a mutable children will be reflected in both.

For a mutable object, see Create

static JsonObject Create((string, JsonValue) item1, (string, JsonValue) item2, (string, JsonValue) item3)

Creates a new immutable JSON object with 3 fields

  • item1 — Name and value of the first field
  • item2 — Name and value of the second field
  • item3 — Name and value of the third field

Returns: JSON object of size 2, that cannot be modified.

For a mutable object, see Create

static JsonObject Create((string, JsonValue) item1, (string, JsonValue) item2, (string, JsonValue) item3, (string, JsonValue) item4)

Creates a new immutable JSON object with 4 fields

  • item1 — Name and value of the first field
  • item2 — Name and value of the second field
  • item3 — Name and value of the third field
  • item4 — Name and value of the fourth field

Returns: JSON object of size 2, that cannot be modified.

For a mutable object, see Create

CreateBoxed

static JsonObject CreateBoxed(IDictionary<string, object> members)

Converts an untyped dictionary into a JSON Object

Returns: Corresponding immutable JSON Object

This should only be used to interface with legacy APIs that generate a Dictionary<string, object>.

static JsonObject CreateBoxed(IEqualityComparer<string> comparer, IDictionary<string, object> members)

Converts an untyped dictionary into a JSON Object

Returns: Corresponding immutable JSON Object

This should only be used to interface with legacy APIs that generate a Dictionary<string, object>.

FromObject

static JsonObject FromObject<TValue>(TValue value, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Converts an instance of type TValue into the equivalent read-only JSON Object.

  • value — Instance to convert.
  • settings — Serialization settings (use default JSON settings if null)
  • resolver — Custom type resolver (use default behavior if null)

Returns: Corresponding immutable JSON Object, or null if value is null

The JSON Object that is returned is read-only, and can safely be cached or shared. If you need a mutable instance, consider calling instead.

FromValues

static JsonObject FromValues<TValue>(IDictionary<string, TValue> members, Func<TValue, JsonValue> valueSelector)

Creates a read-only JSON Object from an existing dictionary, using a custom JSON converter.

  • members — Dictionary that must be converted.
  • valueSelector — Handler that is called for each value of the dictionary, and must return the converted JSON value.

Returns: Corresponding JSON object, that cannot be modified.

static JsonObject FromValues<TValue>(IEnumerable<KeyValuePair<string, TValue>> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a read-only JSON Object from a list of key/value pairs.

  • items — Sequence of key/value pairs that will become the fields of the new JSON Object. There must not be any duplicate key, or an exception will be thrown.
  • settings — Serialization settings (use default JSON settings if null)
  • resolver — Custom type resolver (use default behavior if null)

Returns: Corresponding JSON object, that cannot be modified.

static JsonObject FromValues<TValue>(IEqualityComparer<string> comparer, IDictionary<string, TValue> members, Func<TValue, JsonValue> valueSelector)

Creates a read-only JSON Object from an existing dictionary, using a custom JSON converter.

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • members — Dictionary that must be converted.
  • valueSelector — Handler that is called for each value of the dictionary, and must return the converted JSON value.

Returns: Corresponding JSON object, that cannot be modified.

static JsonObject FromValues<TElement>(IEnumerable<TElement> source, Func<TElement, string> keySelector, Func<TElement, JsonValue> valueSelector)

Creates a read-only JSON Object from a sequence of elements, using a custom key and value selector.

  • source — Sequence of elements to convert
  • keySelector — Handler that is called for each element of the sequence, and should return the corresponding unique key.
  • valueSelector — Handler that is called for each element of the sequence, and should return the corresponding JSON value.

Returns: Corresponding JSON object, that cannot be modified

static JsonObject FromValues<TElement, TValue>(IEnumerable<TElement> source, Func<TElement, string> keySelector, Func<TElement, TValue> valueSelector)

Creates a read-only JSON Object from a sequence of elements, using a custom key and value selector.

  • source — Sequence of elements to convert
  • keySelector — Handler that is called for each element of the sequence, and should return the corresponding unique key.
  • valueSelector — Handler that is called for each element of the sequence, and should return the corresponding value, that will in turn be converted into JSON.

Returns: Corresponding JSON object, that cannot be modified

static JsonObject FromValues<TValue>(IEqualityComparer<string> comparer, IEnumerable<KeyValuePair<string, TValue>> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a read-only JSON Object from a list of key/value pairs.

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • items — Sequence of key/value pairs that will become the fields of the new JSON Object. There must not be any duplicate key, or an exception will be thrown.
  • settings — Serialization settings (use default JSON settings if null)
  • resolver — Custom type resolver (use default behavior if null)

Returns: Corresponding JSON object, that cannot be modified.

static JsonObject FromValues<TElement>(IEqualityComparer<string> comparer, IEnumerable<TElement> source, Func<TElement, string> keySelector, Func<TElement, JsonValue> valueSelector)

Creates a read-only JSON Object from a sequence of elements, using a custom key and value selector.

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • source — Sequence of elements to convert
  • keySelector — Handler that is called for each element of the sequence, and should return the corresponding unique key.
  • valueSelector — Handler that is called for each element of the sequence, and should return the corresponding JSON value.

Returns: Corresponding JSON object, that cannot be modified

static JsonObject FromValues<TElement, TValue>(IEqualityComparer<string> comparer, IEnumerable<TElement> source, Func<TElement, string> keySelector, Func<TElement, TValue> valueSelector, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a read-only JSON Object from a sequence of elements, using a custom key and value selector.

  • comparer — The IEqualityComparer implementation to use when comparing keys, or null to use the default EqualityComparer for the type of the key.
  • source — Sequence of elements to convert
  • keySelector — Handler that is called for each element of the sequence, and should return the corresponding unique key.
  • valueSelector — Handler that is called for each element of the sequence, and should return the corresponding value, that will in turn be converted into JSON.
  • settings — Serialization settings (use default JSON settings if null)
  • resolver — Custom type resolver (use default behavior if null)

Returns: Corresponding JSON object, that cannot be modified

Parse

static JsonObject Parse(string jsonText, CrystalJsonSettings settings = null)

Parse a string literal containing a JSON Object

  • jsonText — Input text to parse
  • settings — Serialization settings (use default JSON settings if null)

Returns: Corresponding JSON Object. If jsonText is empty or not an object, an exception will be thrown instead.

The JSON object that is returned is immutable, and is safe for use as a singleton, a cached document, or for multithreaded operations. If you require a mutable version, please call

static JsonObject Parse(ReadOnlySpan<char> jsonText, CrystalJsonSettings settings = null)

Parse a string literal containing a JSON Object

  • jsonText — Input text to parse
  • settings — Serialization settings (use default JSON settings if null)

Returns: Corresponding JSON Object. If jsonText is empty or not an object, an exception will be thrown instead.

The JSON object that is returned is immutable, and is safe for use as a singleton, a cached document, or for multithreaded operations. If you require a mutable version, please call

static JsonObject Parse(ReadOnlySpan<byte> jsonBytes, CrystalJsonSettings settings = null)

Parses a buffer containing a document that is expected to be an Object

  • jsonBytes — UTF-8 encoded bytes
  • settings — Serialization settings (use default JSON settings if null)

Returns: Corresponding immutable JSON Object. If jsonBytes is empty or not an Array, an exception will be thrown

The resulting object is immutable and cannot be modified. If you require a mutable array, please use ParseObject instead.

static JsonObject Parse(Slice jsonBytes, CrystalJsonSettings settings = null)

Parses a buffer containing a UTF-8 encoded JSON Object

  • jsonBytes — UTF-8 encoded bytes
  • settings — Serialization settings (use default JSON settings if null)

Returns: Corresponding readonly JSON Object. If jsonBytes is null or empty, will return Missing

Fields

Empty

static readonly JsonObject Empty

Returns an empty, read-only, JSON Object singleton

This instance cannot be modified, and should be used to reduce memory allocations when working with read-only JSON