ObservableJsonValue

Namespace: SnowBank.Data.Json · class

Implements: IJsonProxyNode, IJsonSerializable, IJsonPackable, IEnumerable<ObservableJsonValue>, IEnumerable, IEquatable<ObservableJsonValue>, IComparable<ObservableJsonValue>, IEquatable<JsonValue>, IComparable<JsonValue>, IFormattable, ISpanFormattable, IUtf8SpanFormattable

Observable JSON Object that will capture all reads

Constructors

ObservableJsonValue

ObservableJsonValue(IObservableJsonContext ctx, IJsonProxyNode parent, JsonPathSegment segment, JsonValue json)

Constructs a ObservableJsonValue

• ctx — Tracking context (optional)
• parent — Parent of this value (or null if root)
• segment — Path from the parent to this node (or Empty if root)
• json — Value of this node

Properties

Count

int Count { get; }

Number of items in this array

Item

ObservableJsonValue Item { get; }

ObservableJsonValue Item { get; }

ObservableJsonValue Item { get; }

ObservableJsonValue Item { get; }

ObservableJsonValue Item { get; }

Methods

As

TValue As<TValue>(TValue defaultValue = null)

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

• defaultValue — Value returned if the wrapped JSON value is null-or-missing

Returns: Converted value

Examples: ({ "hello": "world" })["hello"].As() => "world" ({ "hello": null })["hello"].As() => null ({ "hello": null })["hello"].As("there") => "there" ({ /* ... / })["hello"].As() => null ({ / ... */ })["hello"].As("there") => "there"

AsArray

JsonArray AsArray()

Expose the underlying JsonArray of this node

This will we recorded as a full use of the value

AsArrayOf

JsonArray<TValue> AsArrayOf<TValue>()

Expose the underlying JsonArray of this node

This will we recorded as a full use of the value

AsArrayOrDefault

JsonArray AsArrayOrDefault()

Expose the underlying JsonArray of this node, or null if it is null or missing.

This will we recorded as a full use of the value

AsArrayOrDefaultOf

JsonArrayOrDefault<TValue> AsArrayOrDefaultOf<TValue>(TValue missingValue = null)

Expose the underlying JsonArray of this node

This will we recorded as a full use of the value

AsArrayOrEmpty

JsonArray AsArrayOrEmpty()

Expose the underlying JsonArray of this node

This will we recorded as a full use of the value

AsObject

JsonObject AsObject()

Expose the underlying JsonObject of this node, or an empty array if it is null or missing.

This will we recorded as a full use of the value

AsObjectOrDefault

JsonObject AsObjectOrDefault()

Expose the underlying JsonObject of this node, or null if it is null or missing.

This will we recorded as a full use of the value

AsObjectOrEmpty

JsonObject AsObjectOrEmpty()

Expose the underlying JsonObject of this node, or an empty object if it is null or missing.

This will we recorded as a full use of the value

CompareTo

int CompareTo(ObservableJsonValue other)

int CompareTo(JsonValue other)

ContainsKey

bool ContainsKey(string name)

Tests if the wrapped JSON value is an object that contains a field with the given name

• name — Name of the field

Returns: true if the current value is an object, and if the corresponding field has a non-null value; otherwise, false

Examples: ({ "hello": "world" }).ContainsKey("hello") => true ({ "hello": "world" }).ContainsKey("other") => false ([ "one", "two", "three" ]).ContainsKey("two") => false

ContainsValue

bool ContainsValue(JsonValue value)

Tests if the wrapped JSON value is either an array or an object that contains the specified value

• value — Value that is being searched.

Returns: true if the current value is an array that contains value, or an object with a field whose value is equal to value; otherwise, false;

Examples: ({ "hello": "world" }).ContainsValue("world") => true ({ "hello": "world" }).ContainsValue("there") => false ([ "one", "two", "three" ]).ContainsValue("two") => true ([ "one", "two", "three" ]).ContainsValue("four") => false

Equals

bool Equals(object obj)

bool Equals(ObservableJsonValue other)

bool Equals(JsonValue other)

Exists

bool Exists()

Tests if the wrapped JSON value is not null or missing.

Returns: false if the value is JsonNull; otherwise, false

This method will record a access.

Get

ObservableJsonValue Get(string name)

Returns a wrapper for the field with the specified name

• name — Name of the field to return

Returns: Corresponding field, or a null-or-missing placeholder.

This operation in itself will not be recorded as a use of the object

TValue Get<TValue>(string name)

Reads the value of the required field with the specified name

• name — Name of the field

Returns: Corresponding value.

This operation will be recorded as a access.

ObservableJsonValue Get(ReadOnlyMemory<char> name)

Returns a wrapper for the field with the specified name

• name — Name of the field to return

Returns: Corresponding field, or a null-or-missing placeholder.

This operation in itself will not be recorded as a use of the object

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

Reads the value of the required field with the specified name

• name — Name of the field

Returns: Corresponding value.

This operation will be recorded as a access.

ObservableJsonValue Get(int index)

Returns a wrapper for the field with the specified name

• index — Index of the item to return

Returns: Corresponding item, or an error placeholder.

This operation in itself will not be recorded as a use of the array

TValue Get<TValue>(int index)

Reads the value of the required item at the specified index

• index — Index of the item

Returns: Corresponding value

This operation will be recorded as a access.

ObservableJsonValue Get(Index index)

Returns a wrapper for the field with the specified name

• index — Index of the item to return

Returns: Corresponding item, or an error placeholder.

This operation in itself will not be recorded as a use of the array

TValue Get<TValue>(Index index)

Reads the value of the required item at the specified index

• index — Index of the item

Returns: Corresponding value

This operation will be recorded as a access.

ObservableJsonValue Get(JsonPath path)

Returns a wrapper for the descendant of this node at the specified location

• path — Path of the node to return

Returns: Corresponding node, or a null-or-missing placeholder.

This operation in itself will not be recorded as a use of the object

TValue Get<TValue>(JsonPath path)

Reads the value of the required node at the specified location

• path — Path to the node to read

Returns: Corresponding value.

This operation will be recorded as a access.

ObservableJsonValue Get(JsonPathSegment segment)

Returns a wrapper for the child of this node at the specified location

• segment — Path of the node to return

Returns: Corresponding node, or a null-or-missing placeholder.

This operation in itself will not be recorded as a use of the object

TValue Get<TValue>(JsonPathSegment segment)

Reads the value of the required node at the specified location

• segment — Path to the node to read

Returns: Corresponding value.

This operation will be recorded as a access.

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

Reads the value of the optional field with the specified name

• name — Name of the field
• defaultValue — Value returned if the field is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

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

Reads the value of the optional field with the specified name

• name — Name of the field
• defaultValue — Value returned if the field is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

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

Reads the value of the optional item at the specified index

• index — Index of the item
• defaultValue — Value returned if the item is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

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

Reads the value of the optional item at the specified index

• index — Index of the item
• defaultValue — Value returned if the item is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

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

Reads the value of the optional node at the specified location

• path — Path to the node to read
• defaultValue — Value returned if the node is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

TValue Get<TValue>(JsonPathSegment segment, TValue defaultValue)

Reads the value of the optional node at the specified location

• segment — Path to the node to read
• defaultValue — Value returned if the node is null or missing

Returns: Corresponding value.

This operation will be recorded as a access.

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

Reads the value of the optional field with the specified name

• name — Name of the field
• defaultValue — Value returned if the field is null or missing

Returns: Corresponding value

This operation will be recorded as a access.

GetArray

JsonArray GetArray(string name)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return

Returns: Corresponding array

This operation will be recorded as a access.

TValue[] GetArray<TValue>(string name, IJsonConverter<TValue> converter)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return
• converter — Converter used to unpack the elements of the JSON Array into a TValue instances

Returns: Corresponding array

This operation will be recorded as a access.

GetArrayOrDefault

JsonArray GetArrayOrDefault(string name)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return

Returns: Corresponding array, or null if the field is null or missing

This operation will be recorded as a access.

TValue[] GetArrayOrDefault<TValue>(string name, IJsonConverter<TValue> converter)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return
• converter — Converter used to unpack the elements of the JSON Array into a TValue instances

Returns: Corresponding array, or null if the field is null or missing

This operation will be recorded as a access.

GetArrayOrEmpty

JsonArray GetArrayOrEmpty(string name)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return

Returns: Array in the corresponding field, or an empty read-only array if null or missing

This operation will be recorded as a access.

TValue[] GetArrayOrEmpty<TValue>(string name, IJsonConverter<TValue> converter)

Returns an array with the converted elements of the array contained in field with the specified name

• name — Name of the field to return
• converter — Converter used to unpack the elements of the JSON Array into a TValue instances

Returns: Array of TValue instances, or an empty array if the field is null or missing

This operation will be recorded as a access.

GetContext

IObservableJsonContext GetContext()

Returns the tracking context that is attached to this node

GetDepth

int GetDepth()

Returns the depth from the root to this value

Returns: Number of parents of this value, or 0 if this is the top-level value

GetEnumerator

IEnumerator<ObservableJsonValue> GetEnumerator()

GetHashCode

int GetHashCode()

GetJsonUnsafe

JsonValue GetJsonUnsafe()

Expose the underlying JsonValue of this node, without recording it as a read access

This should only be used by infrastructure that need to inspect the content of the node, outside the "view" of the context

GetObject

JsonObject GetObject(string name)

Returns the underlying JsonArray of the field with the specified name

• name — Name of the field to return

Returns: Corresponding array

This operation will be recorded as a access.

GetObjectOrDefault

JsonObject GetObjectOrDefault(string name)

Returns the underlying JsonValue of the field with the specified name

• name — Name of the field to return

Returns: Corresponding field

This operation will be recorded as a access.

GetObjectOrEmpty

JsonObject GetObjectOrEmpty(string name)

Returns the underlying JsonValue of the field with the specified name

• name — Name of the field to return

Returns: Corresponding field

This operation will be recorded as a access.

GetParent

IJsonProxyNode GetParent()

Returns the parent of this node

Returns: Parent node, or null if root

GetPath

JsonPath GetPath()

Returns the path to this node, from the root

JsonPath GetPath(JsonPathSegment child)

Returns the path to a child of this value, from the root

GetValue

JsonValue GetValue(string name)

Returns the underlying JsonValue of the field with the specified name

• name — Name of the field to return

Returns: Corresponding field

This operation will be recorded as a access.

JsonValue GetValue(ReadOnlyMemory<char> name)

Returns the underlying JsonValue of the field with the specified name

• name — Name of the field to return

Returns: Corresponding field

This operation will be recorded as a access.

JsonValue GetValue(int index)

Returns the underlying JsonValue of the item at the specified location

• index — Index of the item to return

Returns: Corresponding item, or Error if the index is out of bounds, of this is not an array.

This operation will be recorded as a access.

JsonValue GetValue(Index index)

Returns the underlying JsonValue of the item at the specified location

• index — Index of the item to return

Returns: Corresponding item, or Error if the index is out of bounds, of this is not an array.

This operation will be recorded as a access.

JsonValue GetValue(JsonPath path)

Returns the underlying JsonValue of the node at the specified location

• path — Path to the node to read

Returns: Corresponding value

This operation will be recorded as a access.

JsonValue GetValue(JsonPathSegment segment)

Reads the value of the required node at the specified location

• segment — Path to the node to read

Returns: Corresponding value.

This operation will be recorded as a access.

IsArray

bool IsArray()

Tests if the wrapped JSON value is a non-null array.

Returns: true if the value is an array; otherwise, false

This method will record a access.

IsArrayOrMissing

bool IsArrayOrMissing()

Tests if the wrapped JSON value is either an array, or null-or-missing.

Returns: true if the value is an array, null or missing; otherwise, false

This method will record a access.

IsArrayUnsafe

bool IsArrayUnsafe(out JsonArray value)

Tests if the wrapped JSON value is a non-null array.

• value — Receives the underlying JSON array

Returns: true if the value is an array; otherwise, false

This method will record a Type access, but any reads performed on value will not be tracked by the attached context!

It is intended to be used by infrastructure code that will manually record any access to the value.

IsEmpty

bool IsEmpty()

Tests if the wrapped JSON is either an empty JsonArray ([ ]), an empty JsonObject ({ }), or an empty JsonString (" ").

IsNullOrMissing

bool IsNullOrMissing()

Tests if the wrapped JSON value is null or missing.

Returns: true if the value is JsonNull; otherwise, false

This method will record a access.

IsObject

bool IsObject()

Tests if the wrapped JSON value is a non-null object.

Returns: true if the value is an object; otherwise, false

This method will record a access.

IsObjectOrMissing

bool IsObjectOrMissing()

Tests if the wrapped JSON value is either an object, or null-or-missing.

Returns: true if the value is an object, null or missing; otherwise, false

This method will record a access.

IsObjectUnsafe

bool IsObjectUnsafe(out JsonObject value)

Tests if the wrapped JSON value is a non-null object.

• value — Receives the underlying JSON object

Returns: true if the value is an object; otherwise, false

This method will record a Type access, but any reads performed on value will not be tracked by the attached context!

It is intended to be used by infrastructure code that will manually record any access to the value.

IsOfType

bool IsOfType(JsonType type)

Tests if the wrapped JSON value is of the given type

• type — Expected type of the value

Returns: true if the value is of this type; otherwise, false

This method will record a access.

IsOfTypeOrNull

bool IsOfTypeOrNull(JsonType type)

Tests if the wrapped JSON value is of the given type, or is null-or-missing

• type — Expected type of the value

Returns: true if the value is of this type, null or missing; otherwise, false

This method will record a access.

IsRoot

bool IsRoot()

Tests if this is the top-level node of the document

Required

TValue Required<TValue>()

Converts the wrapped JSON value into the specified CLR type.

Returns: Converted value

Examples: ({ "hello": "world" })["hello"].Required() => "world" ({ "hello": null })["hello"].Required() => throws ({ /* ... */ })["hello"].Required() => throws

ToJson

JsonValue ToJson()

Expose the underlying JsonValue of this node

This will we recorded as a full use of the value

ToJsonValue

JsonValue ToJsonValue()

Expose the underlying JsonValue of this node

This will we recorded as a full use of the value

ToString

string ToString()

string ToString(string format, IFormatProvider provider = null)

Tracked

static ObservableJsonValue Tracked(IObservableJsonContext ctx, JsonValue value)

Returns an JSON value tracked by a context

TryFormat

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

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

TryGetCount

bool TryGetCount(out int count)

Try getting the size of this array

• count — Receives the length of the array, or 0 if this is not an array

Returns: true if this is an array; otherwise, false

TryGetValue

bool TryGetValue(string name, out ObservableJsonValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• value — Value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue(ReadOnlyMemory<char> name, out ObservableJsonValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• value — Value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(string name, out TValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• value — Value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(ReadOnlyMemory<char> name, out TValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• value — Value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue(int index, out ObservableJsonValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(int index, out TValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue(Index index, out ObservableJsonValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

This can be used to perform a different operation if the value exists or not (initialize a counter or increment its value, throw a specialized exception, ....)

bool TryGetValue<TValue>(Index index, out TValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue(JsonPathSegment segment, out ObservableJsonValue value)

Returns the value of the given child, if it is not null or missing

• segment — Name of the field in this object, or location in this array.
• value — Value that represents this child.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(JsonPathSegment segment, out TValue value)

Returns the value of the given child, if it is not null or missing

• segment — Name of the field in this object, or location in this array.
• value — Value that represents this child.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue(JsonPath path, out ObservableJsonValue value)

Returns the value of the element at the given path, if it is not null or missing

• path — Path to the element.
• value — Value that represents this element.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(JsonPath path, out TValue value)

Returns the value of the element at the given path, if it is not null or missing

• path — Path to the element.
• value — Value that represents this element, converted into TValue.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(string name, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• converter — Converter used to unpack the JSON value into a TValue instance
• value — Receives the unpacked value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(ReadOnlyMemory<char> name, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value of the given field, if it is not null or missing

• name — Name of the field in this object
• converter — Converter used to unpack the JSON value into a TValue instance
• value — Receives the unpacked value that represents this field in the current object.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(int index, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• converter — Converter used to unpack the JSON value into a TValue instance
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(Index index, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value at the given location, if it was non-null and inside the bounds of the array

• index — Index of the element in this array
• converter — Object that can deserialize instances of TValue from JSON values
• value — Value that represents this index in the current array.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(JsonPathSegment segment, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value of the given child, if it is not null or missing

• segment — Name of the field in this object, or location in this array.
• converter — Converter used to unpack the JSON value into a TValue instance
• value — Value that represents this child.

Returns: true if the element exists and has a non-null value; otherwise, false.

bool TryGetValue<TValue>(JsonPath path, IJsonDeserializer<TValue> converter, out TValue value)

Returns the value of the element at the given path, if it is not null or missing

• path — Path to the element.
• converter — Converter used to unpack the JSON value into a TValue instance
• value — Value that represents this element, converted into TValue using converter.

Returns: true if the element exists and has a non-null value; otherwise, false.

Untracked

static ObservableJsonValue Untracked(JsonValue value)

Returns an untracked JSON value

This may return singleton instances for well-known values (null, true/false, 0, empty array of object, ...)

ValueEquals

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

Tests if the value of this node is equal to a given value

• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of a field of this document is equal to a given value

• name — Name of the field
• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of a field of this document is equal to a given value

• name — Name of the field
• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of an item of this array is equal to a given value

• index — Index of this item
• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of an item of this array is equal to a given value

• index — Index of this item
• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of a child of this node is equal to a given value

• segment — Path of this child
• value — Expected value
• comparer — Equality comparer to use (optional)

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

Tests if the value of a descendant of this node is equal to a given value

• path — Path to the node
• value — Expected value
• comparer — Equality comparer to use (optional)

Visit

ObservableJsonValue Visit(JsonValue newValue)

Returns a new instance with the same path, but with the different value

• newValue — New value of this instance

Returns: Equivalent instance, that could replace the current one in its parent

WritePath

void WritePath(ref JsonPathBuilder sb)

Writes the path from the root to this node into the output buffer

Fields

EmptyArray

static readonly ObservableJsonValue EmptyArray

Untracked singleton for [ ]

EmptyObject

static readonly ObservableJsonValue EmptyObject

Untracked singleton for { }

False

static readonly ObservableJsonValue False

Untracked singleton for false

Missing

static readonly ObservableJsonValue Missing

Untracked singleton for "missing" values

This can be used as the root of an observable document that does not exist yet, or has been deleted.

Null

static readonly ObservableJsonValue Null

Untracked singleton for an explicit null value

True

static readonly ObservableJsonValue True

Untracked singleton for true

Zero

static readonly ObservableJsonValue Zero

Untracked singleton for 0