Struct ValueList<T>.Builder
- Namespace
- Badeend.ValueCollections
- Assembly
- Badeend.ValueCollections.dll
A mutable list builder that can be used to efficiently construct new immutable lists.
public readonly struct ValueList<T>.Builder : IEquatable<ValueList<T>.Builder>- Implements
- Inherited Members
- Extension Methods
Remarks
Most mutating methods on this type return this, allowing the caller to
chain multiple mutations in a row.
When you're done building, call Build() to extract the resulting list.
For constructing ValueList<T>s it is recommended to use this
type over e.g. List<T>. This type can avoiding unnecessary
copying by taking advantage of the immutability of its results. Whereas
calling .ToValueList() on a regular List<T>always performs a full copy.
Unlike the resulting ValueList, its Builder is not thread-safe.
To prevent accidental boxing, this type does not implement commonly used interfaces such as IEnumerable<T> and IList<T>. You can still use these interfaces by manually calling AsCollection() instead.
The default value is an empty read-only builder.
Properties
Capacity
The total number of elements the internal data structure can hold without resizing.
[Pure]
public int Capacity { get; }Property Value
Count
Current length of the list.
[Pure]
public int Count { get; }Property Value
IsEmpty
Shortcut for .Count == 0.
[Pure]
public bool IsEmpty { get; }Property Value
IsReadOnly
Returns true when this instance has been built and is now read-only.
[Pure]
public bool IsReadOnly { get; }Property Value
this[int]
Gets or sets the element at the specified index.
public T this[int index] { get; set; }Parameters
indexint
Property Value
- T
Methods
Add(T)
Add an item to the end of the list.
public ValueList<T>.Builder Add(T item)Parameters
itemT
Returns
AddRange(ValueList<T>)
Add the items to the end of the list.
public ValueList<T>.Builder AddRange(ValueList<T> items)Parameters
itemsValueList<T>
Returns
Remarks
An overload that takes any IEnumerable<T> exists as an
extension method.
AddRange(Builder)
Add the items to the end of the list.
public ValueList<T>.Builder AddRange(ValueList<T>.Builder items)Parameters
Returns
Exceptions
- InvalidOperationException
Can't add builder into itself.
AddRange(ValueSlice<T>)
Add the items to the end of the list.
public ValueList<T>.Builder AddRange(ValueSlice<T> items)Parameters
itemsValueSlice<T>
Returns
AddRange(params ReadOnlySpan<T>)
Add the items to the end of the list.
public ValueList<T>.Builder AddRange(params ReadOnlySpan<T> items)Parameters
itemsReadOnlySpan<T>
Returns
AsCollection()
Create a new heap-allocated live view of the builder.
public ValueList<T>.Builder.Collection AsCollection()Returns
Remarks
This method is an O(1) operation and allocates a new fixed-size
collection instance. The items are not copied. Changes made to the
builder are visible in the collection and vice versa.
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 was expected.
[Pure]
public int BinarySearch(T item)Parameters
itemT
Returns
Build()
Finalize the builder and export its contents as a ValueList<T>. This makes the builder read-only. Any future attempt to mutate the builder will throw.
This is an O(1) operation and performs no heap allocations.
public ValueList<T> Build()Returns
- ValueList<T>
Remarks
If you need an intermediate snapshot of the contents while keeping the builder open for mutation, use ToValueList() instead.
Exceptions
- InvalidOperationException
This instance has already been built.
Clear()
Remove all elements from the list.
public ValueList<T>.Builder Clear()Returns
Remarks
The capacity remains unchanged until a call to TrimExcess() is made.
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 list.
EnsureCapacity(int)
Ensures that the capacity of this list is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.
public ValueList<T>.Builder EnsureCapacity(int minimumCapacity)Parameters
minimumCapacityint
Returns
Exceptions
- ArgumentOutOfRangeException
minimumCapacityis less than 0.
Equals(Builder)
Returns true when the two builders refer to the same allocation.
[Pure]
public bool Equals(ValueList<T>.Builder other)Parameters
Returns
GetEnumerator()
Returns an enumerator for this ValueList<T>.Builder.
Typically, you don't need to manually call this method, but instead use
the built-in foreach syntax.
[Pure]
public ValueList<T>.Builder.Enumerator GetEnumerator()Returns
GetHashCode()
Returns the hash code for this instance.
[Pure]
public override int GetHashCode()Returns
- int
A 32-bit signed integer that is the hash code for this instance.
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
Insert(int, T)
Insert an item into the list at the specified index.
public ValueList<T>.Builder Insert(int index, T item)Parameters
indexintitemT
Returns
Exceptions
- ArgumentOutOfRangeException
Invalid
index.
InsertRange(int, ValueList<T>)
Insert the items into the list at the specified index.
public ValueList<T>.Builder InsertRange(int index, ValueList<T> items)Parameters
Returns
Remarks
An overload that takes any IEnumerable<T> exists as an
extension method.
Exceptions
- ArgumentOutOfRangeException
Invalid
index.
InsertRange(int, Builder)
Insert the items into the list at the specified index.
public ValueList<T>.Builder InsertRange(int index, ValueList<T>.Builder items)Parameters
Returns
Exceptions
- InvalidOperationException
Can't insert builder into itself.
- ArgumentOutOfRangeException
Invalid
index.
InsertRange(int, ValueSlice<T>)
Insert the items into the list at the specified index.
public ValueList<T>.Builder InsertRange(int index, ValueSlice<T> items)Parameters
indexintitemsValueSlice<T>
Returns
Exceptions
- ArgumentOutOfRangeException
Invalid
index.
InsertRange(int, params ReadOnlySpan<T>)
Insert the items into the list at the specified index.
public ValueList<T>.Builder InsertRange(int index, params ReadOnlySpan<T> items)Parameters
indexintitemsReadOnlySpan<T>
Returns
Exceptions
- ArgumentOutOfRangeException
Invalid
index.
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
Remove(Predicate<T>)
Remove the first element that matches the predicate.
public ValueList<T>.Builder Remove(Predicate<T> match)Parameters
matchPredicate<T>
Returns
Remove(T)
Remove the first occurrence of a specific object from the list.
public ValueList<T>.Builder Remove(T item)Parameters
itemT
Returns
RemoveAll(Predicate<T>)
Remove all elements that match the predicate.
public ValueList<T>.Builder RemoveAll(Predicate<T> match)Parameters
matchPredicate<T>
Returns
RemoveAll(T)
Remove all occurrences of a specific object from the list.
public ValueList<T>.Builder RemoveAll(T item)Parameters
itemT
Returns
RemoveAt(int)
Remove the element at the specified index.
public ValueList<T>.Builder RemoveAt(int index)Parameters
indexint
Returns
RemoveRange(int, int)
Remove a range of elements from the list.
public ValueList<T>.Builder RemoveRange(int index, int count)Parameters
Returns
Reverse()
Reverse the order of the elements in the list.
public ValueList<T>.Builder Reverse()Returns
SetItem(int, T)
Replaces an element at a given position in the list with the specified element.
public ValueList<T>.Builder SetItem(int index, T value)Parameters
indexintvalueT
Returns
Shuffle()
Performs an in-place shuffle of all elements in the list using a cryptographically secure pseudorandom number generator (CPRNG).
public ValueList<T>.Builder Shuffle()Returns
Sort()
Sort all elements in the list.
public ValueList<T>.Builder Sort()Returns
ToArray()
Copy the contents of the list into a new array.
[Pure]
public T[] ToArray()Returns
- T[]
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
ToValueList()
Copy the current contents of the builder into a new ValueList<T>.
[Pure]
public ValueList<T> ToValueList()Returns
- ValueList<T>
Remarks
If you don't need the builder anymore after this method, consider using Build() instead.
ToValueListBuilder()
Copy the current contents of the builder into a new ValueList<T>.Builder.
[Pure]
public ValueList<T>.Builder ToValueListBuilder()Returns
TrimExcess()
Set the capacity to the actual number of elements in the list, if that number is less than a threshold value.
public ValueList<T>.Builder TrimExcess()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
TryRemove(Predicate<T>)
Attempt to remove the first element that matches the predicate. Returns false when the element wasn't found.
public bool TryRemove(Predicate<T> match)Parameters
matchPredicate<T>
Returns
TryRemove(T)
Attempt to remove the first occurrence of a specific object from the list. Returns false when the element wasn't found.
public bool TryRemove(T item)Parameters
itemT
Returns
Operators
operator ==(Builder, Builder)
Check for equality.
[Pure]
public static bool operator ==(ValueList<T>.Builder left, ValueList<T>.Builder right)Parameters
Returns
operator !=(Builder, Builder)
Check for inequality.
[Pure]
public static bool operator !=(ValueList<T>.Builder left, ValueList<T>.Builder right)