SnowBank SDK SnowBank SDK
EN

JsonNull

Namespace: SnowBank.Data.Json · class

Implements: JsonValue, 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>, IEquatable<JsonNull>

JSON null

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

IsError

bool IsError { get; }

Tests if this is the Error singleton

IsMissing

bool IsMissing { get; }

Tests if this is the Missing singleton

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; }

JsonValue Item { get; set; }

JsonValue Item { get; set; }

JsonValue Item { get; set; }

JsonValue Item { get; set; }

Type

JsonType Type { get; }

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

Methods

Bind

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.

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.

CompareTo

int CompareTo(JsonValue value)

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

Equals

bool Equals(object obj)

bool Equals(JsonValue value)

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.

bool Equals(JsonNull value)

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.

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(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(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(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(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.

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.

JsonSerialize

void JsonSerialize(CrystalJsonWriter writer)

Serializes this instance as JSON

  • writer — Writer that will output the content of this instance

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

bool StrictEquals(JsonNull other)

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

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" }"

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.

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

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)

ValueEquals

bool ValueEquals<TValue>(TValue value, IEqualityComparer<TValue> comparer = null)

Tests if the current instance is equal to the specified value, using the strict JSON comparison semantics

  • value — Value to test with the current instance
  • comparer — Custom equality comparer if specified; otherwise, uses the default comparer for this type

Returns: true if both arguments are considered equal; otherwise, false

This method tries to perform an optimized comparison, and should perform less memory allocations than calling

WriteTo

void WriteTo(ref SliceWriter writer)

Serializes the current instance to the specified output buffer

Fields

Error

static readonly JsonValue Error

Result of an invalid operation

This singleton is used to represent a null or missing value, which is due to some sort of error condition

For example, attempting to index an object (ex: obj[123]) or access the field of an array (ex: arr["foo"]) are 'soft errors'

Missing

static readonly JsonValue Missing

Missing value

This singleton is returned when

Null

static readonly JsonValue Null

Explicit null value

This singleton is used to represent values that are present in the JSON document, usually represents by the null token.