Class ValueDictionaryBuilder<TKey, TValue>

Namespace

Badeend.ValueCollections

Assembly

Badeend.ValueCollections.dll

A mutable dictionary that can be used to efficiently construct new immutable dictionaries.

public sealed class ValueDictionaryBuilder<TKey, TValue> : IDictionary<TKey, TValue>, ICollection<KeyValuePair<TKey, TValue>>, IReadOnlyDictionary<TKey, TValue>, IReadOnlyCollection<KeyValuePair<TKey, TValue>>, IEnumerable<KeyValuePair<TKey, TValue>>, IEnumerable where TKey : notnull

Type Parameters

TKey

The type of keys in the dictionary.

TValue

The type of values in the dictionary.

Inheritance

object

ValueDictionaryBuilder<TKey, TValue>

Implements

IDictionary<TKey, TValue>

ICollection<KeyValuePair<TKey, TValue>>

IReadOnlyDictionary<TKey, TValue>

IReadOnlyCollection<KeyValuePair<TKey, TValue>>

IEnumerable<KeyValuePair<TKey, TValue>>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ValueCollectionExtensions.AddRange<TKey, TValue>(ValueDictionaryBuilder<TKey, TValue>, ReadOnlySpan<KeyValuePair<TKey, TValue>>)

ValueCollectionExtensions.RemoveRange<TKey, TValue>(ValueDictionaryBuilder<TKey, TValue>, ReadOnlySpan<TKey>)

ValueCollectionExtensions.SetItems<TKey, TValue>(ValueDictionaryBuilder<TKey, TValue>, ReadOnlySpan<KeyValuePair<TKey, TValue>>)

ValueCollectionExtensions.ToValueDictionaryBuilder<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>>)

ValueCollectionExtensions.ToValueDictionaryBuilder<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>>, int)

ValueCollectionExtensions.ToValueDictionary<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>>)

ValueCollectionExtensions.ToValueDictionary<TKey, TValue>(IEnumerable<TValue>, Func<TValue, TKey>)

ValueCollectionExtensions.ToValueDictionary<TSource, TKey, TValue>(IEnumerable<TSource>, Func<TSource, TKey>, Func<TSource, TValue>)

ValueCollectionExtensions.ToValueListBuilder<T>(IEnumerable<T>)

ValueCollectionExtensions.ToValueListBuilder<T>(IEnumerable<T>, int)

ValueCollectionExtensions.ToValueList<T>(IEnumerable<T>)

ValueCollectionExtensions.ToValueSetBuilder<T>(IEnumerable<T>)

ValueCollectionExtensions.ToValueSetBuilder<T>(IEnumerable<T>, int)

ValueCollectionExtensions.ToValueSet<T>(IEnumerable<T>)

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 dictionary.

For constructing ValueDictionary<TKey, TValue>s it is recommended to use this class over e.g. Dictionary<TKey, TValue>. This type can avoiding unnecessary copying by taking advantage of the immutability of its results. Whereas calling .ToValueDictionary() on a regular Dictionary<TKey, TValue>always performs a full copy.

The order in which the entries are enumerated is undefined.

Unlike ValueDictionary, ValueDictionaryBuilder is not thread-safe.

Constructors

ValueDictionaryBuilder()

Construct a new empty dictionary builder.

[Pure]
public ValueDictionaryBuilder()

ValueDictionaryBuilder(IEnumerable<KeyValuePair<TKey, TValue>>)

Construct a new ValueDictionaryBuilder<TKey, TValue> with the provided items as its initial content.

public ValueDictionaryBuilder(IEnumerable<KeyValuePair<TKey, TValue>> items)

Parameters

items IEnumerable<KeyValuePair<TKey, TValue>>

Remarks

Use Builder<TKey, TValue>(ReadOnlySpan<KeyValuePair<TKey, TValue>>) to construct a ValueDictionaryBuilder from a span.

ValueDictionaryBuilder(int)

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

[Pure]
public ValueDictionaryBuilder(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 dictionary.

[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

this[TKey]

Get the value associated with the specified key.

public TValue this[TKey key] { get; set; }

Parameters

key TKey

Property Value

TValue

Exceptions

ArgumentNullException

key is null.

KeyNotFoundException

The key does not exist.

Keys

All keys in the dictionary in no particular order.

[Pure]
public IReadOnlyCollection<TKey> Keys { get; }

Property Value

IReadOnlyCollection<TKey>

Remarks

Every modification to the builder invalidates any Keys collection obtained before that moment.

Values

All values in the dictionary in no particular order.

[Pure]
public IReadOnlyCollection<TValue> Values { get; }

Property Value

IReadOnlyCollection<TValue>

Remarks

Every modification to the builder invalidates any Values collection obtained before that moment.

Methods

Add(TKey, TValue)

Add the key and value to the dictionary.

public ValueDictionaryBuilder<TKey, TValue> Add(TKey key, TValue value)

Parameters

key TKey

value TValue

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

This method throws an exception when the key already exists. If this is not desired, you can use TryAdd(TKey, TValue) or SetItem(TKey, TValue) instead.

Exceptions

ArgumentException

The key already exists.

AddRange(IEnumerable<KeyValuePair<TKey, TValue>>)

Add multiple entries to the dictionary.

public ValueDictionaryBuilder<TKey, TValue> AddRange(IEnumerable<KeyValuePair<TKey, TValue>> items)

Parameters

items IEnumerable<KeyValuePair<TKey, TValue>>

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

More overloads are available as extension methods.

Exceptions

ArgumentException

items contains a duplicate key or a key that already exists in the dictionary.

Build()

Finalize the builder and export its contents as a ValueDictionary<TKey, TValue>. 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 ValueDictionary<TKey, TValue> Build()

Returns

ValueDictionary<TKey, TValue>

Remarks

If you need an intermediate snapshot of the contents while keeping the builder open for mutation, use ToValueDictionary() instead.

Exceptions

InvalidOperationException

This instance has already been built.

Clear()

Remove all elements from the dictionary.

public ValueDictionaryBuilder<TKey, TValue> Clear()

Returns

ValueDictionaryBuilder<TKey, TValue>

ContainsKey(TKey)

Determines whether this dictionary contains an element with the specified key.

[Pure]
public bool ContainsKey(TKey key)

Parameters

key TKey

Returns

bool

ContainsValue(TValue)

Determines whether this dictionary contains an element with the specified value.

[Pure]
public bool ContainsValue(TValue value)

Parameters

value TValue

Returns

bool

Remarks

This performs a linear scan through the dictionary.

EnsureCapacity(int)

Ensures that the capacity of this dictionary is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.

public ValueDictionaryBuilder<TKey, TValue> EnsureCapacity(int capacity)

Parameters

capacity int

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

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

GetEnumerator()

Returns an enumerator for this ValueDictionaryBuilder<TKey, TValue>.

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

[Pure]
public ValueDictionaryBuilder<TKey, TValue>.Enumerator GetEnumerator()

Returns

ValueDictionaryBuilder<TKey, TValue>.Enumerator

GetValueOrDefault(TKey)

Attempt to get the value associated with the specified key. Returns default when the key was not found.

[Pure]
public TValue? GetValueOrDefault(TKey key)

Parameters

key TKey

Returns

TValue

GetValueOrDefault(TKey, TValue)

Attempt to get the value associated with the specified key. Returns defaultValue when the key was not found.

[Pure]
public TValue GetValueOrDefault(TKey key, TValue defaultValue)

Parameters

key TKey

defaultValue TValue

Returns

TValue

Remove(TKey)

Remove a specific key from the dictionary if it exists.

public ValueDictionaryBuilder<TKey, TValue> Remove(TKey key)

Parameters

key TKey

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

Use TryRemove if you want to know whether any element was actually removed.

RemoveRange(IEnumerable<TKey>)

Remove the provided keys from the dictionary.

public ValueDictionaryBuilder<TKey, TValue> RemoveRange(IEnumerable<TKey> keys)

Parameters

keys IEnumerable<TKey>

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

More overloads are available as extension methods.

SetItem(TKey, TValue)

Set the specified key in the dictionary, possibly overwriting an existing value for the key.

public ValueDictionaryBuilder<TKey, TValue> SetItem(TKey key, TValue value)

Parameters

key TKey

value TValue

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

Functionally equivalent to:

builder[key] = value;

SetItems(IEnumerable<KeyValuePair<TKey, TValue>>)

Sets the specified key/value pairs in the dictionary, possibly overwriting existing values for the keys.

public ValueDictionaryBuilder<TKey, TValue> SetItems(IEnumerable<KeyValuePair<TKey, TValue>> items)

Parameters

items IEnumerable<KeyValuePair<TKey, TValue>>

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

When the same key appears multiple times in the items, the last value overwrites any earlier values.

More overloads are available as extension methods.

ToValueDictionary()

Copy the current contents of the builder into a new ValueDictionary<TKey, TValue>.

[Pure]
public ValueDictionary<TKey, TValue> ToValueDictionary()

Returns

ValueDictionary<TKey, TValue>

Remarks

If you don't need the builder anymore after this method, consider using Build() instead.

TrimExcess()

Reduce the capacity of this dictionary as much as possible. After calling this method, the Capacity of the dictionary may still be higher than the Count.

public ValueDictionaryBuilder<TKey, TValue> TrimExcess()

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

This method can be used to minimize the memory overhead of long-lived dictionaries. This method is most useful just before calling Build(), e.g.:

var longLivedDictionary = builder.TrimExcess().Build()

Excessive use of this method most likely introduces more performance problems than it solves.

TrimExcess(int)

Reduce the capacity of the dictionary 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 ValueDictionaryBuilder<TKey, TValue> TrimExcess(int capacity)

Parameters

capacity int

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

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

Exceptions

ArgumentOutOfRangeException

capacity is less than Count.

TryAdd(TKey, TValue)

Attempt to add the key and value to the dictionary. Returns false when the key was already present.

public bool TryAdd(TKey key, TValue value)

Parameters

key TKey

value TValue

Returns

bool

TryGetValue(TKey, out TValue)

Attempt to get the value associated with the specified key. Returns false when the key was not found.

public bool TryGetValue(TKey key, out TValue value)

Parameters

key TKey

value TValue

Returns

bool

TryRemove(TKey)

Attempt to remove a specific key from the dictionary. Returns false when the key was not found.

public bool TryRemove(TKey key)

Parameters

key TKey

Returns

bool

Remarks

This is the equivalent of Dictionary.Remove.

TryRemove(TKey, out TValue)

Attempt to remove a specific key from the dictionary. Returns false when the key was not found. The removed value (if any) is stored in value.

public bool TryRemove(TKey key, out TValue value)

Parameters

key TKey

value TValue

Returns

bool