JsonArray

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>, IList<JsonValue>, ICollection<JsonValue>, IEnumerable<JsonValue>, IEnumerable, IReadOnlyList<JsonValue>, IReadOnlyCollection<JsonValue>, IEquatable<JsonArray>, IComparable<JsonArray>

Array of JSON values

Constructors

JsonArray

JsonArray()

Creates a new empty JSON Array

JsonArray(int capacity)

Creates a new empty JSON Array

capacity — Initial capacity

Properties

Capacity

int Capacity { get; set; }

Gets or sets the internal capacity of the array

Should be used before inserting a large number of items, if the final length is known in advance.

Count

int Count { get; }

Returns the number of items in the array.

EmptyReadOnly

static JsonArray EmptyReadOnly { get; }

Returns an empty, read-only, JSON Array singleton

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

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

JsonArray Item { get; }

Type

JsonType Type { get; }

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

Methods

Add

void Add(JsonValue value)

AddNull

void AddNull()

Add a Null item to the array

AddRange

JsonArray AddRange(ReadOnlySpan<JsonValue> values)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddRange(JsonValue[] values)

Appends all the elements of an array to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRange(IEnumerable<JsonValue> values)

Appends all the elements of an IEnumerable to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRange<TSource>(ReadOnlySpan<TSource> values, Func<TSource, JsonValue> selector)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddRange<TSource>(TSource[] values, Func<TSource, JsonValue> selector)

Appends all the elements of an array to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRange<TSource>(IEnumerable<TSource> values, Func<TSource, JsonValue> selector)

Appends all the elements of an IEnumerable to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRange<TKey, TValue>(IDictionary<TKey, TValue> values, Func<TKey, TValue, JsonValue> selector)

Appends all the elements of an IEnumerable to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

AddRangeReadOnly

JsonArray AddRangeReadOnly(ReadOnlySpan<JsonValue> values)

Appends all the elements of a read-only span to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRangeReadOnly(JsonValue[] values)

Appends all the elements of an array to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRangeReadOnly(IEnumerable<JsonValue> values)

Appends all the elements of an IEnumerable to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRangeReadOnly<TSource>(ReadOnlySpan<TSource> values, Func<TSource, JsonValue> selector)

Appends all the elements of a read-only span to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

JsonArray AddRangeReadOnly<TSource>(TSource[] items, Func<TSource, JsonValue> selector)

Appends all the elements of an array to the end of this JsonArray

Any mutable element in will be converted to read-only before being added. Elements that were already read-only will be added be reference.

AddValue

void AddValue<TValue>(TValue value)

Adds a value of type TValue item to the array

AddValues

JsonArray AddValues<TValue>(ReadOnlySpan<TValue> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues<TValue>(TValue[] items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of an array to the end of this JsonArray

JsonArray AddValues<TValue>(IEnumerable<TValue> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of an IEnumerable to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<string> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<int> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<long> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<float> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<double> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<Guid> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues(ReadOnlySpan<Uuid128> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValues<TSource, TValue>(ReadOnlySpan<TSource> items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of a read-only span into a new JsonArray

items — Input read-only span of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

JsonArray AddValues<TSource, TValue>(TSource[] items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of an array into a new JsonArray

items — Input array of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

JsonArray AddValues<TSource, TValue>(IEnumerable<TSource> items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of an IEnumerable into a new JsonArray

items — Input sequence of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

AddValuesReadOnly

JsonArray AddValuesReadOnly<TValue>(ReadOnlySpan<TValue> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of a read-only span to the end of this JsonArray

JsonArray AddValuesReadOnly<TValue>(TValue[] items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of an array to the end of this JsonArray

JsonArray AddValuesReadOnly<TValue>(IEnumerable<TValue> items, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Appends all the elements of an IEnumerable to the end of this JsonArray

JsonArray AddValuesReadOnly<TSource, TValue>(ReadOnlySpan<TSource> items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of a read-only span into a new JsonArray

items — Input read-only span of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

JsonArray AddValuesReadOnly<TSource, TValue>(TSource[] items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of an array into a new JsonArray

items — Input array of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

JsonArray AddValuesReadOnly<TSource, TValue>(IEnumerable<TSource> items, Func<TSource, TValue> transform, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Transforms the elements of an IEnumerable into a new JsonArray

items — Input sequence of elements to transform
transform — Transformation applied to each input element
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

All

bool All(JsonType type)

Tests if all the elements in the array have the specified type

type — Type of element (Object, String, Number, ...)

if at least one element is of a different type, or if the array is empty or with only elements of this type.

bool All(Func<JsonValue, bool> predicate)

Tests if all elements in the array match the specified predicate.

predicate — Callback that should return true for matching elements.

Returns: false if there is at least one element that does not match, or true if the array is empty or without only matching elements.

Any

bool Any()

Tests if there is at least one element in the array

Returns: false if the array is empty; otherwise, true.

bool Any(JsonType type)

Tests if there is at least one element in the array with the specified type

type — Type of element (Object, String, Number, ...)

Returns: true if there is at least one element of this type in the array, or false if the array is empty or contains only elements that are of a different type.

bool Any(Func<JsonValue, bool> predicate)

Tests if there is at least one element in the array that matches the specified predicate

predicate — Callback that should return true for matching elements.

Returns: true if there is at least one element that matches, or true if the array is empty or without any matching element.

ApplyPatch

void ApplyPatch(JsonObject patch, bool deepCopy = false)

Applies a patch to this array, by modifying it in-place

patch — Patch containing the changes to apply to this instance (previously computed by a call to ComputePatch)
deepCopy — If false (default), copy the content of patch as-is; otherwise, clone all the elements before merging them.

If this array was equal to 'before', and is the result of calling ComputePatch(before, after), then the array will now be equal to 'after'

AsArrayOf

JsonArray<TValue> AsArrayOf<TValue>()

Returns a wrapper that will convert all the elements of this JsonArray as values of type TValue when enumerated.

This method can be used to remove the need of allocating a temporary array or list of items that would only be called inside a foreach loop, or used with LINQ.

AsArrayOrDefaultOf

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

Returns a wrapper that will convert all the elements of this JsonArray as values of type TValue when enumerated.

This method can be used to remove the need of allocating a temporary array or list of items that would only be called inside a foreach loop, or used with LINQ.

AsArrays

JsonArray<JsonArray> AsArrays()

Returns a typed view of this array that is expected to only contain JSON arrays

If the array contains any item that is either null or not an array, and exception will be thrown when iterating!

If null entries are allowed, use AsArraysOrDefault instead

AsArraysOrDefault

JsonArrayOrDefault<JsonArray> AsArraysOrDefault()

Returns a typed view of this array that is expected to only contain JSON arrays

If the array contains any item that is either null or not an array, and exception will be thrown when iterating!

If null entries are allowed, use AsArraysOrDefault instead

AsArraysOrEmpty

JsonArrayOrDefault<JsonArray> AsArraysOrEmpty()

Returns a typed view of this array that is expected to only contain JSON arrays

If the array contains any item that is either null or not an array, and exception will be thrown when iterating!

If null entries are allowed, use AsArraysOrDefault instead

AsObjects

JsonArray<JsonObject> AsObjects()

Returns a typed view of this array that is expected to only contain JSON objects

If the array contains any item that is either null or not an object, and exception will be thrown when iterating!

If null entries are allowed, use AsObjectsOrDefault instead

AsObjectsOrDefault

JsonArrayOrDefault<JsonObject> AsObjectsOrDefault()

Returns a typed view of this array that is expected to only contain JSON objects or null entries

If the array contains any item that is not null and not an object, and exception will be thrown when iterating!

If null entries are not allowed, use AsObjects instead

AsObjectsOrEmpty

JsonArrayOrDefault<JsonObject> AsObjectsOrEmpty()

Returns a typed view of this array that is expected to only contain JSON objects or null entries

If the array contains any item that is not null and not an object, and exception will be thrown when iterating!

If null entries are not allowed, use AsObjects instead

Average

TNumber Average<TNumber>()

Returns the average of all the items in JSON Array interpreted as the corresponding TNumber

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.

BindArray

static TValue[] BindArray<TValue>(JsonValue value, TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null, bool required = false)

Deserializes a JSON Array into an array of TValue

value — JSON value known to be a JSON Array
defaultValue — Default value if the value is null or missing
resolver — Optional type resolver
required — If true, all items must be non-null

Returns: Array of TValue

BindList

static List<TValue> BindList<TValue>(JsonValue value, ICrystalJsonTypeResolver resolver = null, bool required = false)

Deserializes a JSON Array into a list of objects of the specified type

value — JSON Array that contains the elements to bind
resolver — Optional type resolver
required — If true the array cannot be null

Returns: A list of all elements that have been deserialized into instance of type TValue

Cast

JsonArray<TValue> Cast<TValue>()

Returns a wrapper that will convert all the elements of this JsonArray as values of type TValue when enumerated.

This method can be used to remove the need of allocating a temporary array or list of items that would only be called inside a foreach loop, or used with LINQ.

JsonArrayOrDefault<TValue> Cast<TValue>(TValue defaultValue)

Returns a wrapper that will convert all the elements of this JsonArray as values of type TValue when enumerated.

This method can be used to remove the need of allocating a temporary array or list of items that would only be called inside a foreach loop, or used with LINQ.

Clear

void Clear()

Clears the content of the array

Keeps the internal buffer, unless its capacity is greater than 1024 items

To always release the buffer, you should call TrimExcess after Clear

Combine

static JsonArray Combine(JsonArray arr1, JsonArray arr2)

Combines two JsonArrays into a single new array

The new array contains a copy of the items of the two input arrays

static JsonArray Combine(JsonArray arr1, JsonArray arr2, JsonArray arr3)

Combines three JsonArrays into a single new array

The new array contains a copy of the items of the three input arrays

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.

int CompareTo(JsonArray other)

ComputeChanges

(JsonArray, JsonArray, JsonArray) ComputeChanges(JsonArray previous)

Compare this array with a previous version, and return the list of added, removed and unchanged elements

previous — Previous version of this array

The change detection is "by value" semantics, but will be faster if both the current and previous arrays are "immutable" and where unchanged elements are copied by reference

ComputePatch

JsonValue ComputePatch(JsonArray after, bool deepCopy = false, bool readOnly = false)

Compute the delta between this array and a different version, in order to produce a patch that contains the instruction to go from this instance to the new version

after — New version of the array
deepCopy — If true, create a copy of all mutable elements before adding them to the resulting patch.
readOnly — If true, the resulting patch will be read-only

Returns: Value that can be passed to ApplyPatch in order to transform this array into after.

The patch produced is not marked as immutable. The caller should call on the result if immutability is required.

Contains

bool Contains(JsonValue item)

Determines whether the JSON Array contains a specific JSON value.

item — The value to locate in the array.

Returns: true if item is found in the array; otherwise, false.

If is , it will match any null or missing entries. If it is any of , or , it will only match the same singletons.

Copy

JsonArray Copy()

Returns a new mutable copy of this JSON Array (and all of its children)

Returns: A deep copy of this array and its children.

This will recursively copy all JSON objects or arrays present in the array, even if they are already mutable.

static JsonArray Copy(JsonArray array, bool deep, bool readOnly = false)

Creates a copy of a JSON Array

array — JSON Array to clone
deep — If true, recursively copy the children as well. If false, perform a shallow copy that reuse the same children.
readOnly — If true, the copy will become read-only. If false, the copy will be writable.

Returns: Copy of array, and optionally of its children (if deep is true

CopyAndAdd

JsonArray CopyAndAdd(JsonValue value)

Returns a new read-only copy of this array with an additional item

value — Item that will be appended to the end of the new copy

Returns: A new instance with the same content of the original array, plus the additional item

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

Please note that is value is a JSON Array, it will be added as a child element. To append the items of an array, please use CopyAndConcat instead

static JsonArray CopyAndAdd(ref JsonArray original, JsonValue value)

Replaces a published JSON Array with a new version with an added item, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
value — Value of the field to append

Returns: New published JSON Array, that includes the new item.

This method will attempt to atomically replace the original JSON Array with a new version, unless another thread was able to update it faster, in which case it will simply retry with the newest version, until it is able to successfully update the reference.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

Please note that is value is a JSON Array, it will be added as a child element. To append the items of an array, please use CopyAndConcat instead

CopyAndConcat

JsonArray CopyAndConcat(JsonArray tail)

Returns a new read-only copy of this array concatenated with another array

tail — Array that will be appended to the end of the new copy

Returns: A new instance with the same content of the original array, plus the content of the tail

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

To add the array itself as a new item, please use CopyAndAdd instead.

JsonArray CopyAndConcat(ReadOnlySpan<JsonValue> tail)

Returns a new read-only copy of this array concatenated with another array

tail — Span of items that will be appended to the end of the new copy

Returns: A new instance with the same content of the original array, plus the content of the tail

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

static JsonArray CopyAndConcat(ref JsonArray original, JsonArray tail)

Replaces a published JSON Array with a new version with extra items appended to the end, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
tail — Array that will be appended to the end of the new copy

Returns: New published JSON Array, that includes the new items.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

To add the array itself as a new item, please use CopyAndAdd instead.

static JsonArray CopyAndConcat(ref JsonArray original, ReadOnlySpan<JsonValue> tail)

Replaces a published JSON Array with a new version with extra items appended to the end, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
tail — Array of items that will be appended to the end of the new copy

Returns: New published JSON Array, that includes the new items.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

CopyAndInsert

JsonArray CopyAndInsert(int index, JsonValue value)

Returns a new read-only copy of this array, with a new item inserted at the specified location

index — Index where to insert, with all following items shifted to the right. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value to write at this location

Returns: A new instance with the same content of the original object, with the additional item inserted at the specified location.

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

JsonArray CopyAndInsert(Index index, JsonValue value)

Returns a new read-only copy of this array, with a new item inserted at the specified location

index — Index where to insert the item, with all following items shifted to the right. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value to write at this location

Returns: A new instance with the same content of the original object, with the additional item inserted at the specified location.

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

static JsonArray CopyAndInsert(ref JsonArray original, int index, JsonValue value)

Replaces a published JSON Array with a new version with an item inserted at the specified location, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index where to insert the item, with all following items shifted to the right. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value to write at this location

Returns: New published JSON Array, that includes the new item.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

static JsonArray CopyAndInsert(ref JsonArray original, Index index, JsonValue value)

Replaces a published JSON Array with a new version with an item inserted at the specified location, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index where to insert the item, with all following items shifted to the right. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value to write at this location

Returns: New published JSON Array, that includes the new item.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

CopyAndRemove

JsonArray CopyAndRemove(int index)

Returns a new read-only copy of this array without the specified item

index — Index of the location to remove, with all following items shifted to the left.

Returns: A new instance with the same content of the original array, but with the specified item removed.

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

JsonArray CopyAndRemove(Index index)

Returns a new read-only copy of this array without the specified item

index — Index of the location to remove, with all following items shifted to the left.

Returns: A new instance with the same content of the original array, but with the specified item removed.

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

JsonArray CopyAndRemove(int index, out JsonValue previous)

Returns a new read-only copy of this array without the specified item

index — Index of the location to remove, with all following items shifted to the left.
previous — Receives the value that was removed, or null if the index was outside the bounds of the array

Returns: A new instance with the same content of the original array, but with the specified item removed.

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

JsonArray CopyAndRemove(Index index, out JsonValue previous)

Returns a new read-only copy of this array without the specified item

index — Index of the location to remove, with all following items shifted to the left.
previous — Receives the value that was removed, or null if the index was outside the bounds of the array

Returns: A new instance with the same content of the original array, but with the specified item removed.

If the array was not read-only, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays.

static JsonArray CopyAndRemove(ref JsonArray original, int index)

Replaces a published JSON Array with a new version without the specified item, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index of the location to remove, with all following items shifted to the left.

Returns: New published JSON Array without the field, or the original array if the was not present.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

static JsonArray CopyAndRemove(ref JsonArray original, Index index)

Replaces a published JSON Array with a new version without the specified item, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index of the location to remove, with all following items shifted to the left.

Returns: New published JSON Array without the field, or the original array if the was not present.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

CopyAndSet

JsonArray CopyAndSet(int index, JsonValue value)

Returns a new read-only copy of this array, with a new item at the specified location

index — Index of the item to modify. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value of the new item

Returns: A new instance with the same content of the original object, except the additional item at the specified location.

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

JsonArray CopyAndSet(Index index, JsonValue value)

Returns a new read-only copy of this array, with a new item at the specified location

index — Index of the item to modify. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value of the new item

Returns: A new instance with the same content of the original object, except the additional item at the specified location.

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

static JsonArray CopyAndSet(ref JsonArray original, int index, JsonValue value)

Replaces a published JSON Array with a new version with a new item at the specified location, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index of the item to modify. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value of the new item

Returns: New published JSON Array, that includes the new item.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

static JsonArray CopyAndSet(ref JsonArray original, Index index, JsonValue value)

Replaces a published JSON Array with a new version with a new item at the specified location, in a thread-safe manner, using a SpinWait if necessary.

original — Reference to the currently published JSON Array
index — Index of the item to modify. If the array is too small, any gaps will be filled with nulls, and value will be inserted last.
value — Value of the new item

Returns: New published JSON Array, that includes the new item.

Caution: the order of operation between threads is not guaranteed, and this method may loop infinitely if it is perpetually blocked by another, faster, thread !

JsonArray CopyAndSet(int index, JsonValue value, out JsonValue previous)

Returns a new read-only copy of this array, with a new item at the specified location

index — Index where to write the new item
value — Value of the new item
previous — Receives the previous value at this location, or null if the index is outside the bounds of the array.

Returns: A new instance with the same content of the original object, plus the additional item

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

JsonArray CopyAndSet(Index index, JsonValue value, out JsonValue previous)

Returns a new read-only copy of this array, with a new item at the specified location

index — Index where to write the new item
value — Value of the new item
previous — Receives the previous value at this location, or null if the index is outside the bounds of the array.

Returns: A new instance with the same content of the original object, plus the additional item

If the array was not-readonly, existing non-readonly items will also be converted to read-only.

For best performance, this should only be used on already read-only arrays, and with read-only values.

CopyTo

void CopyTo(Span<JsonValue> destination)

Copies the contents of this JSON Array into a destination Span.

destination — The destination Span object.

void CopyTo(JsonValue[] array, int arrayIndex)

Create

static JsonArray Create()

Creates a new mutable empty JSON Array

For a read-only array, see

static JsonArray Create(JsonValue value)

Creates a new mutableJSON Array with a single element

For a read-only array, see

static JsonArray Create(JsonValue[] values)

Creates a new mutableJSON Array from an array of elements

For a read-only array, see

static JsonArray Create(ReadOnlySpan<JsonValue> items)

Creates a new mutableJSON Array from a span of elements

For a read-only array, see

static JsonArray Create(IEnumerable<JsonValue> items)

Creates a new mutableJSON Array from a sequence of elements

items — Elements of the new array

For a read-only array, see

static JsonArray Create(JsonValue value1, JsonValue value2)

Creates a new mutableJSON Array with 2 elements

For a read-only array, see

static JsonArray Create(bool readOnly, JsonValue[] items)

Creates a new JsonArray from the specified items, that will be either read-only or mutable.

readOnly — If true, creates a read-only JsonArray that cannot be modified.
items — Items to copy

Returns: New JsonArray with the same elements as in items.

If readOnly is true, any JsonValue in items will replaced by a read-only equivalent, if they are mutable.

static JsonArray Create(bool readOnly, ReadOnlySpan<JsonValue> items)

Creates a new JsonArray from the specified items, that will be either read-only or mutable.

readOnly — If true, creates a read-only JsonArray that cannot be modified.
items — Items to copy

Returns: New JsonArray with the same elements as in items.

If readOnly is true, any JsonValue in items will replaced by a read-only equivalent, if they are mutable.

This overload is intended for creating a read-only JsonArray using collection expressions via the following syntax: // create a new read-only array JsonArray immutable = [ with(readOnly: true), "hello", "world", 123, /.../ ]; // array cannot be modified immutable.Add("there"); // => throws InvalidOperationException

static JsonArray Create(bool readOnly, IEnumerable<JsonValue> items)

Creates a new JsonArray from the specified items, that will be either read-only or mutable.

readOnly — If true, creates a read-only JsonArray that cannot be modified.
items — Items to copy

Returns: New JsonArray with the same elements as in items.

If readOnly is true, any JsonValue in items will replaced by a read-only equivalent, if they are mutable.

static JsonArray Create(JsonValue value1, JsonValue value2, JsonValue value3)

Creates a new mutableJSON Array with 3 elements

For a read-only array, see

static JsonArray Create(JsonValue value1, JsonValue value2, JsonValue value3, JsonValue value4)

Creates a new mutableJSON Array with 4 elements

For a read-only array, see

EndsWith

bool EndsWith(JsonArray suffix)

Determines whether the elements of specified array appears at the end of the current array.

suffix — An array of elements to search for at the end of the current array

Returns: true all the elements of suffix match the last elements of the current array; otherwise, false

bool EndsWith(ReadOnlySpan<JsonValue> suffix)

Determines whether the specified elements appear at the end of the current array.

suffix — A span to search for at the end of the current array

Returns: true all the elements of suffix match the last elements of the current array; otherwise, false

Equals

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.

bool Equals(JsonArray other)

Tests if two arrays are considered equal

bool Equals(JsonArray other, IEqualityComparer<JsonValue> comparer)

Tests if two arrays are considered equal, using a custom equality comparer

Find

JsonValue Find(Func<JsonValue, bool> predicate)

Finds and returns the first element in the array that matches the given predicate

predicate — Predicate that will evaluate all the elements in the array, in order, until it returns either true, or there are no more elements

Returns: First element where predicate returned true, or null if the array is empty, or no element was matched.

Flatten

JsonArray Flatten(bool deep = false)

Flattens a list of nested lists into a single list

deep — If false, only flattens the first level. If true, recursively flattens all nested lists

Returns: Flattened list

Flatten([ [1,2], 3, [4, [5,6]] ], deep: false) => [ 1, 2, 3, 4, [5, 6] ]Flatten([ [1,2], 3, [4, [5,6]] ], deep: true) => [ 1, 2, 3, 4, 5, 6 ]

Freeze

JsonArray Freeze()

Freezes this object and all its children, and mark it as read-only.

This is similar to the { get; init; } pattern for CLR records, and allows initializing a JSON object and then marking it as read-only once it is ready to be returned and/or shared, without performing extra memory allocations.

Please note that, once "frozen", the operation cannot be reverted, and if additional mutations are required, a new copy of the object must be created.

FromValues

static JsonArray FromValues<TValue>(ReadOnlySpan<TValue> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of raw values.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues<TValue>(TValue[] values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from an array of raw values.

values — Array of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues<TValue>(IEnumerable<TValue> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a sequence of raw values.

values — Sequence of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<string> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of string literals.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<int> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of numbers.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<long> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of numbers.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<float> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of numbers.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<double> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of numbers.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<Guid> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of Guid.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues(ReadOnlySpan<Uuid128> values, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array from a span of Uuid128.

values — Span of values that must be converted
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all values converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues<TItem, TValue>(ReadOnlySpan<TItem> values, Func<TItem, TValue> selector, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array with values extracted from a span of source items.

values — Span of items to convert
selector — Lambda that will extract a value from each item in the source.
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all the values extracted from the source, and converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues<TItem, TValue>(TItem[] values, Func<TItem, TValue> selector, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array with values extracted from an array of source items.

values — Array of items to convert
selector — Lambda that will extract a value from each item in the source.
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all the values extracted from the source, and converted into JsonValue instances

For a read-only array, see

static JsonArray FromValues<TItem, TValue>(IEnumerable<TItem> values, Func<TItem, TValue> selector, CrystalJsonSettings settings = null, ICrystalJsonTypeResolver resolver = null)

Creates a new mutable JSON Array with values extracted from a sequence of source items.

values — Sequence of items to convert
selector — Lambda that will extract a value from each item in the source.
settings — Serialization settings (use default JSON settings if null)
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Mutable array with all the values extracted from the source, and converted into JsonValue instances

For a read-only array, see

GetElementsTypeOrDefault

JsonType? GetElementsTypeOrDefault()

Tests if all elements in the array have a similar type, or if they are dissimilar

Returns: The JsonType that have elements all have in common, or null if there is at least two incompatible types present.

Ignore any null or missing elements in the array, so for example [ 123, null, 789 ] will return Number.

Will return null if the array is only filled with null or missing values, instead of Null.

GetEnumerator

Enumerator GetEnumerator()

Returns an enumerator that iterates through the 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.

GetMemory

ReadOnlyMemory<JsonValue> GetMemory()

Returns a read-only span of all items in this array

ReadOnlyMemory<JsonValue> GetMemory(int start)

Returns a read-only span of the items in this array, starting from the specified index

ReadOnlyMemory<JsonValue> GetMemory(Range range)

Returns a read-only span of the items in this array, for the specified range

ReadOnlyMemory<JsonValue> GetMemory(int start, int length)

Returns a read-only span of the items in this array, starting from the specified index for a specified length

GetRange

JsonArray GetRange(int index)

Returns a new JSON Array with a shallow copy of all the items starting from the specified index

JsonArray GetRange(Index index)

Returns a new JSON Array with a shallow copy of all the items starting from the specified index

JsonArray GetRange(Range range)

Return a new JSON Array with a shallow copy of all the items in the specified range

JsonArray GetRange(int index, int count)

Returns a new JSON Array with a shallow copy of all the items in the specified range

GetSpan

ReadOnlySpan<JsonValue> GetSpan()

Returns a read-only span of all items in this array

ReadOnlySpan<JsonValue> GetSpan(int start)

Returns a read-only span of the items in this array, starting from the specified index

ReadOnlySpan<JsonValue> GetSpan(Range range)

Returns a read-only span of the items in this array, for the specified range

ReadOnlySpan<JsonValue> GetSpan(int start, int length)

Returns a read-only span of the items in this array, starting from the specified index for a specified length

GetValue

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.

GetValueOrDefault

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.

IndexOf

int IndexOf(JsonValue item)

Determines the index of a specific value in the JSON Array.

item — The value to locate in the array.

Returns: The index of item if found in the array; otherwise, -1.

If is , it will match any null or missing entries. If it is any of , or , it will only match the same singletons.

Insert

void Insert(int index, JsonValue item)

Inserts an item to the JSON Array at the specified index.

index — The zero-based index at which item should be inserted.
item — The object to insert into the array.

void Insert(Index index, JsonValue item)

Inserts an item to the JSON Array at the specified index.

index — The index at which item should be inserted.
item — The object to insert into the array.

JsonSerialize

void JsonSerialize(CrystalJsonWriter writer)

Serializes this instance as JSON

writer — Writer that will output the content of this instance

KeepOnly

int KeepOnly(Func<JsonValue, bool> predicate)

Keep only the elements that match a predicate

predicate — Predicate that should return true for elements to keep, and false for elements to discard

Returns: Number of elements that where kept

The original array is modified

Max

TNumber Max<TNumber>()

Returns the sum of all the items in JSON Array interpreted as the corresponding TNumber

Merge

static JsonArray Merge(JsonArray parent, JsonArray other, bool deepCopy = false, bool keepNull = false)

Merges the content of an array into the current array

parent — Parent array that will be modified
other — Source array that should be copied into the parent.
deepCopy — If false (default), copy the content of other as-is; otherwise, clone all the elements before merging them.
keepNull — If false (default), fields set to null in other will be removed; otherwise, they will be kept as null entries in the merged result.

MergeWith

void MergeWith(JsonArray other, bool deepCopy = false, bool keepNull = false)

Merges the content of an array into the current array

other — Source array that should be copied into the current array.
deepCopy — If false (default), copy the content of other as-is; otherwise, clone all the elements before merging them.
keepNull — If false (default), fields set to null in other will be removed; otherwise, they will be kept as null entries in the merged result.

Min

TNumber Min<TNumber>()

Returns the sum of all the items in JSON Array interpreted as the corresponding TNumber

Parse

static JsonArray Parse(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 Parse(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 Parse(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 Parse(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.

static JsonArray Parse(string jsonText, IFormatProvider provider)

static JsonArray 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.

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.

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.

Remove

bool Remove(JsonValue item)

Removes the first occurrence of a specific value from the JSON Array.

item — The value to remove from the array.

Returns: true if item was successfully removed from the array; otherwise, false. This method also returns false if item is not found in the original array.

RemoveAll

int RemoveAll(Func<JsonValue, bool> predicate)

Remove all the elements that match a predicate

predicate — Predicate that returns true for elements to remove, and false for elements to keep

Returns: Number of elements that where removed

The original array is modified

RemoveAt

void RemoveAt(int index)

Removes the item at the specified index.

index — The zero-based index of the item to remove.

void RemoveAt(Index index)

Removes the item at the specified index.

index — The index of the item to remove.

RemoveDuplicates

void RemoveDuplicates()

Remove duplicate elements from this array

Similar to Distinct(), except that it modifies the original array.

Return

static JsonArray Return<T1>((T1) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2>(in (T1, T2) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2, T3>(in (T1, T2, T3) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2, T3, T4>(in (T1, T2, T3, T4) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2, T3, T4, T5>(in (T1, T2, T3, T4, T5) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2, T3, T4, T5, T6>(in (T1, T2, T3, T4, T5, T6) tuple)

Converts a ValueTuple into the equivalent JsonArray

static JsonArray Return<T1, T2, T3, T4, T5, T6, T7>(in (T1, T2, T3, T4, T5, T6, T7) tuple)

Converts a ValueTuple into the equivalent JsonArray

Set

void Set(int index, JsonValue item)

Sets the value of the item at the specified index

void Set(Index index, JsonValue item)

Sets the value of the item at the specified index

Slice

JsonArray Slice(int start)

Forms a new array out of the given array, beginning at 'start'.

start — The zero-based index at which to begin this slice.

The returned array keeps the "readonly-ness" of the original

JsonArray Slice(int start, int length)

Forms a new array out of the given array, beginning at 'start', of given length

start — The zero-based index at which to begin this slice.
length — The desired length for the slice (exclusive).

The returned array keeps the "readonly-ness" of the original

StartsWith

bool StartsWith(JsonArray prefix)

Determines whether the elements of specified array appears at the start of the current array.

prefix — An array of elements to search for at the start of the current array

Returns: true all the elements of prefix match the first elements of the current array; otherwise, false

bool StartsWith(ReadOnlySpan<JsonValue> prefix)

Determines whether the specified elements appear at the start of the current array.

prefix — A span of elements to search for at the start of the current array

Returns: true all the elements of prefix match the first elements of the current array; otherwise, false

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(ReadOnlySpan<JsonValue> other)

bool StrictEquals(JsonValue[] other)

bool StrictEquals(JsonArray other)

bool StrictEquals(IEnumerable<JsonValue> other)

Sum

TNumber Sum<TNumber>()

Returns the sum of all the items in JSON Array interpreted as the corresponding TNumber

Swap

void Swap(int first, int second)

Swap two items in this JSON Array

first — Index of the first item
second — Index of the second item

[ 1, 2, 3, 4 ].Swap(1, 2) === [ 1, 3, 2, 4 ]

void Swap(Index first, Index second)

Swap two items in this JSON Array

first — Index of the first item
second — Index of the second item

[ 1, 2, 3, 4 ].Swap(^2, ^1) === [ 1, 2, 4, 3 ]

ToArray

JsonValue[] ToArray()

Returns an array of JsonValue with the same items as this JsonArray

Return a shallow copy of the array.

TValue[] ToArray<TValue>(Func<JsonValue, TValue> decoder)

Deserializes this array into an array of TValue, using a custom decoder

decoder — Func that is called do decode each element of this array

Returns: Array of deserialized items

TValue[] ToArray<TValue>(TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Deserializes this array into an array of TValue

defaultValue — Default value for items that are null or missing
resolver — Optional custom resolver used to bind the value into a managed type.

Returns: Array of deserialized items

ToArrayDeserializable

TValue[] ToArrayDeserializable<TValue>(ICrystalJsonTypeResolver resolver = null)

Deserializes this array into an array of TValue

Returns: Array of deserialized items

ToBoolArray

bool[] ToBoolArray(bool defaultValue = false)

Returns the equivalent Boolean array

ToBoolList

List<bool> ToBoolList(bool defaultValue = false)

Deserializes this JSON Array into a list of Boolean

ToDateTimeArray

DateTime[] ToDateTimeArray(DateTime defaultValue = null)

Returns the equivalent DateTime array

ToDateTimeList

List<DateTime> ToDateTimeList(DateTime defaultValue = null)

Deserializes this JSON Array into a list of UInt64

ToDateTimeOffsetArray

DateTimeOffset[] ToDateTimeOffsetArray(DateTimeOffset defaultValue = null)

Returns the equivalent DateTimeOffset array

ToDateTimeOffsetList

List<DateTimeOffset> ToDateTimeOffsetList(DateTimeOffset defaultValue = null)

Deserializes this JSON Array into a list of UInt64

ToDecimalArray

decimal[] ToDecimalArray(decimal defaultValue = 0)

Returns the equivalent Decimal array

ToDecimalList

List<decimal> ToDecimalList(decimal defaultValue = 0)

Deserializes this JSON Array into a list of Decimal

ToDoubleArray

double[] ToDoubleArray(double defaultValue = 0)

Returns the equivalent Double array

ToDoubleList

List<double> ToDoubleList(double defaultValue = 0)

Deserializes this JSON Array into a list of Double

ToGuidArray

Guid[] ToGuidArray(Guid defaultValue = null)

Returns the equivalent Guid array

ToGuidList

List<Guid> ToGuidList(Guid defaultValue = null)

Deserializes this JSON Array into a list of Guid

ToHalfArray

Half[] ToHalfArray(Half defaultValue = null)

Returns the equivalent Half array

ToHalfList

List<Half> ToHalfList(Half defaultValue = null)

Deserializes this JSON Array into a list of Double

ToHashSet

HashSet<JsonValue> ToHashSet(IEqualityComparer<JsonValue> comparer = null)

Returns a HashSet with the same elements as this array

comparer — Comparer used by the set. If null, uses the Strict value comparer.

Returns: A shallow copy of the original items

HashSet<TValue> ToHashSet<TValue>(Func<JsonValue, TValue> decoder, IEqualityComparer<TValue> comparer = null)

Returns a HashSet with the transformed elements of this array

decoder — Func that is called do decode each element of this array
comparer — Comparer used by the set

Returns: A list of all elements that have been converted decoder

HashSet<TValue> ToHashSet<TValue>(TValue defaultValue = null, IEqualityComparer<TValue> comparer = null, ICrystalJsonTypeResolver resolver = null)

Returns a HashSet with the same elements as this array

defaultValue — Default value of null items
comparer — Comparer used by the set
resolver — Optional type resolver

ToImmutableArray

ImmutableArray<TValue> ToImmutableArray<TValue>(Func<JsonValue, TValue> decoder)

Deserializes this array into an immutable array of TValue, using a custom decoder

decoder — Func that is called do decode each element of this array

Returns: Immutable array of deserialized items

ImmutableArray<TValue> ToImmutableArray<TValue>(TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Deserializes this JSON Array into an ImmutableList

ToImmutableList

ImmutableList<TValue> ToImmutableList<TValue>(Func<JsonValue, TValue> decoder)

Deserializes this array into an immutable array of TValue, using a custom decoder

decoder — Func that is called do decode each element of this array

Returns: Immutable array of deserialized items

ImmutableList<TValue> ToImmutableList<TValue>(TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Deserializes this JSON Array into an ImmutableList

ToInstantArray

Instant[] ToInstantArray(Instant defaultValue = null)

Returns the equivalent Instant array

ToInstantList

List<Instant> ToInstantList(Instant defaultValue = null)

Deserializes this JSON Array into a list of Instant

ToInt32Array

int[] ToInt32Array(int defaultValue = 0)

Returns the equivalent Int32 array

ToInt32List

List<int> ToInt32List(int defaultValue = 0)

Deserializes this JSON Array into a list of Int32

ToInt64Array

long[] ToInt64Array(long defaultValue = 0)

Returns the equivalent Int64 array

ToInt64List

List<long> ToInt64List(long defaultValue = 0)

Deserializes this JSON Array into a list of Int64

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

ToList

List<JsonValue> ToList()

Returns a List<JsonValue> with the same elements as this array

Returns: A shallow copy of the original items

List<TValue> ToList<TValue>(Func<JsonValue, TValue> decoder)

Returns a List with the transformed elements of this array

decoder — Func that is called do decode each element of this array

Returns: A list of all elements that have been converted decoder

List<TValue> ToList<TValue>(TValue defaultValue = null, ICrystalJsonTypeResolver resolver = null)

Returns a List<JsonValue> with the same elements as this array

Returns: A shallow copy of the original items

ToListDeserializable

List<TValue> ToListDeserializable<TValue>(ICrystalJsonTypeResolver resolver = null)

Deserializes this array into an array of TValue

Returns: Array of deserialized items

ToMutable

JsonArray ToMutable()

Converts this JSON Array 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 JSON Array with a List<object?>.

ToReadOnly

JsonArray ToReadOnly()

Returns a new immutable read-only version of this JSON Array (and all of its children)

Returns: The same object, if it is already read-only; otherwise, a deep copy marked as read-only.

A JSON object that is immutable is truly safe against any modification, including any of its direct or indirect children.

ToSingleArray

float[] ToSingleArray(float defaultValue = 0)

Returns the equivalent Single array

ToSingleList

List<float> ToSingleList(float defaultValue = 0)

Deserializes this JSON Array into a list of Single

ToStringArray

string[] ToStringArray(string defaultValue = null)

Returns the equivalent String array

ToStringList

List<string> ToStringList(string defaultValue = null)

Deserializes this JSON Array into a list of String

ToUInt32Array

uint[] ToUInt32Array(uint defaultValue = 0)

Returns the equivalent UInt32 array

ToUInt32List

List<uint> ToUInt32List(uint defaultValue = 0)

Deserializes this JSON Array into a list of UInt32

ToUInt64Array

ulong[] ToUInt64Array(ulong defaultValue = 0)

Returns the equivalent UInt64 array

ToUInt64List

List<ulong> ToUInt64List(ulong defaultValue = 0)

Deserializes this JSON Array into a list of UInt64

ToUuid128Array

Uuid128[] ToUuid128Array(Uuid128 defaultValue = null)

Returns the equivalent Uuid128 array

ToUuid128List

List<Uuid128> ToUuid128List(Uuid128 defaultValue = null)

Deserializes this JSON Array into a list of UInt64

TrimExcess

void TrimExcess()

Trim the size of the internal buffer to reduce memory consumption.

Should only be used to reduce the wasted internal space if the JSON array is expected to be kept alive for a long duration

Truncate

JsonArray Truncate(int size, JsonValue padding = null)

Set the new size of the array, adding or removing elements if necessary

size — New size of the array
padding — Value used to fill the array, if it needs to be enlarged

Returns: The same instance

If the array was already the correct size, there is no changes to the array.

If the array was smaller, new padding elements are added until the length is equal to size

If the array was larger, all the extra elements are removed (padding is ignored in this case)

TryCopyTo

bool TryCopyTo(Span<JsonValue> destination)

Attempts to copy the contents of this JSON Array to a destination Span and returns a value that indicates whether the copy operation succeeded.

destination — The target of the copy operation.

Returns: true if the copy operation succeeded; otherwise, false.

TryFind

bool TryFind(Func<JsonValue, bool> predicate, out JsonValue value)

Finds and returns the first element in the array that matches the given predicate

predicate — Predicate that will evaluate all the elements in the array, in order, until it returns either true, or there are no more elements
value — Receives the first element that matched

Returns: true if predicate matched an element, or false if the array is empty, or no element was matched.

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)

TryGetValue

bool TryGetValue(int index, out JsonValue value)

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

index — Index of the value to retrieve
value — When this method returns, the value located at the specified index, if the index is inside the bounds of the array; otherwise, null. This parameter is passed uninitialized.

Returns: true if index is inside the bounds of the array; otherwise, false.

bool TryGetValue(Index index, out JsonValue value)

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

index — Index of the value to retrieve
value — When this method returns, the value located at the specified index, if the index is inside the bounds of the array; otherwise, null. This parameter is passed uninitialized.

Returns: true if index is inside the bounds of the array; otherwise, false.

ValueEquals

bool ValueEquals<TCollection>(TCollection value, IEqualityComparer<TCollection> 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

ValuesEqual

bool ValuesEqual(string[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<string> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual(int[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<int> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual(long[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<long> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual(float[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<float> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual(double[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<double> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual(bool[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual(ReadOnlySpan<bool> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual<TValue>(ReadOnlySpan<TValue> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual<TValue>(ReadOnlyMemory<TValue> items)

Tests if the elements of this array are equal to the elements of the specified span, using the strict JSON comparison semantics

bool ValuesEqual<TValue>(TValue[] items)

Tests if the elements of this array are equal to the elements of the specified array, using the strict JSON comparison semantics

bool ValuesEqual<TValue>(IEnumerable<TValue> items)

Tests if the elements of this array are equal to the elements of the specified sequence, using the strict JSON comparison semantics

WriteTo

void WriteTo(ref SliceWriter writer)

Serializes the current instance to the specified output buffer