JsonValue

Namespace: SnowBank.Data.Json · class

Implements: IEquatable<JsonValue>, IComparable<JsonValue>, IJsonSerializable, IFormattable, ISliceSerializable, IConvertible, IParsable<JsonValue>, ISpanParsable<JsonValue>, ISpanFormattable, IUtf8SpanFormattable, INumberBase<JsonValue>, IUtf8SpanParsable<JsonValue>, IAdditionOperators<JsonValue, JsonValue, JsonValue>, IAdditiveIdentity<JsonValue, JsonValue>, IDecrementOperators<JsonValue>, IDivisionOperators<JsonValue, JsonValue, JsonValue>, IEqualityOperators<JsonValue, JsonValue, bool>, IIncrementOperators<JsonValue>, IMultiplicativeIdentity<JsonValue, JsonValue>, IMultiplyOperators<JsonValue, JsonValue, JsonValue>, ISubtractionOperators<JsonValue, JsonValue, JsonValue>, IUnaryNegationOperators<JsonValue, JsonValue>, IUnaryPlusOperators<JsonValue, JsonValue>, IComparisonOperators<JsonValue, JsonValue, bool>

Represents a value in a JSON Document

Remarks

The value can be null or missing (), a literal (, , ), an object () or an array ()

Properties

IsDefault

bool IsDefault { get; }

Tests if this value corresponds to the logical default for this type (0, false, null or missing, ...)

Returns: true for values like 0, false, or null; or false for non-zero integers, true, strings, arrays and objects

The empty string, array and object are NOT considered to be the default value of their type!

JsonNumber.Zero.IsDefault == true, JsonNumber.Return(123).IsDefault == false, JsonString.Return("").IsDefault == false, new JsonArray().IsDefault == false, new JsonObject().IsDefault == false

IsNull

bool IsNull { get; }

Tests if this value is null or missing

IsReadOnly

bool IsReadOnly { get; }

Returns true if this value is read-only, and cannot be modified, or false if it allows mutations.

Only JSON Objects and Arrays can return false. All other "value types" (string, boolean, numbers, ...) are always immutable, and will always be read-only.

If you need to modify a JSON Object or Array that is read-only, you should first create a copy, by calling either Copy or ToMutable, perform any changes required, and then either Freeze the copy, or call ToReadOnly again.

Item

JsonValue Item { get; set; }

Type

JsonType Type { get; }

Type of JSON value (Boolean, String, Number, Object, Array, ...)

Methods

Bind

object Bind(Type type, ICrystalJsonTypeResolver resolver = null)

Bind this value into an instance of the specified type

type — Target managed type
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: An instance of the target type that is equivalent to the original JSON value, if there exists a valid conversion path or convention. Otherwise, an exception will be thrown.

If the target type is a Value Type, the instance will be boxed, which may cause extra memory allocations. Consider calling instance, or use any of the convenience methods like , , ...

JsonNumber.Return(123).Bind(typeof(long)) will return a boxed Int64 with value 123.

TValue Bind<TValue>(TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Bind this value into an instance of type TValue

defaultValue — Default value to return if the current instance is null or missing
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: An instance of the type TValue that is equivalent to the original JSON value, if there exists a valid conversion path. Otherwise, an exception will be thrown.

JsonNumber.Return(123).Bind() will return the value 123.

BindValueType

static object BindValueType<T>(T value, Type type, ICrystalJsonTypeResolver resolver)

Compare

static int Compare(JsonValue left, JsonValue right)

Compares two JSON values, and returns an integer that indicates whether the first value precedes, follows, or occurs in the same position in the sort order as the second value.

CompareTo

int CompareTo(JsonValue other)

Compares two JSON values, and returns an integer that indicates whether the first value precedes, follows, or occurs in the same position in the sort order as the second value.

Contains

bool Contains(JsonValue value)

Tests if the current instance is an array that contains the specified value

Copy

JsonValue Copy()

Creates a deep copy of this value (and all of its children)

Returns: A new instance, isolated from the original.

Any changes to this copy will not have any effect of the original, and vice versa

If the value is an immutable type (like JsonString, JsonNumber, JsonBoolean, ...) then the same instance will be returned.

If the value is an array then a new array containing a

Equals

bool Equals(object obj)

bool Equals(JsonValue other)

Tests if these two JSON values are considered equal, using the relaxed JSON comparison semantics

Two values are considered "equal" if they would produce the same result when serialized using a canonical representation.

Numbers are equal if they represent the "same" number (ie: 1 and 1.0 are equal)

Numbers and strings can be equal, if the later can be parsed into a number equal to the former (ie: 123 and "123" are equal)

Arrays are equal if they have the same length and all their elements are equals pairwise

Objects are equal if they have the same key/value pairs, irrespective of their order.

A Missing field is not considered equal to an explicit Null field, and vice versa

If you require strict equality (ie: "123" and 123 are different), consider calling StrictEquals instead.

static bool Equals(JsonValue left, JsonValue right)

Tests if two JSON values are equivalent

Freeze

JsonValue Freeze()

Prevents any future mutations of this JSON value (of type Object or Array), by recursively freezing it and all of its children.

Returns: The same instance, which is now converted to a read-only instance.

Any future attempt to modify this object, or any of its children that was previously mutable, will fail.

If this instance is already read-only, this will be a no-op.

This should only be used with care, and only on objects that are entirely owned by the called, or that have not been published yet. Freezing a shared mutable object may cause issues for other threads that still were expecting a mutable instance.

FromValue

static JsonValue FromValue(object value)

Converts a boxed instance into a mutable JSON value

value — Instance to convert (primitive, class, struct, array, ...)

Returns: Corresponding JSON value(JsonNumber, JsonObject, JsonArray, ...), or Null if value is null

Consider using instead, if the type is known at compile time, in order to reduce runtime overhead.

static JsonValue FromValue<T>(T value)

Converts a typed value into a mutable JSON value

value — Instance to convert

Returns: Corresponding JSON value(JsonNumber, JsonObject, JsonArray, ...), or Null if value is null

static JsonValue FromValue<T1>((T1) tuple)

static JsonValue FromValue<T1, T2>(in (T1, T2) tuple)

static JsonValue FromValue<T1, T2, T3>(in (T1, T2, T3) tuple)

static JsonValue FromValue<T1, T2, T3, T4>(in (T1, T2, T3, T4) tuple)

static JsonValue FromValue<T1, T2, T3, T4, T5>(in (T1, T2, T3, T4, T5) tuple)

static JsonValue FromValue<T1, T2, T3, T4, T5, T6>(in (T1, T2, T3, T4, T5, T6) tuple)

static JsonValue FromValue<T1, T2, T3, T4, T5, T6, T7>(in (T1, T2, T3, T4, T5, T6, T7) tuple)

static JsonValue FromValue(object value, CrystalJsonSettings settings, ICrystalJsonTypeResolver resolver = null)

Converts a boxed instance into a mutable JSON value

value — Instance to convert (primitive, class, struct, array, ...)
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Corresponding JSON value(JsonNumber, JsonObject, JsonArray, ...), or Null if value is null

Consider using instead, if the type is known at compile time, in order to reduce runtime overhead.

static JsonValue FromValue<T>(T value, CrystalJsonSettings settings, ICrystalJsonTypeResolver resolver = null)

Converts a typed value into a mutable JSON value

value — Instance to convert
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Corresponding JSON value(JsonNumber, JsonObject, JsonArray, ...), or Null if value is null

static JsonValue FromValue(object value, Type declaredType, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Converts a boxed instance into a mutable JSON value

value — Instance to convert (primitive, class, struct, array, ...)
declaredType — Type of the field in the parent container that points to this value (can be a base class or interface)
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Corresponding JSON value(JsonNumber, JsonObject, JsonArray, ...), or Null if value is null

Consider using instead, if the type is known at compile time, in order to reduce runtime overhead.

FromValueReadOnly

static JsonValue FromValueReadOnly(object value)

static JsonValue FromValueReadOnly<T>(T value)

static JsonValue FromValueReadOnly(object value, CrystalJsonSettings settings, ICrystalJsonTypeResolver resolver = null)

static JsonValue FromValueReadOnly<T>(T value, CrystalJsonSettings settings, ICrystalJsonTypeResolver resolver = null)

static JsonValue FromValueReadOnly(object value, Type declaredType, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Get

TValue Get<TValue>(string key)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

({ "Hello": "World"}).Get("Hello") // => "World" ({ "Hello": "123"}).Get("Hello") // => 123 ().Get("Hello") // => Exception ().Get("Hello") // => Exception ().Get<int?>("Hello", null) // => Exception ({ "Hello": null }).Get("Hello") // => Exception ({ "Hello": null }).Get("Hello") // => Exception ({ "Hello": null }).Get<int?>("Hello") // => Exception

TValue Get<TValue>(ReadOnlySpan<char> key)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

TValue Get<TValue>(ReadOnlyMemory<char> key)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

TValue Get<TValue>(int index)

Gets the converted value of the required item at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve

Returns: The value located at the specified index converted into type TValue, or an exception if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(Index index)

Gets the converted value of the required item at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve

Returns: The value located at the specified index converted into type TValue, or an exception if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(string key, TValue defaultValue)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

({ "Hello": "World"}).Get("Hello", "not_found") // => "World" ({ "Hello": "123"}).Get("Hello", -1) // => 123 ().Get("Hello", null) // => ().Get("Hello", "not_found") // => "not_found" ().Get("Hello", -1) // => -1 ().Get<int?>("Hello", null) // => ({ "Hello": null }).Get("Hello", "not_found") // => "not_found" ({ "Hello": null }).Get("Hello") // => Exception ({ "Hello": null }).Get<int?>("Hello") // => Exception

TValue Get<TValue>(ReadOnlySpan<char> key, TValue defaultValue)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

TValue Get<TValue>(ReadOnlyMemory<char> key, TValue defaultValue)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

TValue Get<TValue>(int index, TValue defaultValue)

Gets the converted value at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array.

Returns: The value located at the specified index converted into type TValue, or defaultValue if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(Index index, TValue defaultValue)

Gets the converted value at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array.

Returns: the value located at the specified index converted into type TValue, or defaultValue if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(string key, ICrystalJsonTypeResolver resolver = null, string message = null)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field
resolver — Optional custom type resolver
message — Optional error message if the field is null or missing

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

TValue Get<TValue>(ReadOnlySpan<char> key, ICrystalJsonTypeResolver resolver = null, string message = null)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field
resolver — Optional custom type resolver
message — Optional error message if the field is null or missing

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

TValue Get<TValue>(ReadOnlyMemory<char> key, ICrystalJsonTypeResolver resolver = null, string message = null)

Gets the value of the required field with the specified name, converted into type TValue

key — Name of the field
resolver — Optional custom type resolver
message — Optional error message if the field is null or missing

Returns: Value converted into an instance of type TValue, or an exception if the value is null or missing

This method can never return null, which means that there is no point in using a nullable value type for TValue.

TValue Get<TValue>(string key, TValue defaultValue, ICrystalJsonTypeResolver resolver)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing
resolver — Optional custom type resolver

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

TValue Get<TValue>(ReadOnlySpan<char> key, TValue defaultValue, ICrystalJsonTypeResolver resolver)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing
resolver — Optional custom type resolver

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

TValue Get<TValue>(ReadOnlyMemory<char> key, TValue defaultValue, ICrystalJsonTypeResolver resolver)

Gets the value of the optional field with the specified name, converted into type TValue

key — Name of the field
defaultValue — Value returned if the value is null or missing
resolver — Optional custom type resolver

Returns: Value converted into an instance of type TValue, or defaultValue if the value is null or missing

TValue Get<TValue>(int index, ICrystalJsonTypeResolver resolver = null, string message = null)

Gets the converted value of the required item at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: The value located at the specified index converted into type TValue, or an exception if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(Index index, ICrystalJsonTypeResolver resolver = null, string message = null)

Gets the converted value of the required item at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: The value located at the specified index converted into type TValue, or an exception if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(int index, TValue defaultValue, ICrystalJsonTypeResolver resolver)

Gets the converted value at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array.
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: the value located at the specified index converted into type TValue, or defaultValue if the index is outside the bounds of the array, OR the value is null or missing.

TValue Get<TValue>(Index index, TValue defaultValue, ICrystalJsonTypeResolver resolver)

Gets the converted value at the specified index, if it is contained inside the array's bound.

index — Index of the value to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array.
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: the value located at the specified index converted into type TValue, or defaultValue if the index is outside the bounds of the array, OR the value is null or missing.

GetArray

JsonArray GetArray(string key)

Gets the required JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonArray GetArray(ReadOnlySpan<char> key)

Gets the required JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonArray GetArray(ReadOnlyMemory<char> key)

Gets the required JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonArray GetArray(int index)

Gets the required JSON Array that corresponds to the field with the specified name.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonArray GetArray(Index index)

Gets the required JSON Array that corresponds to the field with the specified name.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

GetArrayOrDefault

JsonArray GetArrayOrDefault(string key)

Gets the optional JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, null if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrDefault(ReadOnlySpan<char> key)

Gets the optional JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, null if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrDefault(ReadOnlyMemory<char> key)

Gets the optional JSON Array that corresponds to the field with the specified name.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, null if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrDefault(int index)

Gets the optional JSON Array that corresponds to the field with the specified name.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, null if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrDefault(Index index)

Gets the optional JSON Array that corresponds to the field with the specified name.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, null if it is null or missing, or an exception if it is not a JSON Array.

GetArrayOrEmpty

JsonArray GetArrayOrEmpty(string key)

Gets the optional JSON Array that corresponds to the field with the specified name, or and empty (read-only) array if it is null or missing.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, the Empty if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrEmpty(ReadOnlySpan<char> key)

Gets the optional JSON Array that corresponds to the field with the specified name, or and empty (read-only) array if it is null or missing.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, the Empty if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrEmpty(ReadOnlyMemory<char> key)

Gets the optional JSON Array that corresponds to the field with the specified name, or and empty (read-only) array if it is null or missing.

key — Name of the field that is expected to be an array.

Returns: the value of the field key as a JsonArray, the Empty if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrEmpty(int index)

Gets the optional JSON Array that corresponds to the field with the specified name, or and empty (read-only) array if it is null or missing.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, the Empty if it is null or missing, or an exception if it is not a JSON Array.

JsonArray GetArrayOrEmpty(Index index)

Gets the optional JSON Array that corresponds to the field with the specified name, or and empty (read-only) array if it is null or missing.

index — Index of the value to retrieve

Returns: the value of the field index as a JsonArray, the Empty if it is null or missing, or an exception if it is not a JSON Array.

GetHashCode

int GetHashCode()

Returns a hash code that can be used to quickly identify a JSON value.

The hash code is guaranteed to remain unchanged during the lifetime of the object.

Caution: there is NO guarantee that two equivalent Objects or Arrays will have the same hash code! This means that it is NOT safe to use a JSON object or array has the key of a Dictionary or other collection that uses hash codes to quickly compare two instances.

GetObject

JsonObject GetObject(string key)

Gets the required JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonObject GetObject(ReadOnlySpan<char> key)

Gets the required JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonObject GetObject(ReadOnlyMemory<char> key)

Gets the required JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonObject GetObject(int index)

Gets the required JSON Object that corresponds to the field with the specified name.

index — Name of the field that is expected to be an object.

Returns: Value of the field index as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

JsonObject GetObject(Index index)

Gets the required JSON Object that corresponds to the field with the specified name.

index — Name of the field that is expected to be an object.

Returns: Value of the field index as a JsonArray, or an exception if it is null, missing, or not a JSON Array.

GetObjectOrDefault

JsonObject GetObjectOrDefault(string key, JsonObject defaultValue = null)

Gets the optional JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.
defaultValue — Value that is returned if the value is null or missing

Returns: Value of the field key as a JsonObject, defaultValue if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrDefault(ReadOnlySpan<char> key, JsonObject defaultValue = null)

Gets the optional JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.
defaultValue — Value that is returned if the value is null or missing

Returns: Value of the field key as a JsonObject, defaultValue if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrDefault(ReadOnlyMemory<char> key, JsonObject defaultValue = null)

Gets the optional JSON Object that corresponds to the field with the specified name.

key — Name of the field that is expected to be an object.
defaultValue — Value that is returned if the value is null or missing

Returns: Value of the field key as a JsonObject, defaultValue if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrDefault(int index, JsonObject defaultValue)

Gets the optional JSON Object that corresponds to the field with the specified name.

index — Name of the field that is expected to be an object.
defaultValue — Value that is returned if the value is null or missing

Returns: Value of the field index as a JsonObject, defaultValue if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrDefault(Index index, JsonObject defaultValue = null)

Gets the optional JSON Object that corresponds to the field with the specified name.

index — Name of the field that is expected to be an object.
defaultValue — Value that is returned if the value is null or missing

Returns: Value of the field index as a JsonObject, defaultValue if it is null or missing, or an exception if it is not a JSON Object.

GetObjectOrEmpty

JsonObject GetObjectOrEmpty(string key)

Gets the optional JSON Object that corresponds to the field with the specified name, or an empty (read-only) object if it was null or missing.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonObject, the Empty if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrEmpty(ReadOnlySpan<char> key)

Gets the optional JSON Object that corresponds to the field with the specified name, or an empty (read-only) object if it was null or missing.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonObject, the Empty if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrEmpty(ReadOnlyMemory<char> key)

Gets the optional JSON Object that corresponds to the field with the specified name, or an empty (read-only) object if it was null or missing.

key — Name of the field that is expected to be an object.

Returns: Value of the field key as a JsonObject, the Empty if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrEmpty(int index)

Gets the optional JSON Object that corresponds to the field with the specified name, or an empty (read-only) object if it was null or missing.

index — Name of the field that is expected to be an object.

Returns: Value of the field index as a JsonObject, the Empty if it is null or missing, or an exception if it is not a JSON Object.

JsonObject GetObjectOrEmpty(Index index)

Gets the optional JSON Object that corresponds to the field with the specified name, or an empty (read-only) object if it was null or missing.

index — Name of the field that is expected to be an object.

Returns: Value of the field index as a JsonObject, the Empty if it is null or missing, or an exception if it is not a JSON Object.

GetPath

TValue GetPath<TValue>(string path)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, converted into an instance of type TValue, or and exception if there was no match, or the matched value is null.

TValue GetPath<TValue>(ReadOnlyMemory<char> path)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, converted into an instance of type TValue, or and exception if there was no match, or the matched value is null.

TValue GetPath<TValue>(JsonPath path)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, converted into an instance of type TValue, or and exception if there was no match, or the matched value is null.

TValue GetPath<TValue>(string path, TValue defaultValue)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — The default value to return when the no match is found for the specified path, or it is null or missing.

Returns: the value found at this location, converted into an instance of type TValue, or defaultValue if no match was found or the value is null or missing.

TValue GetPath<TValue>(ReadOnlyMemory<char> path, TValue defaultValue)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — The default value to return when the no match is found for the specified path, or it is null or missing.

Returns: the value found at this location, converted into an instance of type TValue, or defaultValue if no match was found or the value is null or missing.

TValue GetPath<TValue>(JsonPath path, TValue defaultValue)

Gets the converted value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — The default value to return when the no match is found for the specified path, or it is null or missing.

Returns: the value found at this location, converted into an instance of type TValue, or defaultValue if no match was found or the value is null or missing.

GetPathArray

JsonArray GetPathArray(string path)

Returns the JSON Array at the specified path within this instance

JsonArray GetPathArray(ReadOnlyMemory<char> path)

Returns the JSON Array at the specified path within this instance

JsonArray GetPathArray(JsonPath path)

Returns the JSON Array at the specified path within this instance

GetPathArrayOrDefault

JsonArray GetPathArrayOrDefault(string path, JsonArray defaultValue = null)

Returns the JSON AArray at the specified path within this instance

Returns: The matching array, or null if it was not found

JsonArray GetPathArrayOrDefault(ReadOnlyMemory<char> path, JsonArray defaultValue = null)

Returns the JSON AArray at the specified path within this instance

Returns: The matching array, or null if it was not found

JsonArray GetPathArrayOrDefault(JsonPath path, JsonArray defaultValue = null)

Returns the JSON AArray at the specified path within this instance

Returns: The matching array, or null if it was not found

GetPathArrayOrEmpty

JsonArray GetPathArrayOrEmpty(string path)

Returns the JSON Array at the specified path within this instance

Returns: The matching object, or Empty if it was not found

JsonArray GetPathArrayOrEmpty(ReadOnlyMemory<char> path)

Returns the JSON Array at the specified path within this instance

Returns: The matching object, or Empty if it was not found

JsonArray GetPathArrayOrEmpty(JsonPath path)

Returns the JSON Array at the specified path within this instance

Returns: The matching object, or Empty if it was not found

GetPathObject

JsonObject GetPathObject(string path)

Returns the JSON Object at the specified path within this instance

JsonObject GetPathObject(ReadOnlyMemory<char> path)

Returns the JSON Object at the specified path within this instance

JsonObject GetPathObject(JsonPath path)

Returns the JSON Object at the specified path within this instance

GetPathObjectOrDefault

JsonObject GetPathObjectOrDefault(string path, JsonObject defaultValue = null)

Returns the JSON Object at the specified path within this instance

Returns: The matching object, or null if it was not found

JsonObject GetPathObjectOrDefault(ReadOnlyMemory<char> path, JsonObject defaultValue = null)

Returns the JSON Object at the specified path within this instance

Returns: The matching object, or null if it was not found

JsonObject GetPathObjectOrDefault(JsonPath path, JsonObject defaultValue = null)

Returns the JSON Object at the specified path within this instance

Returns: The matching object, or null if it was not found

GetPathObjectOrEmpty

JsonObject GetPathObjectOrEmpty(string path)

Returns the object at the specified path within this instance

Returns: The matching object, or Empty if it was not found

JsonObject GetPathObjectOrEmpty(ReadOnlyMemory<char> path)

Returns the object at the specified path within this instance

Returns: The matching object, or Empty if it was not found

JsonObject GetPathObjectOrEmpty(JsonPath path)

Returns the object at the specified path within this instance

Returns: The matching object, or Empty if it was not found

GetPathValue

JsonValue GetPathValue(string path)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, or Missing if no match was found

JsonValue GetPathValue(ReadOnlyMemory<char> path)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, or Missing if no match was found

JsonValue GetPathValue(JsonPath path)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"

Returns: the value found at this location, or Missing if no match was found

GetPathValueOrDefault

JsonValue GetPathValueOrDefault(string path, JsonValue defaultValue = null)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — Value that is returned if the path was not found, or the value is null or missing.

Returns: the value found at this location, or defaultValue if no match was found

JsonValue GetPathValueOrDefault(ReadOnlyMemory<char> path, JsonValue defaultValue = null)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — Value that is returned if the path was not found, or the value is null or missing.

Returns: the value found at this location, or defaultValue if no match was found

JsonValue GetPathValueOrDefault(JsonPath path, JsonValue defaultValue = null)

Gets the value at the specified path

path — Path to the value. ex: "foo", "foo.bar" or "foo[2].baz"
defaultValue — Value that is returned if the path was not found, or the value is null or missing.

Returns: the value found at this location, or defaultValue if no match was found

GetValue

JsonValue GetValue(string key)

Returns the value of the required field with the specified name.

key — Name of the field to retrieve

Returns: The value of the specified field, or an exception if it is null or missing.

JsonValue GetValue(ReadOnlySpan<char> key)

Returns the value of the required field with the specified name.

key — Name of the field to retrieve

Returns: The value of the specified field, or an exception if it is null or missing.

JsonValue GetValue(ReadOnlyMemory<char> key)

Returns the value of the required field with the specified name.

key — Name of the field to retrieve

Returns: The value of the specified field, or an exception if it is null or missing.

JsonValue GetValue(int index)

Returns the value at the required item at the specified index.

index — Index of the item to retrieve

Returns: The value located at the specified index, or an exception if the index is outside the bounds of the array, or if the item is null or missing.

JsonValue GetValue(Index index)

Returns the value at the required item at the specified index.

index — Index of the item to retrieve

Returns: The value located at the specified index, or an exception if the index is outside the bounds of the array, or if the item is null or missing.

JsonValue GetValue(ReadOnlySpan<char> key, out string actualKey)

Returns the value of the required field with the specified name.

key — Name of the field to retrieve
actualKey — If the field is present, receives the previously allocated key; otherwise, null.

Returns: The value of the specified field, or an exception if it is null or missing.

JsonValue GetValue(ReadOnlyMemory<char> key, out string actualKey)

Returns the value of the required field with the specified name.

key — Name of the field to retrieve
actualKey — If the field is present, receives the previously allocated key; otherwise, null.

Returns: The value of the specified field, or an exception if it is null or missing.

GetValueOrDefault

JsonValue GetValueOrDefault(string key, JsonValue defaultValue = null)

Returns the value of the optional field with the specified name.

key — Name of the field to retrieve
defaultValue — The value that is returned if field was null or missing.

Returns: The value of the specified field, or defaultValue if it is null or missing.

If the value is not a JsonObject or null or missing, an exception will be thrown.

JsonValue GetValueOrDefault(ReadOnlySpan<char> key, JsonValue defaultValue = null)

Returns the value of the optional field with the specified name.

key — Name of the field to retrieve
defaultValue — The value that is returned if field was null or missing.

Returns: The value of the specified field, or defaultValue if it is null or missing.

If the value is not a JsonObject or null or missing, an exception will be thrown.

JsonValue GetValueOrDefault(ReadOnlyMemory<char> key, JsonValue defaultValue = null)

Returns the value of the optional field with the specified name.

key — Name of the field to retrieve
defaultValue — The value that is returned if field was null or missing.

Returns: The value of the specified field, or defaultValue if it is null or missing.

If the value is not a JsonObject or null or missing, an exception will be thrown.

JsonValue GetValueOrDefault(int index, JsonValue defaultValue = null)

Returns the value at the optional item at the specified index, if it is contained inside the array's bound.

index — Index of the item to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array, or if the item at this location is null or missing.

Returns: The value located at the specified index, or defaultValue if the index is outside the bounds of the array, of the item is null or missing.

If the index is outside the bounds, and is not specified, then is returned.

JsonValue GetValueOrDefault(Index index, JsonValue defaultValue = null)

Returns the value at the optional item at the specified index, if it is contained inside the array's bound.

index — Index of the item to retrieve
defaultValue — The value that is returned if the index is outside the bounds of the array, or if the item at this location is null or missing.

Returns: The value located at the specified index, or defaultValue if the index is outside the bounds of the array, of the item is null or missing.

If the value is not a JsonArray or null or missing, an exception will be thrown.

JsonValue GetValueOrDefault(ReadOnlySpan<char> key, JsonValue defaultValue, out string actualKey)

Returns the value of the optional field with the specified name.

key — Name of the field to retrieve
defaultValue — The value that is returned if field was null or missing.
actualKey — If the field is present, receives the previously allocated key; otherwise, null.

Returns: The value of the specified field, or defaultValue if it is null or missing.

If the value is not a JsonObject or null or missing, an exception will be thrown.

JsonValue GetValueOrDefault(ReadOnlyMemory<char> key, JsonValue defaultValue, out string actualKey)

Returns the value of the optional field with the specified name.

key — Name of the field to retrieve
defaultValue — The value that is returned if field was null or missing.
actualKey — If the field is present, receives the previously allocated key; otherwise, null.

Returns: The value of the specified field, or defaultValue if it is null or missing.

If the value is not a JsonObject or null or missing, an exception will be thrown.

JsonSerialize

void JsonSerialize(CrystalJsonWriter writer)

Serializes this instance as JSON

writer — Writer that will output the content of this instance

Parse

static JsonValue Parse(string jsonText, IFormatProvider provider)

static JsonValue Parse(ReadOnlySpan<char> jsonText, IFormatProvider provider)

Parses a JSON text literal, and returns the corresponding JSON value.

jsonText — JSON text document to parse
provider — This parameter is ignored.

Returns: Corresponding JSON value. If jsonText is empty, will return Missing

It is better to call overloads of this method that accept a argument.

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

Parses a JSON text literal, and returns the corresponding JSON value

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

Returns: Corresponding JSON value. If jsonText is empty, will return Missing

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use Parse instead.

If the result is always expected to be an Array or an Object, please call either Parse or Parse.

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

Parses a JSON text literal, and returns the corresponding JSON value

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

Returns: Corresponding JSON value. If jsonText is empty, will return Missing

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use Parse instead.

If the result is always expected to be an Array or an Object, please call either Parse or Parse.

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

Parses a buffer containing a document

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

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

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use Parse instead.

If the result is always expected to be an Array or an Object, please call either Parse or Parse.

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

Parses a buffer containing a document

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

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

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use Parse instead.

If the result is always expected to be an Array or an Object, please call either Parse or Parse.

ParseArray

static JsonArray ParseArray(string jsonText, CrystalJsonSettings settings = null)

Parses a JSON text literal that is expected to contain an Array

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

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

The JSON Array is mutable and can be freely modified. If you require an immutable array, please use ParseArray instead.

If the JSON document can sometimes be empty of the 'null' token, you should call Parse and then use AsArrayOrDefault on the result.

static JsonArray ParseArray(ReadOnlySpan<char> jsonText, CrystalJsonSettings settings = null)

Parses a JSON text literal that is expected to contain an Array

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

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

The JSON Array is mutable and can be freely modified. If you require an immutable array, please use ParseArray instead.

If the JSON document can sometimes be empty of the 'null' token, you should call Parse and then use AsArrayOrDefault on the result.

static JsonArray ParseArray(ReadOnlySpan<byte> jsonBytes, CrystalJsonSettings settings = null)

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

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

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

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use ParseArray instead.

static JsonArray ParseArray(Slice jsonBytes, CrystalJsonSettings settings = null)

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

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

Returns: Corresponding JSON Array.

The value may be mutable and can be modified. If you require an immutable thread-safe array, please use ParseArray instead.

ParseArrayReadOnly

static JsonArray ParseArrayReadOnly(string jsonText, CrystalJsonSettings settings = null)

static JsonArray ParseArrayReadOnly(ReadOnlySpan<byte> jsonBytes, CrystalJsonSettings settings = null)

static JsonArray ParseArrayReadOnly(Slice jsonBytes, CrystalJsonSettings settings = null)

ParseObject

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

Parses a JSON text literal that is expected to contain an Object

jsonText — JSON text document 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.

If the JSON document can sometimes be empty of the 'null' token, you should call and then use on the result.

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

Parses a JSON text literal that is expected to contain an Object

jsonText — JSON text document 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.

If the JSON document can sometimes be empty of the 'null' token, you should call and then use on the result.

static JsonObject ParseObject(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 JSON Object. If jsonBytes is empty or not an Array, an exception will be thrown

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use ParseObject instead.

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

Parses a buffer containing a UTF-8 JSON document, and returns the corresponding expected JSON Object

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

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

The value may be mutable (for objects and arrays) and can be modified. If you require an immutable thread-safe value, please use ParseObject instead.

ParseObjectReadOnly

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

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

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

ParseReadOnly

static JsonValue ParseReadOnly(string jsonText, CrystalJsonSettings settings = null)

static JsonValue ParseReadOnly(ReadOnlySpan<char> jsonText, CrystalJsonSettings settings = null)

static JsonValue ParseReadOnly(ReadOnlySpan<byte> jsonBytes, CrystalJsonSettings settings = null)

static JsonValue ParseReadOnly(Slice jsonBytes, CrystalJsonSettings settings = null)

StrictEquals

bool StrictEquals(JsonValue other)

Tests if these two JSON values are considered equal, using the strict JSON comparison semantics

For two values to be considered "equal", they must be of the same type (string, number, array, ...) AND have the same result when serialized using a canonical representation.

Arrays are equals if they have the same length and all their elements are also strictly equal.

Objects are equal if they have the same keys, irrespective of their order, and each value is strictly equal.

A Missing field is not considered equal to an explicit Null field, and vice versa

ToBoolean

bool ToBoolean(bool defaultValue = false)

Returns the equivalent Boolean, if there exists a valid conversion

ToBooleanOrDefault

bool? ToBooleanOrDefault(bool? defaultValue = null)

Returns the equivalent Boolean, if there exists a valid conversion

ToByte

byte ToByte(byte defaultValue = 0)

Returns the equivalent Byte, if there exists a valid conversion

ToByteOrDefault

byte? ToByteOrDefault(byte? defaultValue = null)

Returns the equivalent Byte, if there exists a valid conversion

ToChar

char ToChar(char defaultValue = '�')

Returns the equivalent Char, if there exists a valid conversion

ToCharOrDefault

char? ToCharOrDefault(char? defaultValue = null)

Returns the equivalent Char, if there exists a valid conversion

ToDateOnly

DateOnly ToDateOnly(DateOnly defaultValue = null)

Returns the equivalent DateOnly, if there exists a valid conversion

ToDateOnlyOrDefault

DateOnly? ToDateOnlyOrDefault(DateOnly? defaultValue = null)

Returns the equivalent DateOnly, if there exists a valid conversion

ToDateTime

DateTime ToDateTime(DateTime defaultValue = null)

Returns the equivalent DateTime, if there exists a valid conversion

ToDateTimeOffset

DateTimeOffset ToDateTimeOffset(DateTimeOffset defaultValue = null)

Returns the equivalent DateTimeOffset, if there exists a valid conversion

ToDateTimeOffsetOrDefault

DateTimeOffset? ToDateTimeOffsetOrDefault(DateTimeOffset? defaultValue = null)

Returns the equivalent DateTimeOffset, if there exists a valid conversion

ToDateTimeOrDefault

DateTime? ToDateTimeOrDefault(DateTime? defaultValue = null)

Returns the equivalent DateTime, if there exists a valid conversion

ToDecimal

decimal ToDecimal(decimal defaultValue = 0)

Returns the equivalent Decimal, if there exists a valid conversion

ToDecimalOrDefault

decimal? ToDecimalOrDefault(decimal? defaultValue = null)

Returns the equivalent Decimal, if there exists a valid conversion

ToDouble

double ToDouble(double defaultValue = 0)

Returns the equivalent Double, if there exists a valid conversion

ToDoubleOrDefault

double? ToDoubleOrDefault(double? defaultValue = null)

Returns the equivalent Double, if there exists a valid conversion

ToDuration

Duration ToDuration(Duration defaultValue = null)

Returns the equivalent Duration, if there exists a valid conversion

ToDurationOrDefault

Duration? ToDurationOrDefault(Duration? defaultValue = null)

Returns the equivalent Duration, if there exists a valid conversion

ToEnum

TEnum ToEnum<TEnum>(TEnum defaultValue = null)

Returns the equivalent Enum, if there exists a valid conversion

ToEnumOrDefault

TEnum? ToEnumOrDefault<TEnum>(TEnum? defaultValue = null)

Returns the equivalent Enum, if there exists a valid conversion

ToGuid

Guid ToGuid(Guid defaultValue = null)

Returns the equivalent Guid, if there exists a valid conversion

ToGuidOrDefault

Guid? ToGuidOrDefault(Guid? defaultValue = null)

Returns the equivalent Guid, if there exists a valid conversion

ToHalf

Half ToHalf(Half defaultValue = null)

Returns the equivalent Half, if there exists a valid conversion

ToHalfOrDefault

Half? ToHalfOrDefault(Half? defaultValue = null)

Returns the equivalent Half, if there exists a valid conversion

ToInstant

Instant ToInstant(Instant defaultValue = null)

Returns the equivalent Instant, if there exists a valid conversion

ToInstantOrDefault

Instant? ToInstantOrDefault(Instant? defaultValue = null)

Returns the equivalent Instant, if there exists a valid conversion

ToInt128

Int128 ToInt128(Int128 defaultValue = null)

Returns the equivalent Int128, if there exists a valid conversion

ToInt128OrDefault

Int128? ToInt128OrDefault(Int128? defaultValue = null)

Returns the equivalent Int128, if there exists a valid conversion

ToInt16

short ToInt16(short defaultValue = 0)

Returns the equivalent Int16, if there exists a valid conversion

ToInt16OrDefault

short? ToInt16OrDefault(short? defaultValue = null)

Returns the equivalent Int16, if there exists a valid conversion

ToInt32

int ToInt32(int defaultValue = 0)

Returns the equivalent Int32, if there exists a valid conversion

ToInt32OrDefault

int? ToInt32OrDefault(int? defaultValue = null)

Returns the equivalent Int32, if there exists a valid conversion

ToInt64

long ToInt64(long defaultValue = 0)

Returns the equivalent Int64, if there exists a valid conversion

ToInt64OrDefault

long? ToInt64OrDefault(long? defaultValue = null)

Returns the equivalent Int64, if there exists a valid conversion

ToJson

string ToJson(CrystalJsonSettings settings = null)

Serializes this JSON value into a JSON string literal

ToJsonText

string ToJsonText(CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Serializes this JSON value into a JSON string literal

settings — Settings used to change the serialized JSON output (optional)
resolver — Optional custom resolver.

Returns: JSON text literal that can be written to disk, returned as the body of an HTTP request, or

var jsonText = new JsonObject() { ["hello"] = "world" }.ToJsonText(); // == "{ "hello": "world" }"

ToMutable

JsonValue ToMutable()

Convert this JSON value so that it, or any of its children that were previously read-only, can be mutated.

Returns: The same instance if it is already fully mutable, OR a copy where any read-only Object or Array has been converted to allow mutations.

Will return the same instance if it is already mutable, or a new deep copy with all children marked as mutable.

This attempts to only copy what is necessary, and will not copy objects or arrays that are already mutable, or all other "value types" (string, boolean, number, ...) that are always immutable.

ToObject

object ToObject()

Converts this into a CLR object (with a type that matches the value)

Prefer casting to a specific type, using As() or any equivalent method.

ToReadOnly

JsonValue ToReadOnly()

Returns a read-only copy of this value, unless it is already read-only.

Returns: The same instance if it is already read-only, or a new read-only deep copy, if it was mutable.

The value returned is guaranteed to be immutable, and is safe to cache, share, or use as a singleton.

Only JSON Objects and Arrays are impacted. All other "value types" (string, boolean, number, ...) are always immutable, and will not be copied.

ToSByte

sbyte ToSByte(sbyte defaultValue = 0)

Returns the equivalent SByte, if there exists a valid conversion

ToSByteOrDefault

sbyte? ToSByteOrDefault(sbyte? defaultValue = null)

Returns the equivalent SByte, if there exists a valid conversion

ToSingle

float ToSingle(float defaultValue = 0)

Returns the equivalent Single, if there exists a valid conversion

ToSingleOrDefault

float? ToSingleOrDefault(float? defaultValue = null)

Returns the equivalent Single, if there exists a valid conversion

ToString

string ToString()

Converts this JSON value into a printable string

Please note that, due to convention in .NET, this will return the empty string for null values, since ToString must not return a null reference! Please call ToStringOrDefault if you need null references for null or missing JSON values.

See ToString if you need to specify a different format than the default

string ToString(string format, IFormatProvider provider = null)

Converts this JSON value into a printable string, using the specified format and provider

format — Desired format, or "D" (default) if omitted
provider — This parameter is ignored. JSON values are always formatted using InvariantCulture.

Supported values for are:

D Default, returns the value in the default format (no quotes for strings, ...)
N Normal, equivalent to calling ToJsonText with Json
C Compact, equivalent to calling ToJsonText with JsonCompact
P Pretty, equivalent to calling ToJsonText with JsonIndented
Q Quick, equivalent to calling GetCompactRepresentation, that will return a simplified/partial version, suitable for logs/traces.
J JavaScript, equivalent to calling ToJsonText with JavaScript.
B returns a doubly-encoded JSON version of this value, that can be passed through inside another JSON payload, or copy-pasted as a valid C# string literal.

ToStringOrDefault

string ToStringOrDefault(string defaultValue = null)

Returns the equivalent String, if there exists a valid conversion

ToTimeOnly

TimeOnly ToTimeOnly(TimeOnly defaultValue = null)

Returns the equivalent TimeOnly, if there exists a valid conversion

ToTimeOnlyOrDefault

TimeOnly? ToTimeOnlyOrDefault(TimeOnly? defaultValue = null)

Returns the equivalent TimeOnly, if there exists a valid conversion

ToTimeSpan

TimeSpan ToTimeSpan(TimeSpan defaultValue = null)

Returns the equivalent TimeSpan, if there exists a valid conversion

ToTimeSpanOrDefault

TimeSpan? ToTimeSpanOrDefault(TimeSpan? defaultValue = null)

Returns the equivalent TimeSpan, if there exists a valid conversion

ToUInt128

UInt128 ToUInt128(UInt128 defaultValue = null)

Returns the equivalent UInt128, if there exists a valid conversion

ToUInt128OrDefault

UInt128? ToUInt128OrDefault(UInt128? defaultValue = null)

Returns the equivalent UInt128, if there exists a valid conversion

ToUInt16

ushort ToUInt16(ushort defaultValue = 0)

Returns the equivalent UInt16, if there exists a valid conversion

ToUInt16OrDefault

ushort? ToUInt16OrDefault(ushort? defaultValue = null)

Returns the equivalent UInt16, if there exists a valid conversion

ToUInt32

uint ToUInt32(uint defaultValue = 0)

Returns the equivalent UInt32, if there exists a valid conversion

ToUInt32OrDefault

uint? ToUInt32OrDefault(uint? defaultValue = null)

Returns the equivalent UInt32, if there exists a valid conversion

ToUInt64

ulong ToUInt64(ulong defaultValue = 0)

Returns the equivalent UInt64, if there exists a valid conversion

ToUInt64OrDefault

ulong? ToUInt64OrDefault(ulong? defaultValue = null)

Returns the equivalent UInt64, if there exists a valid conversion

ToUuid128

Uuid128 ToUuid128(Uuid128 defaultValue = null)

Returns the equivalent Uuid128, if there exists a valid conversion

ToUuid128OrDefault

Uuid128? ToUuid128OrDefault(Uuid128? defaultValue = null)

Returns the equivalent Uuid128, if there exists a valid conversion

ToUuid48

Uuid48 ToUuid48(Uuid48 defaultValue = null)

Returns the equivalent Uuid48, if there exists a valid conversion

ToUuid48OrDefault

Uuid48? ToUuid48OrDefault(Uuid48? defaultValue = null)

Returns the equivalent Uuid48, if there exists a valid conversion

ToUuid64

Uuid64 ToUuid64(Uuid64 defaultValue = null)

Returns the equivalent Uuid64, if there exists a valid conversion

ToUuid64OrDefault

Uuid64? ToUuid64OrDefault(Uuid64? defaultValue = null)

Returns the equivalent Uuid64, if there exists a valid conversion

ToUuid80

Uuid80 ToUuid80(Uuid80 defaultValue = null)

Returns the equivalent Uuid80, if there exists a valid conversion

ToUuid80OrDefault

Uuid80? ToUuid80OrDefault(Uuid80? defaultValue = null)

Returns the equivalent Uuid80, if there exists a valid conversion

ToUuid96

Uuid96 ToUuid96(Uuid96 defaultValue = null)

Returns the equivalent Uuid96, if there exists a valid conversion

ToUuid96OrDefault

Uuid96? ToUuid96OrDefault(Uuid96? defaultValue = null)

Returns the equivalent Uuid96, if there exists a valid conversion

TryFormat

bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = null, IFormatProvider provider = null)

bool TryFormat(Span<byte> destination, out int bytesWritten, ReadOnlySpan<char> format = null, IFormatProvider provider = null)

TryFormatCompact

static bool TryFormatCompact(JsonValue value, Span<char> destination, out int charsWritten)

TryFormatNormal

static bool TryFormatNormal(JsonValue value, Span<char> destination, out int charsWritten)