ImmutableArray<T> Structure

 

Represents an array that is immutable; meaning it cannot be changed once it is created.

NuGet package: System.Collections.Immutable (about immutable collections and how to install)

Namespace:   System.Collections.Immutable
Assembly:  System.Collections.Immutable (in System.Collections.Immutable.dll)

[DefaultMemberAttribute("Item")]
[DebuggerDisplayAttribute("{DebuggerDisplay,nq}")]
public struct ImmutableArray<T> : IList<T>, ICollection<T>, IEquatable<ImmutableArray<T>>, 
	IImmutableList<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, 
	IEnumerable<T>, IList, ICollection, IEnumerable, IStructuralComparable, 
	IStructuralEquatable

Type Parameters

T

The type of element stored by the array.

NameDescription
System_CAPS_pubpropertyIsDefault

Gets a value indicating whether this array was declared but not initialized.

System_CAPS_pubpropertyIsDefaultOrEmpty

Gets a value indicating whether this ImmutableArray<T> is empty or is not initialized.

System_CAPS_pubpropertyIsEmpty

Gets a value indicating whether this ImmutableArray<T> is empty.

System_CAPS_pubpropertyItem[Int32]

Gets the element at the specified index in the immutable array.

System_CAPS_pubpropertyLength

Gets the number of elements in the array.

NameDescription
System_CAPS_pubmethodAdd(T)

Returns a copy of the original array with the specified item added to the end.

System_CAPS_pubmethodAddRange(IEnumerable<T>)

Returns a copy of the original array with the specified elements added to the end of the array.

System_CAPS_pubmethodAddRange(ImmutableArray<T>)

Returns a copy of the original array with the specified elements added to the end of the array.

System_CAPS_pubmethodAs<TOther>()

Returns a new immutable array that contains the elements of this array cast to a different type.

System_CAPS_pubmethodClear()

Returns an array with all the elements removed.

System_CAPS_pubmethodContains(T)

Determines whether the specified item exists in the array.

System_CAPS_pubmethodCopyTo(T[])

Copies the contents of this array to the specified array.

System_CAPS_pubmethodCopyTo(T[], Int32)

Copies the contents of this array to the specified array starting at the specified destination index.

System_CAPS_pubmethodCopyTo(Int32, T[], Int32, Int32)

Copies the specified items in this array to the specified array at the specified starting index.

System_CAPS_pubmethodEquals(ImmutableArray<T>)

Indicates whether specified array is equal to this array.

System_CAPS_pubmethodEquals(Object)

Determines if this array is equal to the specified object.(Overrides ValueType.Equals(Object).)

System_CAPS_pubmethodGetEnumerator()

Returns an enumerator that iterates through the contents of the array.

System_CAPS_pubmethodGetHashCode()

Returns a hash code for this instance.(Overrides ValueType.GetHashCode().)

System_CAPS_pubmethodGetType()

(Inherited from Object.)

System_CAPS_pubmethodIndexOf(T)

Searches the array for the specified item.

System_CAPS_pubmethodIndexOf(T, Int32)

Searches the array for the specified item.

System_CAPS_pubmethodIndexOf(T, Int32, IEqualityComparer<T>)

Searches the array for the specified item.

System_CAPS_pubmethodIndexOf(T, Int32, Int32)

Searches the array for the specified item.

System_CAPS_pubmethodIndexOf(T, Int32, Int32, IEqualityComparer<T>)

Searches the array for the specified item.

System_CAPS_pubmethodInsert(Int32, T)

Returns a new array with the specified value inserted at the specified position.

System_CAPS_pubmethodInsertRange(Int32, IEnumerable<T>)

Inserts the specified values at the specified index.

System_CAPS_pubmethodInsertRange(Int32, ImmutableArray<T>)

Inserts the specified values at the specified index.

System_CAPS_pubmethodLastIndexOf(T)

Searches the array for the specified item; starting at the end of the array.

System_CAPS_pubmethodLastIndexOf(T, Int32)

Searches the array for the specified item; starting at the end of the array.

System_CAPS_pubmethodLastIndexOf(T, Int32, Int32)

Searches the array for the specified item; starting at the end of the array.

System_CAPS_pubmethodLastIndexOf(T, Int32, Int32, IEqualityComparer<T>)

Searches the array for the specified item; starting at the end of the array.

System_CAPS_pubmethodOfType<TResult>()

Filters the elements of this array to those assignable to the specified type.

System_CAPS_pubmethodRemove(T)

Returns an array with the first occurrence of the specified element removed from the array. If no match is found, the current array is returned.

System_CAPS_pubmethodRemove(T, IEqualityComparer<T>)

Returns an array with the first occurrence of the specified element removed from the array.

If no match is found, the current array is returned.

System_CAPS_pubmethodRemoveAll(Predicate<T>)

Removes all the items from the array that meet the specified condition.

System_CAPS_pubmethodRemoveAt(Int32)

Returns an array with the element at the specified position removed.

System_CAPS_pubmethodRemoveRange(IEnumerable<T>)

Removes the specified items from this array.

System_CAPS_pubmethodRemoveRange(IEnumerable<T>, IEqualityComparer<T>)

Removes the specified items from this array.

System_CAPS_pubmethodRemoveRange(ImmutableArray<T>)

Removes the specified values from this list.

System_CAPS_pubmethodRemoveRange(ImmutableArray<T>, IEqualityComparer<T>)

Removes the specified items from this list.

System_CAPS_pubmethodRemoveRange(Int32, Int32)

Returns an array with the elements at the specified position removed.

System_CAPS_pubmethodReplace(T, T)

Finds the first element in the array equal to the specified value and replaces the value with the specified new value.

System_CAPS_pubmethodReplace(T, T, IEqualityComparer<T>)

Finds the first element in the array equal to the specified value and replaces the value with the specified new value.

System_CAPS_pubmethodSetItem(Int32, T)

Replaces the item at the specified index with the specified item.

System_CAPS_pubmethodSort()

Sorts the elements in the immutable array using the default comparer.

System_CAPS_pubmethodSort(IComparer<T>)

Sorts the elements in the immutable array using the specified comparer.

System_CAPS_pubmethodSort(Int32, Int32, IComparer<T>)

Sorts the specified elements in the immutable array using the specified comparer.

System_CAPS_pubmethodToBuilder()

Creates a mutable array that has the same contents as this array and can be efficiently mutated across multiple operations using standard mutable interfaces.

System_CAPS_pubmethodToString()

(Inherited from ValueType.)

NameDescription
System_CAPS_pubfieldSystem_CAPS_staticEmpty

Gets an empty immutable array.

NameDescription
System_CAPS_puboperatorSystem_CAPS_staticEquality(ImmutableArray<T>, ImmutableArray<T>)

Returns a value that indicates if two arrays are equal.

System_CAPS_puboperatorSystem_CAPS_staticEquality(Nullable<ImmutableArray<T>>, Nullable<ImmutableArray<T>>)

Returns a value that indicates if two arrays are equal.

System_CAPS_puboperatorSystem_CAPS_staticInequality(ImmutableArray<T>, ImmutableArray<T>)

Returns a value that indicates whether two arrays are not equal.

System_CAPS_puboperatorSystem_CAPS_staticInequality(Nullable<ImmutableArray<T>>, Nullable<ImmutableArray<T>>)

Checks for inequality between two array.

NameDescription
System_CAPS_pubinterfaceSystem_CAPS_privmethodICollection<T>.Add(T)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodICollection<T>.Clear()

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodICollection<T>.Remove(T)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIEnumerable<T>.GetEnumerator()

Returns an enumerator that iterates through the array.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList<T>.Insert(Int32, T)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList<T>.RemoveAt(Int32)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodICollection.CopyTo(Array, Int32)

Copies this array to another array starting at the specified index.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIEnumerable.GetEnumerator()

Returns an enumerator that iterates through the immutable array.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.Add(Object)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.Clear()

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.Contains(Object)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.IndexOf(Object)

Gets the value at the specified index.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.Insert(Int32, Object)

Throws NotSupportedExceptionin all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.Remove(Object)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIList.RemoveAt(Int32)

Throws NotSupportedException in all cases.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.Add(T)

Returns a copy of the original array with the specified item added to the end.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.AddRange(IEnumerable<T>)

Returns a copy of the original array with the specified elements added to the end of the array.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.Clear()

Returns an array with all the elements removed.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.Insert(Int32, T)

Returns a new array with the specified value inserted at the specified position.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.InsertRange(Int32, IEnumerable<T>)

Inserts the specified values at the specified index

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.Remove(T, IEqualityComparer<T>)

Returns an array with the first occurrence of the specified element removed from the array; if no match is found, the current array is returned.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.RemoveAll(Predicate<T>)

Removes all the items from the array that meet the specified condition.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.RemoveAt(Int32)

Returns an array with the element at the specified position removed.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.RemoveRange(IEnumerable<T>, IEqualityComparer<T>)

Removes the specified items from this array.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.RemoveRange(Int32, Int32)

Returns an array with the elements at the specified position removed.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.Replace(T, T, IEqualityComparer<T>)

Finds the first element in the array equal to the specified value and replaces the value with the specified new value.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIImmutableList<T>.SetItem(Int32, T)

Replaces the item at the specified index with the specified item.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralComparable.CompareTo(Object, IComparer)

Determines whether the current collection element precedes, occurs in the same position as, or follows another element in the sort order.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralEquatable.Equals(Object, IEqualityComparer)

Determines whether this array is structurally equal to the specified array.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralEquatable.GetHashCode(IEqualityComparer)

Returns a hash code for the current instance.

NameDescription
System_CAPS_pubmethodAggregate<T>(Func<T, T, T>)

Overloaded.

Applies a function to a sequence of elements in a cumulative way.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodAll<T>(Func<T, Boolean>)

Gets a value indicating whether all elements in this array match a given condition.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodAny<T>()

Overloaded.

Gets a value indicating whether the array contains any elements.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodAny<T>(Func<T, Boolean>)

Overloaded.

Gets a value indicating whether the array contains any elements that match a specified condition.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodBinarySearch<T>(T)

Overloaded.

Searches the sorted immutable array for a specified element using the default comparer and returns the zero-based index of the element, if it’s found.(Defined by ImmutableArray.)

System_CAPS_pubmethodBinarySearch<T>(T, IComparer<T>)

Overloaded.

Searches a sorted immutable array for a specified element and returns the zero-based index of the element, if it’s found.(Defined by ImmutableArray.)

System_CAPS_pubmethodBinarySearch<T>(Int32, Int32, T)

Overloaded.

Searches a sorted immutable array for a specified element and returns the zero-based index of the element, if it’s found.(Defined by ImmutableArray.)

System_CAPS_pubmethodBinarySearch<T>(Int32, Int32, T, IComparer<T>)

Overloaded.

Searches a sorted immutable array for a specified element and returns the zero-based index of the element.(Defined by ImmutableArray.)

System_CAPS_pubmethodElementAt<T>(Int32)

Returns the element at a specified index in the array.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodElementAtOrDefault<T>(Int32)

Returns the element at a specified index in a sequence or a default value if the index is out of range.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodFirst<T>()

Overloaded.

Returns the first element in an array.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodFirst<T>(Func<T, Boolean>)

Overloaded.

Returns the first element in a sequence that satisfies a specified condition.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodFirstOrDefault<T>()

Overloaded.

Returns the first element of a sequence, or a default value if the sequence contains no elements.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodFirstOrDefault<T>(Func<T, Boolean>)

Overloaded.

Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodIndexOf<T>(T)

Overloaded. Searches for the specified object and returns the zero-based index of the first occurrence within the list.(Defined by ImmutableList.)

System_CAPS_pubmethodIndexOf<T>(T, IEqualityComparer<T>)

Overloaded. Searches for the specified object and returns the zero-based index of the first occurrence within the list.(Defined by ImmutableList.)

System_CAPS_pubmethodIndexOf<T>(T, Int32)

Overloaded. Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the immutable list that extends from the specified index to the last element.(Defined by ImmutableList.)

System_CAPS_pubmethodIndexOf<T>(T, Int32, Int32)

Overloaded. Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the immutable list that extends from the specified index to the last element.(Defined by ImmutableList.)

System_CAPS_pubmethodLast<T>()

Overloaded.

Returns the last element of the array.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodLast<T>(Func<T, Boolean>)

Overloaded. Returns the last element of a sequence that satisfies a specified condition.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodLastIndexOf<T>(T)

Overloaded. Searches for the specified object and returns the zero-based index of the last occurrence within the entire immutable list.(Defined by ImmutableList.)

System_CAPS_pubmethodLastIndexOf<T>(T, IEqualityComparer<T>)

Overloaded. Searches for the specified object and returns the zero-based index of the last occurrence within the entire immutable list.(Defined by ImmutableList.)

System_CAPS_pubmethodLastIndexOf<T>(T, Int32)

Overloaded. Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the immutable list that extends from the first element to the specified index.(Defined by ImmutableList.)

System_CAPS_pubmethodLastIndexOf<T>(T, Int32, Int32)

Overloaded. Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the immutable list that extends from the first element to the specified index.(Defined by ImmutableList.)

System_CAPS_pubmethodLastOrDefault<T>()

Overloaded.

Returns the last element of a sequence, or a default value if the sequence contains no elements.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodLastOrDefault<T>(Func<T, Boolean>)

Overloaded.

Returns the last element of a sequence that satisfies a condition or a default value if no such element is found.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodRemove<T>(T)

Removes the specified value from this list.(Defined by ImmutableList.)

System_CAPS_pubmethodRemoveRange<T>(IEnumerable<T>)

Removes the specified values from this list.(Defined by ImmutableList.)

System_CAPS_pubmethodReplace<T>(T, T)

Replaces the first equal element in the list with the specified element.(Defined by ImmutableList.)

System_CAPS_pubmethodSelect<T, TResult>(Func<T, TResult>)

Projects each element of a sequence into a new form.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodSingle<T>()

Overloaded.

Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodSingle<T>(Func<T, Boolean>)

Overloaded.

Returns the only element of a sequence that satisfies a specified condition, and throws an exception if more than one such element exists.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodSingleOrDefault<T>()

Overloaded.

Returns the only element of the array, or a default value if the sequence is empty; this method throws an exception if there is more than one element in the sequence.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodSingleOrDefault<T>(Func<T, Boolean>)

Overloaded.

Returns the only element of a sequence that satisfies a specified condition or a default value if no such element exists; this method throws an exception if more than one element satisfies the condition.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodToArray<T>()

Copies the contents of this array to a mutable array.(Defined by ImmutableArrayExtensions.)

System_CAPS_pubmethodToImmutableArray<T>()

Creates an immutable array from the specified collection.(Defined by ImmutableArray.)

System_CAPS_pubmethodToImmutableDictionary<T, TKey>(Func<T, TKey>)

Overloaded. Constructs an immutable dictionary from an existing collection of elements, applying a transformation function to the source keys.(Defined by ImmutableDictionary.)

System_CAPS_pubmethodToImmutableDictionary<T, TKey>(Func<T, TKey>, IEqualityComparer<TKey>)

Overloaded. Constructs an immutable dictionary based on some transformation of a sequence.(Defined by ImmutableDictionary.)

System_CAPS_pubmethodToImmutableDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable dictionary of its contents.(Defined by ImmutableDictionary.)

System_CAPS_pubmethodToImmutableDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>, IEqualityComparer<TKey>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable dictionary of its contents by using the specified key comparer.(Defined by ImmutableDictionary.)

System_CAPS_pubmethodToImmutableDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>, IEqualityComparer<TKey>, IEqualityComparer<TValue>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable dictionary of its contents by using the specified key and value comparers.(Defined by ImmutableDictionary.)

System_CAPS_pubmethodToImmutableHashSet<T>()

Overloaded. Enumerates a sequence and produces an immutable hash set of its contents.(Defined by ImmutableHashSet.)

System_CAPS_pubmethodToImmutableHashSet<T>(IEqualityComparer<T>)

Overloaded. Enumerates a sequence, produces an immutable hash set of its contents, and uses the specified equality comparer for the set type.(Defined by ImmutableHashSet.)

System_CAPS_pubmethodToImmutableList<T>()

Enumerates a sequence and produces an immutable list of its contents.(Defined by ImmutableList.)

System_CAPS_pubmethodToImmutableSortedDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable sorted dictionary of its contents.(Defined by ImmutableSortedDictionary.)

System_CAPS_pubmethodToImmutableSortedDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>, IComparer<TKey>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable sorted dictionary of its contents by using the specified key comparer.(Defined by ImmutableSortedDictionary.)

System_CAPS_pubmethodToImmutableSortedDictionary<T, TKey, TValue>(Func<T, TKey>, Func<T, TValue>, IComparer<TKey>, IEqualityComparer<TValue>)

Overloaded. Enumerates and transforms a sequence, and produces an immutable sorted dictionary of its contents by using the specified key and value comparers.(Defined by ImmutableSortedDictionary.)

System_CAPS_pubmethodToImmutableSortedSet<T>()

Overloaded. Enumerates a sequence and produces an immutable sorted set of its contents.(Defined by ImmutableSortedSet.)

System_CAPS_pubmethodToImmutableSortedSet<T>(IComparer<T>)

Overloaded. Enumerates a sequence, produces an immutable sorted set of its contents, and uses the specified comparer.(Defined by ImmutableSortedSet.)

System_CAPS_pubmethodWhere<T>(Func<T, Boolean>)

Filters a sequence of values based on a predicate.(Defined by ImmutableArrayExtensions.)

There are different scenarios best for ImmutableArray<T> and others best for ImmutableList<T>.

Reasons to use immutable array:

  • Updating the data is rare or the number of elements is quite small (less than 16 items)

  • You need to be able to iterate over the data in performance critical sections

  • You have many instances of immutable collections and you can’t afford keeping the data in trees

Reasons to use immutable list:

  • Updating the data is common or the number of elements isn’t expected to be small

  • Updating the collection is more performance critical than iterating the contents

The following table summarizes the performance characteristics of ImmutableArray<T>

Operation

ImmutableArray<T> Complexity

ImmutableList<T> Complexity

Comments

Item

O(1)

O(log n)

Directly index into the underlying array

Add()

O(n)

O(log n)

Requires creating a new array

This type is thread safe.

Return to top
Show: