Table of Contents

Class ValueSetBuilder<T>

Namespace
Badeend.ValueCollections
Assembly
Badeend.ValueCollections.dll

A mutable set that can be used to efficiently construct new immutable sets.

public sealed class ValueSetBuilder<T> : ISet<T>, ICollection<T>, IReadOnlySet<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable

Type Parameters

T

The type of items in the set.

Inheritance
ValueSetBuilder<T>
Implements
ISet<T>
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 class 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.

Unlike ValueSet, ValueSetBuilder is not thread-safe.

Constructors

ValueSetBuilder()

Construct a new empty set builder.

[Pure]
public ValueSetBuilder()

ValueSetBuilder(IEnumerable<T>)

Construct a new ValueSetBuilder<T> with the provided items as its initial content.

public ValueSetBuilder(IEnumerable<T> items)

Parameters

items IEnumerable<T>

Remarks

Use Builder<T>(ReadOnlySpan<T>) to construct a ValueSetBuilder from a span.

ValueSetBuilder(int)

Construct a new empty set builder with at least the specified initial capacity.

[Pure]
public ValueSetBuilder(int capacity)

Parameters

capacity int

Remarks

Available on .NET Standard 2.1 and .NET Core 2.1 and higher.

Exceptions

ArgumentOutOfRangeException

capacity is less than 0.

Properties

Capacity

The total number of elements the internal data structure can hold without resizing.

public int Capacity { get; }

Property Value

int

Remarks

Available on .NET Standard 2.1 and .NET Core 2.1 and higher.

Count

Current size of the set.

[Pure]
public int Count { get; }

Property Value

int

IsEmpty

Shortcut for .Count == 0.

[Pure]
public bool IsEmpty { get; }

Property Value

bool

IsReadOnly

Returns true when this instance has been built and is now read-only.

[Pure]
public bool IsReadOnly { get; }

Property Value

bool

Methods

Add(T)

Add the item to the set if it isn't already present.

public ValueSetBuilder<T> Add(T item)

Parameters

item T

Returns

ValueSetBuilder<T>

Remarks

Use UnionWith(IEnumerable<T>) to add multiple values at once. Use TryAdd(T) if you want to know whether the element was actually added.

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 only a small fixed-size memory allocation. This does not perform a bulk copy of the contents.

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 ValueSetBuilder<T> Clear()

Returns

ValueSetBuilder<T>

Contains(T)

Returns true when the set contains the specified item.

[Pure]
public bool Contains(T item)

Parameters

item T

Returns

bool

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 ValueSetBuilder<T> EnsureCapacity(int capacity)

Parameters

capacity int

Returns

ValueSetBuilder<T>

Remarks

Available on .NET Standard 2.1 and .NET Core 2.1 and higher.

ExceptWith(IEnumerable<T>)

Remove all elements that appear in the other collection.

public ValueSetBuilder<T> ExceptWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

Returns

ValueSetBuilder<T>

Remarks

More overloads are available as extension methods.

GetEnumerator()

Returns an enumerator for this ValueSetBuilder<T>.

Typically, you don't need to manually call this method, but instead use the built-in foreach syntax.

[Pure]
public ValueSetBuilder<T>.Enumerator GetEnumerator()

Returns

ValueSetBuilder<T>.Enumerator

IntersectWith(IEnumerable<T>)

Modify the current builder to contain only elements that are present in both thisand the other collection.

public ValueSetBuilder<T> IntersectWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

Returns

ValueSetBuilder<T>

IsProperSubsetOf(IEnumerable<T>)

Determines whether the current set is a proper (strict) subset of a specified collection.

public bool IsProperSubsetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set is a proper subset of other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsProperSupersetOf(IEnumerable<T>)

Determines whether the current set is a proper (strict) superset of a specified collection.

public bool IsProperSupersetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set is a proper superset of other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsSubsetOf(IEnumerable<T>)

Determines whether a set is a subset of a specified collection.

public bool IsSubsetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set is a subset of other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsSupersetOf(IEnumerable<T>)

Determines whether the current set is a superset of a specified collection.

public bool IsSupersetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set is a superset of other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

Overlaps(IEnumerable<T>)

Determines whether the current set overlaps with the specified collection.

public bool Overlaps(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set and other share at least one common element; otherwise, false.

Exceptions

ArgumentNullException

other is null.

Remove(T)

Remove a specific element from the set if it exists.

public ValueSetBuilder<T> Remove(T item)

Parameters

item T

Returns

ValueSetBuilder<T>

Remarks

Use ExceptWith(IEnumerable<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 ValueSetBuilder<T> RemoveWhere(Predicate<T> match)

Parameters

match Predicate<T>

Returns

ValueSetBuilder<T>

SetEquals(IEnumerable<T>)

Determines whether the current set and the specified collection contain the same elements.

public bool SetEquals(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare to the current set.

Returns

bool

true if the current set is equal to other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

SymmetricExceptWith(IEnumerable<T>)

Remove all elements that appear in both thisand the other collection.

public ValueSetBuilder<T> SymmetricExceptWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

Returns

ValueSetBuilder<T>

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.

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 ValueSetBuilder<T> TrimExcess()

Returns

ValueSetBuilder<T>

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 capacity is only a hint. After this method returns, the Capacity may be rounded up to a nearby, implementation-specific value.

public ValueSetBuilder<T> TrimExcess(int capacity)

Parameters

capacity int

Returns

ValueSetBuilder<T>

Remarks

Available on .NET Standard 2.1 and .NET Core 2.1 and higher.

Exceptions

ArgumentOutOfRangeException

capacity is 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

item T

Returns

bool

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

item T

Returns

bool

Remarks

This is the equivalent of HashSet.Remove.

UnionWith(IEnumerable<T>)

Add all elements from the other collection.

public ValueSetBuilder<T> UnionWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

Returns

ValueSetBuilder<T>

Remarks

More overloads are available as extension methods.

Edit this page