The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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)

Syntax

C++

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

Type Parameters

T: The type of element stored by the array.

Properties

	Name	Description
	IsDefault	Gets a value indicating whether this array was declared but not initialized.
	IsDefaultOrEmpty	Gets a value indicating whether this ImmutableArray<T> is empty or is not initialized.
	IsEmpty	Gets a value indicating whether this ImmutableArray<T> is empty.
	Item[Int32]	Gets the element at the specified index in the immutable array.
	Length	Gets the number of elements in the array.

Methods

	Name	Description
	Add(T)	Returns a copy of the original array with the specified item added to the end.
	AddRange(IEnumerable<T>^)	Returns a copy of the original array with the specified elements added to the end of the array.
	AddRange(ImmutableArray<T>)	Returns a copy of the original array with the specified elements added to the end of the array.
	As<TOther>()	Returns a new immutable array that contains the elements of this array cast to a different type.
	CastArray<TOther>()	Initializes a new instance of the ImmutableArray<T> struct by casting the underlying array to an array of type TOther .
	CastUp<TDerived>(ImmutableArray<TDerived>)	Initializes a new instance of the ImmutableArray<T> struct based on the contents of an existing instance, allowing a covariant static cast to efficiently reuse the existing array.
	Clear()	Returns an array with all the elements removed.
	Contains(T)	Determines whether the specified item exists in the array.
	CopyTo(array<T>^)	Copies the contents of this array to the specified array.
	CopyTo(array<T>^, Int32)	Copies the contents of this array to the specified array starting at the specified destination index.
	CopyTo(Int32, array<T>^, Int32, Int32)	Copies the specified items in this array to the specified array at the specified starting index.
	Equals(ImmutableArray<T>)	Indicates whether specified array is equal to this array.
	Equals(Object^)	Determines if this array is equal to the specified object.(Overrides ValueType::Equals(Object^).)
	GetEnumerator()	Returns an enumerator that iterates through the contents of the array.
	GetHashCode()	Returns a hash code for this instance.(Overrides ValueType::GetHashCode().)
	GetType()	(Inherited from Object.)
	IndexOf(T)	Searches the array for the specified item.
	IndexOf(T, Int32)	Searches the array for the specified item.
	IndexOf(T, Int32, IEqualityComparer<T>^)	Searches the array for the specified item.
	IndexOf(T, Int32, Int32)	Searches the array for the specified item.
	IndexOf(T, Int32, Int32, IEqualityComparer<T>^)	Searches the array for the specified item.
	Insert(Int32, T)	Returns a new array with the specified value inserted at the specified position.
	InsertRange(Int32, IEnumerable<T>^)	Inserts the specified values at the specified index.
	InsertRange(Int32, ImmutableArray<T>)	Inserts the specified values at the specified index.
	LastIndexOf(T)	Searches the array for the specified item; starting at the end of the array.
	LastIndexOf(T, Int32)	Searches the array for the specified item; starting at the end of the array.
	LastIndexOf(T, Int32, Int32)	Searches the array for the specified item; starting at the end of the array.
	LastIndexOf(T, Int32, Int32, IEqualityComparer<T>^)	Searches the array for the specified item; starting at the end of the array.
	OfType<TResult>()	Filters the elements of this array to those assignable to the specified type.
	Remove(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.
	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.
	RemoveAll(Predicate<T>^)	Removes all the items from the array that meet the specified condition.
	RemoveAt(Int32)	Returns an array with the element at the specified position removed.
	RemoveRange(IEnumerable<T>^)	Removes the specified items from this array.
	RemoveRange(IEnumerable<T>^, IEqualityComparer<T>^)	Removes the specified items from this array.
	RemoveRange(ImmutableArray<T>)	Removes the specified values from this list.
	RemoveRange(ImmutableArray<T>, IEqualityComparer<T>^)	Removes the specified items from this list.
	RemoveRange(Int32, Int32)	Returns an array with the elements at the specified position removed.
	Replace(T, T)	Finds the first element in the array equal to the specified value and replaces the value with the specified new value.
	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.
	SetItem(Int32, T)	Replaces the item at the specified index with the specified item.
	Sort()	Sorts the elements in the immutable array using the default comparer.
	Sort(Comparison<T>^)	Sorts the elements in the entire ImmutableArray<T> using the specified Comparison<T>.
	Sort(IComparer<T>^)	Sorts the elements in the immutable array using the specified comparer.
	Sort(Int32, Int32, IComparer<T>^)	Sorts the specified elements in the immutable array using the specified comparer.
	ToBuilder()	Creates a mutable array that has the same contents as this array and can be efficiently mutated across multiple operations using standard mutable interfaces.
	ToString()	(Inherited from ValueType.)

Fields

	Name	Description
	Empty	Gets an empty immutable array.

Operators

	Name	Description
	Equality(ImmutableArray<T>, ImmutableArray<T>)	Returns a value that indicates if two arrays are equal.
	Equality(Nullable<ImmutableArray<T>>, Nullable<ImmutableArray<T>>)	Returns a value that indicates if two arrays are equal.
	Inequality(ImmutableArray<T>, ImmutableArray<T>)	Returns a value that indicates whether two arrays are not equal.
	Inequality(Nullable<ImmutableArray<T>>, Nullable<ImmutableArray<T>>)	Checks for inequality between two array.

Explicit Interface Implementations

	Name	Description
	ICollection<T>::Add(T)	Throws NotSupportedException in all cases.
	ICollection<T>::Clear()	Throws NotSupportedException in all cases.
	ICollection<T>::Remove(T)	Throws NotSupportedException in all cases.
	IEnumerable<T>::GetEnumerator()	Returns an enumerator that iterates through the array.
	IList<T>::Insert(Int32, T)	Throws NotSupportedException in all cases.
	IList<T>::RemoveAt(Int32)	Throws NotSupportedException in all cases.
	ICollection::CopyTo(Array^, Int32)	Copies this array to another array starting at the specified index.
	IEnumerable::GetEnumerator()	Returns an enumerator that iterates through the immutable array.
	IList::Add(Object^)	Throws NotSupportedException in all cases.
	IList::Clear()	Throws NotSupportedException in all cases.
	IList::Contains(Object^)	Throws NotSupportedException in all cases.
	IList::IndexOf(Object^)	Gets the value at the specified index.
	IList::Insert(Int32, Object^)	Throws NotSupportedExceptionin all cases.
	IList::Remove(Object^)	Throws NotSupportedException in all cases.
	IList::RemoveAt(Int32)	Throws NotSupportedException in all cases.
	IImmutableList<T>::Add(T)	Returns a copy of the original array with the specified item added to the end.
	IImmutableList<T>::AddRange(IEnumerable<T>^)	Returns a copy of the original array with the specified elements added to the end of the array.
	IImmutableList<T>::Clear()	Returns an array with all the elements removed.
	IImmutableList<T>::Insert(Int32, T)	Returns a new array with the specified value inserted at the specified position.
	IImmutableList<T>::InsertRange(Int32, IEnumerable<T>^)	Inserts the specified values at the specified index
	IImmutableList<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.
	IImmutableList<T>::RemoveAll(Predicate<T>^)	Removes all the items from the array that meet the specified condition.
	IImmutableList<T>::RemoveAt(Int32)	Returns an array with the element at the specified position removed.
	IImmutableList<T>::RemoveRange(IEnumerable<T>^, IEqualityComparer<T>^)	Removes the specified items from this array.
	IImmutableList<T>::RemoveRange(Int32, Int32)	Returns an array with the elements at the specified position removed.
	IImmutableList<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.
	IImmutableList<T>::SetItem(Int32, T)	Replaces the item at the specified index with the specified item.
	IStructuralComparable::CompareTo(Object^, IComparer^)	Determines whether the current collection element precedes, occurs in the same position as, or follows another element in the sort order.
	IStructuralEquatable::Equals(Object^, IEqualityComparer^)	Determines whether this array is structurally equal to the specified array.
	IStructuralEquatable::GetHashCode(IEqualityComparer^)	Returns a hash code for the current instance.
	ICollection<T>::Count	Gets the number of array in the collection.
	ICollection<T>::IsReadOnly	Gets a value indicating whether this instance is read only.
	IList<T>::Item[Int32]	Gets or sets the element at the specified index in the read-only list.
	IReadOnlyCollection<T>::Count	Gets the number of array in the collection.
	IReadOnlyList<T>::Item[Int32]	Gets the element at the specified index.
	ICollection::Count	Gets the size of the array.
	ICollection::IsSynchronized	See the ICollection interface.
	ICollection::SyncRoot	Gets the sync root.
	IList::IsFixedSize	Gets a value indicating whether this instance is fixed size.
	IList::IsReadOnly	Gets a value indicating whether this instance is read only.
	IList::Item[Int32]	Gets or sets the Object at the specified index.

Extension Methods

	Name	Description
	Aggregate<T>(Func<T, T, T>^)	Overloaded. Applies a function to a sequence of elements in a cumulative way.(Defined by ImmutableArrayExtensions.)
	All<T>(Func<T, Boolean>^)	Gets a value indicating whether all elements in this array match a given condition.(Defined by ImmutableArrayExtensions.)
	Any<T>()	Overloaded. Gets a value indicating whether the array contains any elements.(Defined by ImmutableArrayExtensions.)
	Any<T>(Func<T, Boolean>^)	Overloaded. Gets a value indicating whether the array contains any elements that match a specified condition.(Defined by ImmutableArrayExtensions.)
	BinarySearch<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.)
	BinarySearch<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.)
	BinarySearch<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.)
	BinarySearch<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.)
	ElementAt<T>(Int32)	Returns the element at a specified index in the array.(Defined by ImmutableArrayExtensions.)
	ElementAtOrDefault<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.)
	First<T>()	Overloaded. Returns the first element in an array.(Defined by ImmutableArrayExtensions.)
	First<T>(Func<T, Boolean>^)	Overloaded. Returns the first element in a sequence that satisfies a specified condition.(Defined by ImmutableArrayExtensions.)
	FirstOrDefault<T>()	Overloaded. Returns the first element of a sequence, or a default value if the sequence contains no elements.(Defined by ImmutableArrayExtensions.)
	FirstOrDefault<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.)
	IndexOf<T>(T)	Overloaded. Searches for the specified object and returns the zero-based index of the first occurrence within the list.(Defined by ImmutableList.)
	IndexOf<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.)
	IndexOf<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.)
	IndexOf<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.)
	Last<T>()	Overloaded. Returns the last element of the array.(Defined by ImmutableArrayExtensions.)
	Last<T>(Func<T, Boolean>^)	Overloaded. Returns the last element of a sequence that satisfies a specified condition.(Defined by ImmutableArrayExtensions.)
	LastIndexOf<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.)
	LastIndexOf<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.)
	LastIndexOf<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.)
	LastIndexOf<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.)
	LastOrDefault<T>()	Overloaded. Returns the last element of a sequence, or a default value if the sequence contains no elements.(Defined by ImmutableArrayExtensions.)
	LastOrDefault<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.)
	Remove<T>(T)	Removes the specified value from this list.(Defined by ImmutableList.)
	RemoveRange<T>(IEnumerable<T>^)	Removes the specified values from this list.(Defined by ImmutableList.)
	Replace<T>(T, T)	Replaces the first equal element in the list with the specified element.(Defined by ImmutableList.)
	Select<T, TResult>(Func<T, TResult>^)	Projects each element of a sequence into a new form.(Defined by ImmutableArrayExtensions.)
	SelectMany<TSource, TCollection, TResult>(Func<TSource, IEnumerable<TCollection>^>^, Func<TSource, TCollection, TResult>^)	Projects each element of a sequence to an IEnumerable<T>, flattens the resulting sequences into one sequence, and invokes a result selector function on each element therein. (Defined by ImmutableArrayExtensions.)
	Single<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.)
	Single<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.)
	SingleOrDefault<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.)
	SingleOrDefault<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.)
	ToArray<T>()	Copies the contents of this array to a mutable array.(Defined by ImmutableArrayExtensions.)
	ToImmutableArray<T>()	Creates an immutable array from the specified collection.(Defined by ImmutableArray.)
	ToImmutableDictionary<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.)
	ToImmutableDictionary<T, TKey>(Func<T, TKey>^, IEqualityComparer<TKey>^)	Overloaded. Constructs an immutable dictionary based on some transformation of a sequence.(Defined by ImmutableDictionary.)
	ToImmutableDictionary<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.)
	ToImmutableDictionary<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.)
	ToImmutableDictionary<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.)
	ToImmutableHashSet<T>()	Overloaded. Enumerates a sequence and produces an immutable hash set of its contents.(Defined by ImmutableHashSet.)
	ToImmutableHashSet<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.)
	ToImmutableList<T>()	Enumerates a sequence and produces an immutable list of its contents.(Defined by ImmutableList.)
	ToImmutableSortedDictionary<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.)
	ToImmutableSortedDictionary<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.)
	ToImmutableSortedDictionary<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.)
	ToImmutableSortedSet<T>()	Overloaded. Enumerates a sequence and produces an immutable sorted set of its contents.(Defined by ImmutableSortedSet.)
	ToImmutableSortedSet<T>(IComparer<T>^)	Overloaded. Enumerates a sequence, produces an immutable sorted set of its contents, and uses the specified comparer.(Defined by ImmutableSortedSet.)
	Where<T>(Func<T, Boolean>^)	Filters a sequence of values based on a predicate.(Defined by ImmutableArrayExtensions.)

Remarks

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

Thread Safety

This type is thread safe.

English	Dansk	Deutsch	Español
Français	Italiano	Nederlands	Polski
Português	Svenska	Türkçe	Pусский
日本語	한국어	简体中文	繁體中文