Struct ValueSet<T>.Builder
- Namespace
- Badeend.ValueCollections
- Assembly
- Badeend.ValueCollections.dll
A mutable set that can be used to efficiently construct new immutable sets.
public readonly struct ValueSet<T>.Builder : IEquatable<ValueSet<T>.Builder>- Implements
- Inherited Members
- Extension Methods
Remarks
Most mutating methods on this class return this, allowing the caller to
chain multiple mutations in a row. The boolean-returning
HashSet.Add and
HashSet.Remove are implemented as
TryAdd(T) and TryRemove(T).
When you're done building, call Build() to extract the resulting set.
For constructing ValueSet<T>s it is recommended to use this
type over e.g. HashSet<T>. This type can avoiding unnecessary
copying by taking advantage of the immutability of its results. Whereas
calling .ToValueSet() on a regular HashSet<T>always performs a full copy.
The order in which the elements are enumerated is undefined.
To prevent accidental boxing, this type does not implement commonly used interfaces such as IEnumerable<T> and ISet<T>. You can still use these interfaces by manually calling AsCollection() instead.
Unlike the resulting ValueSet, its Builder is not thread-safe.
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 size of the set.
[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
Methods
Add(T)
Add the item to the set if it isn't already present.
public ValueSet<T>.Builder Add(T item)Parameters
itemT
Returns
Remarks
Use UnionWith(ValueSet<T>) to add multiple values at once. Use TryAdd(T) if you want to know whether the element was actually added.
AsCollection()
Create a new heap-allocated live view of the builder.
public ValueSet<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.
Build()
Finalize the builder and export its contents as a ValueSet<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 ValueSet<T> Build()Returns
- ValueSet<T>
Remarks
If you need an intermediate snapshot of the contents while keeping the builder open for mutation, use ToValueSet() instead.
Exceptions
- InvalidOperationException
This instance has already been built.
Clear()
Remove all elements from the set.
public ValueSet<T>.Builder Clear()Returns
Remarks
The capacity remains unchanged until a call to TrimExcess() is made.
Contains(T)
Returns true when the set contains the specified
item.
[Pure]
public bool Contains(T item)Parameters
itemT
Returns
CopyTo(Span<T>)
Copy the contents of the set into an existing Span<T>.
public void CopyTo(Span<T> destination)Parameters
destinationSpan<T>
Remarks
The order in which the elements are copied is undefined.
Exceptions
- ArgumentException
destinationis shorter than the source slice.
EnsureCapacity(int)
Ensures that the capacity of this set is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.
public ValueSet<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(ValueSet<T>.Builder other)Parameters
Returns
ExceptWith(ValueSet<T>)
Remove all elements that appear in the other collection.
public ValueSet<T>.Builder ExceptWith(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
ExceptWith(scoped ReadOnlySpan<T>)
Remove all elements that appear in the items sequence.
public ValueSet<T>.Builder ExceptWith(scoped ReadOnlySpan<T> items)Parameters
itemsReadOnlySpan<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in items.
GetEnumerator()
Returns an enumerator for this ValueSet<T>.Builder.
Typically, you don't need to manually call this method, but instead use
the built-in foreach syntax.
[Pure]
public ValueSet<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.
IntersectWith(ValueSet<T>)
Modify the current builder to contain only elements that are present in
both thisand the other
collection.
public ValueSet<T>.Builder IntersectWith(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in this.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
IsProperSubsetOf(ValueSet<T>)
Check whether this set is a proper subset of the provided collection.
public bool IsProperSubsetOf(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in this.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
IsProperSupersetOf(ValueSet<T>)
Check whether this set is a proper superset of the provided collection.
public bool IsProperSupersetOf(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in this.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
IsSubsetOf(ValueSet<T>)
Check whether this set is a subset of the provided collection.
public bool IsSubsetOf(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in this.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
IsSupersetOf(ValueSet<T>)
Check whether this set is a superset of the provided collection.
public bool IsSupersetOf(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
IsSupersetOf(scoped ReadOnlySpan<T>)
Check whether this set is a superset of the provided sequence.
public bool IsSupersetOf(scoped ReadOnlySpan<T> other)Parameters
otherReadOnlySpan<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
Overlaps(ValueSet<T>)
Check whether this set and the provided collection share any common elements.
public bool Overlaps(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
Overlaps(scoped ReadOnlySpan<T>)
Check whether this set and the provided collection share any common elements.
public bool Overlaps(scoped ReadOnlySpan<T> other)Parameters
otherReadOnlySpan<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
Remove(T)
Remove a specific element from the set if it exists.
public ValueSet<T>.Builder Remove(T item)Parameters
itemT
Returns
Remarks
Use ExceptWith(ValueSet<T>) to remove multiple values at once. Use TryRemove(T) if you want to know whether any element was actually removed.
RemoveWhere(Predicate<T>)
Remove all elements that match the predicate.
public ValueSet<T>.Builder RemoveWhere(Predicate<T> match)Parameters
matchPredicate<T>
Returns
SetEquals(ValueSet<T>)
Check whether this set and the provided collection contain
the same elements, ignoring duplicates and the order of the elements.
public bool SetEquals(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
SymmetricExceptWith(ValueSet<T>)
Remove all elements that appear in both thisand the other collection.
public ValueSet<T>.Builder SymmetricExceptWith(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
Beware of the performance implications though.
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
ToValueSet()
Copy the current contents of the builder into a new ValueSet<T>.
[Pure]
public ValueSet<T> ToValueSet()Returns
- ValueSet<T>
Remarks
If you don't need the builder anymore after this method, consider using Build() instead.
ToValueSetBuilder()
Copy the current contents of the builder into a new ValueSet<T>.Builder.
[Pure]
public ValueSet<T>.Builder ToValueSetBuilder()Returns
TrimExcess()
Reduce the capacity of this set as much as possible. After calling this
method, the Capacity of the set may still be higher than
the Count.
public ValueSet<T>.Builder TrimExcess()Returns
Remarks
This method can be used to minimize the memory overhead of long-lived sets. This method is most useful just before calling Build(), e.g.:
var longLivedSet = builder.TrimExcess().Build()Excessive use of this method most likely introduces more performance problems than it solves.
TrimExcess(int)
Reduce the capacity of the set to roughly the specified value. If the
current capacity is already smaller than the requested capacity, this
method does nothing. The specified targetCapacity is only
a hint. After this method returns, the Capacity may be
rounded up to a nearby, implementation-specific value.
public ValueSet<T>.Builder TrimExcess(int targetCapacity)Parameters
targetCapacityint
Returns
Exceptions
- ArgumentOutOfRangeException
targetCapacityis less than Count.
TryAdd(T)
Attempt to add the item to the set.
Returns false when the element was
already present.
public bool TryAdd(T item)Parameters
itemT
Returns
Remarks
This is the equivalent of HashSet.Add.
TryRemove(T)
Attempt to remove a specific element from the set. Returns false when the element was not found.
public bool TryRemove(T item)Parameters
itemT
Returns
Remarks
This is the equivalent of HashSet.Remove.
UnionWith(ValueSet<T>)
Add all elements from the other collection.
public ValueSet<T>.Builder UnionWith(ValueSet<T> other)Parameters
otherValueSet<T>
Returns
Remarks
This is an O(n) operation, where n is the number of elements in other.
An overload that takes any IEnumerable<T> exists as an
extension method.
UnionWith(scoped ReadOnlySpan<T>)
Add all elements from the items sequence.
public ValueSet<T>.Builder UnionWith(scoped ReadOnlySpan<T> items)Parameters
itemsReadOnlySpan<T>
Returns
Operators
operator ==(Builder, Builder)
Check for equality.
[Pure]
public static bool operator ==(ValueSet<T>.Builder left, ValueSet<T>.Builder right)Parameters
Returns
operator !=(Builder, Builder)
Check for inequality.
[Pure]
public static bool operator !=(ValueSet<T>.Builder left, ValueSet<T>.Builder right)