Class ValueListBuilder<T>
- Namespace
- Badeend.ValueCollections
- Assembly
- Badeend.ValueCollections.dll
A mutable list that can be used to efficiently construct new immutable lists.
public sealed class ValueListBuilder<T> : IList<T>, ICollection<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerableType Parameters
TThe type of items in the list.
- Inheritance
-
ValueListBuilder<T>
- Implements
-
IList<T>ICollection<T>IEnumerable<T>
- Inherited Members
- Extension Methods
Remarks
Most mutating methods on this class 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
class 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 ValueList, ValueListBuilder is not thread-safe.
Constructors
ValueListBuilder()
Construct a new empty list builder.
[Pure]
public ValueListBuilder()ValueListBuilder(IEnumerable<T>)
Construct a new ValueListBuilder<T> with the provided
items as its initial content.
public ValueListBuilder(IEnumerable<T> items)Parameters
itemsIEnumerable<T>
Remarks
Use Builder<T>(ReadOnlySpan<T>) to construct a ValueListBuilder from a span.
ValueListBuilder(int)
Construct a new empty list builder with the specified initial capacity.
[Pure]
public ValueListBuilder(int capacity)Parameters
capacityint
Exceptions
- ArgumentOutOfRangeException
capacityis less than 0.
Properties
Capacity
The total number of elements the internal data structure can hold without resizing.
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 ValueListBuilder<T> Add(T item)Parameters
itemT
Returns
AddRange(IEnumerable<T>)
Add the items to the end of the list.
public ValueListBuilder<T> AddRange(IEnumerable<T> items)Parameters
itemsIEnumerable<T>
Returns
Remarks
More overloads are available as extension methods.
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
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 only a small fixed-size
memory allocation. This does not perform a bulk copy of the contents.
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 ValueListBuilder<T> Clear()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 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 ValueListBuilder<T> EnsureCapacity(int capacity)Parameters
capacityint
Returns
GetEnumerator()
Returns an enumerator for this ValueListBuilder<T>.
Typically, you don't need to manually call this method, but instead use
the built-in foreach syntax.
[Pure]
public ValueListBuilder<T>.Enumerator GetEnumerator()Returns
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 ValueListBuilder<T> Insert(int index, T item)Parameters
indexintitemT
Returns
InsertRange(int, IEnumerable<T>)
Insert the items into the list at the specified index.
public ValueListBuilder<T> InsertRange(int index, IEnumerable<T> items)Parameters
indexintitemsIEnumerable<T>
Returns
Remarks
More overloads are available as extension methods.
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
RemoveAll(Predicate<T>)
Remove all elements that match the predicate.
public ValueListBuilder<T> RemoveAll(Predicate<T> match)Parameters
matchPredicate<T>
Returns
RemoveAll(T)
Remove all occurrences of a specific object from the list.
public ValueListBuilder<T> RemoveAll(T item)Parameters
itemT
Returns
RemoveAt(int)
Remove the element at the specified index.
public ValueListBuilder<T> RemoveAt(int index)Parameters
indexint
Returns
RemoveFirst(Predicate<T>)
Remove the first element that matches the predicate.
public ValueListBuilder<T> RemoveFirst(Predicate<T> match)Parameters
matchPredicate<T>
Returns
RemoveFirst(T)
Remove the first occurrence of a specific object from the list.
public ValueListBuilder<T> RemoveFirst(T item)Parameters
itemT
Returns
RemoveRange(int, int)
Remove a range of elements from the list.
public ValueListBuilder<T> RemoveRange(int index, int count)Parameters
Returns
Reverse()
Reverse the order of the elements in the list.
public ValueListBuilder<T> Reverse()Returns
SetItem(int, T)
Replaces an element at a given position in the list with the specified element.
public ValueListBuilder<T> SetItem(int index, T value)Parameters
indexintvalueT
Returns
Sort()
Sort all elements in the list.
public ValueListBuilder<T> Sort()Returns
ToArray()
Copy the contents of the list into a new array.
[Pure]
public T[] ToArray()Returns
- T[]
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.
TrimExcess()
Set the capacity to the actual number of elements in the list, if that number is less than a threshold value.
public ValueListBuilder<T> 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>