JsonValueExtensions

Namespace: SnowBank.Data.Json · class

Extension methods for JsonValue and other derived types

Methods

As

static JsonValue As(JsonValue value, JsonValue missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static string As(JsonValue value, string missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static bool As(JsonValue value, bool missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static int As(JsonValue value, int missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static long As(JsonValue value, long missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static double As(JsonValue value, double missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static float As(JsonValue value, float missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Half As(JsonValue value, Half missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Guid As(JsonValue value, Guid missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Uuid128 As(JsonValue value, Uuid128 missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Uuid64 As(JsonValue value, Uuid64 missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static TimeSpan As(JsonValue value, TimeSpan missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static DateTime As(JsonValue value, DateTime missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static DateTimeOffset As(JsonValue value, DateTimeOffset missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Instant As(JsonValue value, Instant missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static Duration As(JsonValue value, Duration missingValue)

Returns the converted value, or a fallback value if it is missing

• value — JSON value to convert
• missingValue — Fallback value

Returns: The converted value, or missingValue if it is null or missing

static TValue As<TValue>(JsonValue value, TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Converts this value into the specified CLR type, with a fallback value if it is null or missing.

If the value is or "null-like", this will return the .

AsArray

static JsonArray AsArray(JsonValue value)

Returns this value as a required JSON Array.

• value — Value that must be a JSON Array.

Returns: The same instance cast as JsonArray, Throws an exception if the value is null, missing, or any other type.

AsArrayOrDefault

static JsonArray AsArrayOrDefault(JsonValue value)

Returns this value as a JSON Array, or null if it is null or missing.

• value — Value that can either be a JSON Array or null or missing.

Returns: The same instance cast as JsonArray, or null if it was null or missing. Throws an exception if the value is any other type.

AsArrayOrEmpty

static JsonArray AsArrayOrEmpty(JsonValue value)

Returns this value as a JSON Array, or an empty (read-only) object it is null or missing.

• value — Value that can either be a JSON Array or null or missing.

Returns: The same instance cast as JsonArray, or the Empty singleton if it was null or missing. Throws an exception if the value is any other type.

AsBoolean

static JsonBoolean AsBoolean(JsonValue value)

Ensures that a JsonValue is is non-null JsonString.

• value — JSON value expected to be a string

Returns: Value cast into a JsonString if it was a string literal, or an exception if it is something else.

AsBooleanOrDefault

static JsonBoolean AsBooleanOrDefault(JsonValue value)

Ensures that a JsonValue is is non-null JsonString.

• value — JSON value expected to be either a string literal, or null/missing

Returns: Value cast into a JsonString it it was a string literal, null if it was null or missing, or an exception if it is something else.

AsNumber

static JsonNumber AsNumber(JsonValue value)

Ensures that a JsonValue is is non-null JsonNumber.

• value — JSON value expected to be a string

Returns: Value cast into a JsonNumber if it was a number literal, or an exception if it is something else.

AsNumberOrDefault

static JsonNumber AsNumberOrDefault(JsonValue value)

Ensures that a JsonValue is is non-null JsonNumber.

• value — JSON value expected to be a string

Returns: Value cast into a JsonNumber if it was a number literal, or an exception if it is something else.

AsObject

static JsonObject AsObject(JsonValue value)

Returns this value as a required JSON Object.

• value — Value that must be a JSON Object.

Returns: The same instance cast as JsonObject, Throws an exception if the value is null, missing, or any other type.

AsObjectOrDefault

static JsonObject AsObjectOrDefault(JsonValue value)

Returns this value as JSON Object, or null if it is null or missing.

• value — Value that can either be a JSON Object or null or missing.

Returns: The same instance cast as JsonObject, or null if it was null or missing. Throws an exception if the value is any other type.

AsObjectOrEmpty

static JsonObject AsObjectOrEmpty(JsonValue value)

Returns this value as a JSON Object, or an empty (read-only) object it is null or missing.

• value — Value that can either be a JSON Object or null or missing.

Returns: The same instance cast as JsonObject, or the Empty singleton if it was null or missing. Throws an exception if the value is any other type.

AsString

static JsonString AsString(JsonValue value)

Ensures that a JsonValue is is non-null JsonString.

• value — JSON value expected to be a string

Returns: Value cast into a JsonString if it was a string literal, or an exception if it is something else.

AsStringOrDefault

static JsonString AsStringOrDefault(JsonValue value)

Ensures that a JsonValue is is non-null JsonString.

• value — JSON value expected to be either a string literal, or null/missing

Returns: Value cast into a JsonString it it was a string literal, null if it was null or missing, or an exception if it is something else.

GetArray

static TValue[] GetArray<TValue>(JsonValue self, string key, TValue[] defaultValue)

Return the value of the optional field with the specified name, converted into an array with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — Values returned if the field is null or missing.

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static TValue[] GetArray<TValue>(JsonValue self, string key, ReadOnlySpan<TValue> defaultValue)

Return the value of the optional field with the specified name, converted into an array with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — Values returned if the field is null or missing.

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static TValue[] GetArray<TValue>(JsonValue self, string key, TValue[] defaultValue, ICrystalJsonTypeResolver resolver)

Return the value of the optional field with the specified name, converted into an array with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — Values returned if the field is null or missing.
• resolver — Optional custom type resolver

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static TValue[] GetArray<TValue>(JsonValue self, string key, ReadOnlySpan<TValue> defaultValue, ICrystalJsonTypeResolver resolver)

Return the value of the optional field with the specified name, converted into an array with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — Values returned if the field is null or missing.
• resolver — Optional custom type resolver

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static TValue[] GetArray<TValue>(JsonValue self, string key, TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null, string message = null)

Returns the value of the required field with the specified name, converted into an array with elements of type TValue

• self — Parent object
• key — Name of the field
• resolver — Optional custom type resolver
• message — Optional error message if the required array is null or missing

Returns: Array of values converted into instances of type TValue

GetDictionary

static Dictionary<TKey, TValue> GetDictionary<TKey, TValue>(JsonValue self, string key, Dictionary<TKey, TValue> defaultValue)

static Dictionary<TKey, TValue> GetDictionary<TKey, TValue>(JsonValue self, string key, ICrystalJsonTypeResolver resolver = null, string message = null)

Return the value of the required field with the specified name, converted into a dictionary with keys of type TKey and elements of type TValue

• self — Parent object
• key — Name of the field
• resolver — Optional custom type resolver
• message — Optional error message if the required array is null or missing

Returns: Dictionary of keys and values converted into instances of type TKey and TValue respectively.

static Dictionary<TKey, TValue> GetDictionary<TKey, TValue>(JsonValue self, string key, Dictionary<TKey, TValue> defaultValue, ICrystalJsonTypeResolver resolver)

Return the value of the optional field with the specified name, converted into a dictionary with keys of type TKey and elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — Dictionary returned if the field is null or missing.
• resolver — Optional custom type resolver

Returns: Dictionary of keys and values converted into instances of type TKey and TValue respectively, or defaultValue if the field was null or missing.

GetList

static List<TValue> GetList<TValue>(JsonValue self, string key, List<TValue> defaultValue)

Return the value of the optional field with the specified name, converted into a list with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — List returned if the field is null or missing.

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static List<TValue> GetList<TValue>(JsonValue self, string key, List<TValue> defaultValue, ICrystalJsonTypeResolver resolver)

Return the value of the optional field with the specified name, converted into a list with elements of type TValue

• self — Parent object
• key — Name of the field
• defaultValue — List returned if the field is null or missing.
• resolver — Optional custom type resolver

Returns: Array of values converted into instances of type TValue, or defaultValue if the field was null or missing.

static List<TValue> GetList<TValue>(JsonValue self, string key, TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null, string message = null)

Return the value of the required field with the specified name, converted into a list with elements of type TValue

• self — Parent object
• key — Name of the field
• resolver — Optional custom type resolver
• message — Optional error message if the required array is null or missing

Returns: List of values converted into instances of type TValue

IsError

static bool IsError(JsonValue value)

Tests if a JSON value is Error

• value — JSON value

Returns: true if value is equal to the Error singleton.

IsMissing

static bool IsMissing(JsonValue value)

Tests if a JSON value is Missing

• value — JSON value

Returns: true if value is equal to the Missing singleton.

is not considered missing (it is an explicit null)

IsNullOrMissing

static bool IsNullOrMissing(JsonValue value)

Tests if a JSON value is null, or null-like

• value — JSON Value

Returns: true if value is null, or any instance of type JsonNull

OrEmpty

static JsonObject OrEmpty(JsonObject self)

Returns either the object itself, or an empty read-only object if it was missing

static JsonArray OrEmpty(JsonArray self)

Returns either the array itself, or an empty read-only array if it was missing

Required

static JsonValue Required(JsonValue value)

Ensures that a JSON value is not null> or missing

• value — JSON value

Returns: The same instance if the value is non-null. Throws an exception if it is null or missing

static JsonArray Required(JsonArray value)

Ensures that a JSON Array is not null

• value — JSON Array

Returns: The same instance if not null. Throws an exception if null

static JsonObject Required(JsonObject value)

Ensures that a JSON Object is not null

• value — JSON Object

Returns: The same instance if not null. Throws an exception if null

static TValue Required<TValue>(JsonValue value, ICrystalJsonTypeResolver resolver = null)

Converts this required JsonValue into an instance of the specified type.

• value — JSON value to be converted
• resolver — Optional type resolver used to bind the value into a managed CLR type (DefaultResolver is omitted)

RequiredField

static JsonValue RequiredField(JsonValue value, string field, string message = null)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value of the field in the parent object.
• field — Name of the field in the parent object.
• message — Message of the exception thrown if the value is null or missing

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

static JsonValue RequiredField(JsonValue value, ReadOnlySpan<char> field, string message = null)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value of the field in the parent object.
• field — Name of the field in the parent object.
• message — Message of the exception thrown if the value is null or missing

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

static JsonValue RequiredField(JsonValue value, ReadOnlyMemory<char> field, string message = null)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value of the field in the parent object.
• field — Name of the field in the parent object.
• message — Message of the exception thrown if the value is null or missing

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

RequiredIndex

static JsonValue RequiredIndex(JsonValue value, int index, string message = null)

Ensures that a JSON value is not null> or missing

• value — JSON value that must not be null, or missing
• index — Array index
• message — Error message

Returns: The same instance if the value is non-null. Throws an exception if it is null or missing

static JsonValue RequiredIndex(JsonValue value, Index index, string message = null)

Ensures that a JSON value is not null> or missing

• value — JSON value that must not be null, or missing
• index — Array index
• message — Error message

Returns: The same instance if the value is non-null. Throws an exception if it is null or missing

RequiredPath

static JsonValue RequiredPath(JsonValue value, string path)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value at the specified path in the parent object.
• path — Path to a field

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

static JsonValue RequiredPath(JsonValue value, ReadOnlyMemory<char> path)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value at the specified path in the parent object.
• path — Path to a field

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

static JsonValue RequiredPath(JsonValue value, JsonPath path)

Ensures that the value of a field in a JSON Object is not null or missing

• value — Value at the specified path in the parent object.
• path — Path to a field

Returns: The same value, if it is not null or missing; otherwise, an exception is thrown

ToJsonBytes

static byte[] ToJsonBytes(JsonValue value)

Serializes a JsonValue into a byte array, using the default settings

• value — JSON value to serialize

Returns: Array of the utf-8 encoded text representation of the JSON value

Only call this when interacting with legacy API that only accept byte[] arrays. Prefer that will reduce the number of needed memory copies and allocations

static byte[] ToJsonBytes(JsonValue value, CrystalJsonSettings settings)

Serializes a JsonValue into a byte array, using custom settings

• value — JSON value to serialize
• settings — Custom serialization settings

Returns: Array of the utf-8 encoded text representation of the JSON value

Only call this when interacting with legacy API that only accept byte[] arrays. Prefer that will reduce the number of needed memory copies and allocations

ToJsonCompact

static string ToJsonCompact(JsonValue value)

Serializes a JsonValue into the most compact text literal possible

• value — JSON value to serialize

Note: if the JSON has to be sent over HTTP, or stored on disk, prefer or that will return the same result but already utf-8 encoded

ToJsonIndented

static string ToJsonIndented(JsonValue value)

Serializes a JsonValue into a human-friendly indented text representation (for logging, console output, etc...)

• value — JSON value to serialize

ToJsonObject

static JsonObject ToJsonObject(IEnumerable<KeyValuePair<string, JsonValue>> items, IEqualityComparer<string> comparer = null)

static JsonObject ToJsonObject<TValue>(IEnumerable<KeyValuePair<string, TValue>> items, IEqualityComparer<string> comparer = null)

static JsonObject ToJsonObject<TValue>(IEnumerable<KeyValuePair<string, TValue>> items, Func<TValue, JsonValue> valueSelector, IEqualityComparer<string> comparer = null)

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

static JsonObject ToJsonObject<TElement, TValue>(IEnumerable<TElement> source, Func<TElement, string> keySelector, Func<TElement, TValue> valueSelector, IEqualityComparer<string> comparer = null)

ToJsonSlice

static Slice ToJsonSlice(JsonValue value, CrystalJsonSettings settings = null)

Serializes a JsonValue into a Slice, using custom settings

• value — JSON value to serialize
• settings — Custom serialization settings

Returns: Slice that contains the utf-8 encoded text representation of the JSON value

static Slice ToJsonSlice<TJsonSerializable>(TJsonSerializable value, CrystalJsonSettings settings = null)

Serializes a IJsonSerializable value into a Slice, using custom settings

• value — Instance to serialize
• settings — Custom serialization settings

Returns: Slice that contains the utf-8 encoded text representation of the JSON value

static SliceOwner ToJsonSlice(JsonValue value, ArrayPool<byte> pool, CrystalJsonSettings settings = null)

Serializes a JsonValue into a Slice, using custom settings

• value — JSON value to serialize
• pool — Pool used to allocate the content of the slice (use Shared if null)
• settings — Custom serialization settings

Returns: Slice that contains the utf-8 encoded text representation of the JSON value

static SliceOwner ToJsonSlice<TJsonSerializable>(TJsonSerializable value, ArrayPool<byte> pool, CrystalJsonSettings settings = null)

Serializes a IJsonSerializable value into a Slice, using custom settings

• value — Instance to serialize
• pool — Pool used to allocate the content of the slice (use Shared if null)
• settings — Custom serialization settings

Returns: Slice that contains the utf-8 encoded text representation of the JSON value

ToJsonText

static string ToJsonText(JsonValue value)

Serializes a JsonValue into a text literal possible

• value — JSON value to serialize

Note: if the JSON has to be sent over HTTP, or stored on disk, prefer or that will return the same result but already utf-8 encoded

ToJsonTextCompact

static string ToJsonTextCompact(JsonValue value)

Serializes a JsonValue into the most compact text literal possible

• value — JSON value to serialize

Note: if the JSON has to be sent over HTTP, or stored on disk, prefer or that will return the same result but already utf-8 encoded

ToJsonTextIndented

static string ToJsonTextIndented(JsonValue value)

Serializes a JsonValue into a human-friendly indented text representation (for logging, console output, etc...)

• value — JSON value to serialize