Class ValueList<T>
- Namespace
- Badeend.ValueCollections
- Assembly
- Badeend.ValueCollections.dll
An immutable, thread-safe list with value semantics.
public sealed class ValueList<T> : IReadOnlyList<T>, IReadOnlyCollection<T>, IList<T>, ICollection<T>, IEnumerable<T>, IEnumerable, IEquatable<ValueList<T>>Type Parameters
TThe type of items in the list.
- Inheritance
-
ValueList<T>
- Implements
-
IList<T>ICollection<T>IEnumerable<T>IEquatable<ValueList<T>>
- Inherited Members
- Extension Methods
Remarks
Constructing new instances can be done using Builder<T>() or ToBuilder(). For creating ValueLists, ValueListBuilder<T> is generally more efficient than List<T>.
ValueLists have "structural equality". This means that two lists are considered equal only when their contents are equal. As long as a value is present in a ValueList, its hash code may not change.
Taking a subslice with Slice(int) and Slice(int, int) is very cheap as it reuses the same allocation.
Properties
Count
Length of the list.
[Pure]
public int Count { get; }Property Value
Empty
Get an empty list.
This does not allocate any memory.
[Pure]
public static ValueList<T> Empty { get; }Property Value
- ValueList<T>
IsEmpty
Shortcut for .Count == 0.
[Pure]
public bool IsEmpty { get; }Property Value
this[int]
Get an item from the list at the specified index.
public ref readonly T this[int index] { get; }Parameters
indexint
Property Value
- T
Methods
AsMemory()
Access the list's contents using a ReadOnlyMemory<T>.
[Pure]
public ReadOnlyMemory<T> AsMemory()Returns
AsSpan()
Access the list's contents using a ReadOnlySpan<T>.
[Pure]
public ReadOnlySpan<T> AsSpan()Returns
- ReadOnlySpan<T>
AsValueSlice()
Access the list's contents using a ValueSlice<T>.
[Pure]
public ValueSlice<T> AsValueSlice()Returns
- ValueSlice<T>
BinarySearch(T)
Perform a binary search for item within the list.
The list is assumed to already be sorted. This uses the
Default comparer and throws if
T is not comparable. If the item is found, its
index is returned. Otherwise a negative value is returned representing
the bitwise complement of the index where the item should be inserted.
[Pure]
public int BinarySearch(T item)Parameters
itemT
Returns
Contains(T)
Returns true when the list contains the specified
item.
[Pure]
public bool Contains(T item)Parameters
itemT
Returns
CopyTo(Span<T>)
Copy the contents of the list into an existing Span<T>.
public void CopyTo(Span<T> destination)Parameters
destinationSpan<T>
Exceptions
- ArgumentException
destinationis shorter than the source slice.
Equals(ValueList<T>?)
Returns true when the two lists have identical length and content.
[Pure]
public bool Equals(ValueList<T>? other)Parameters
otherValueList<T>
Returns
GetEnumerator()
Returns an enumerator for this ValueList<T>.
Typically, you don't need to manually call this method, but instead use
the built-in foreach syntax.
[Pure]
public ValueList<T>.Enumerator GetEnumerator()Returns
GetHashCode()
Serves as the default hash function.
[Pure]
public override sealed int GetHashCode()Returns
- int
A hash code for the current object.
IndexOf(T)
Return the index of the first occurrence of item in
the list, or -1 if not found.
[Pure]
public int IndexOf(T item)Parameters
itemT
Returns
LastIndexOf(T)
Return the index of the last occurrence of item in
the list, or -1 if not found.
[Pure]
public int LastIndexOf(T item)Parameters
itemT
Returns
Slice(int)
Create a subslice, starting at offset.
This does not allocate any memory.
[Pure]
public ValueSlice<T> Slice(int offset)Parameters
offsetintThe index at which to begin the subslice.
Returns
- ValueSlice<T>
Exceptions
- ArgumentOutOfRangeException
offsetis below0or greater than the current list's length.
Slice(int, int)
Create a subslice with a specified length,
starting at offset.
This does not allocate any memory.
[Pure]
public ValueSlice<T> Slice(int offset, int length)Parameters
Returns
- ValueSlice<T>
Exceptions
- ArgumentOutOfRangeException
offsetis below0or greater than the current list's length.- ArgumentOutOfRangeException
lengthis below0or would extend beyond the current list's length.
ToArray()
Copy the contents of the list into a new array.
[Pure]
public T[] ToArray()Returns
- T[]
ToBuilder()
Create a new ValueListBuilder<T> with this list as its initial content. This builder can then be used to efficiently construct a new immutable ValueList<T>.
[Pure]
public ValueListBuilder<T> ToBuilder()Returns
Remarks
The capacity of the returned builder may be larger than the size of this list. How much larger exactly is undefined.
ToBuilder(int)
Create a new ValueListBuilder<T> with a capacity of at
least minimumCapacity and with this list as its
initial content. This builder can then be used to efficiently construct
a new immutable ValueList<T>.
[Pure]
public ValueListBuilder<T> ToBuilder(int minimumCapacity)Parameters
minimumCapacityint
Returns
Remarks
This is functionally equivalent to:
list.ToBuilder().EnsureCapacity(minimumCapacity)but without unnecessary intermediate copies.
Exceptions
- ArgumentOutOfRangeException
minimumCapacityis less than 0.
ToString()
Get a string representation of the collection for debugging purposes. The format is not stable and may change without prior notice.
[Pure]
public override string ToString()Returns
TryCopyTo(Span<T>)
Attempt to copy the contents of the list into an existing
Span<T>. If the destination is too short,
no items are copied and the method returns false.
public bool TryCopyTo(Span<T> destination)Parameters
destinationSpan<T>
Returns
Operators
operator ==(ValueList<T>?, ValueList<T>?)
Check for equality.
[Pure]
public static bool operator ==(ValueList<T>? left, ValueList<T>? right)Parameters
Returns
implicit operator ValueSlice<T>(ValueList<T>)
Convert list to slice.
[Pure]
public static implicit operator ValueSlice<T>(ValueList<T> list)Parameters
listValueList<T>
Returns
- ValueSlice<T>
operator !=(ValueList<T>?, ValueList<T>?)
Check for inequality.
[Pure]
public static bool operator !=(ValueList<T>? left, ValueList<T>? right)