Struct ValueDictionary<TKey, TValue>.Builder

Namespace

Badeend.ValueCollections

Assembly

Badeend.ValueCollections.dll

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

public readonly struct ValueDictionary<TKey, TValue>.Builder : IEquatable<ValueDictionary<TKey, TValue>.Builder>

Implements

IEquatable<ValueDictionary<TKey, TValue>.Builder>

Inherited Members

ValueType.Equals(object)

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ValueCollectionExtensions.AddRange<TKey, TValue>(ValueDictionary<TKey, TValue>.Builder, IEnumerable<KeyValuePair<TKey, TValue>>)

ValueCollectionExtensions.RemoveRange<TKey, TValue>(ValueDictionary<TKey, TValue>.Builder, IEnumerable<TKey>)

ValueCollectionExtensions.SetItems<TKey, TValue>(ValueDictionary<TKey, TValue>.Builder, IEnumerable<KeyValuePair<TKey, TValue>>)

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

To prevent accidental boxing, this type does not implement commonly used interfaces such as IEnumerable<T> and IDictionary<TKey, TValue>. You can still use these interfaces by manually calling AsCollection() instead.

Unlike the resulting ValueDictionary, 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.

public int Capacity { get; }

Property Value

int

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 ValueDictionary<TKey, TValue>.Builder.KeysEnumerator Keys { get; }

Property Value

ValueDictionary<TKey, TValue>.Builder.KeysEnumerator

Remarks

Every modification to the builder invalidates any ValueDictionary<TKey, TValue>.Builder.KeysEnumerator obtained before that moment.

Values

All values in the dictionary in no particular order.

[Pure]
public ValueDictionary<TKey, TValue>.Builder.ValuesEnumerator Values { get; }

Property Value

ValueDictionary<TKey, TValue>.Builder.ValuesEnumerator

Remarks

Every modification to the builder invalidates any ValueDictionary<TKey, TValue>.Builder.ValuesEnumerator obtained before that moment.

Methods

Add(TKey, TValue)

Add the key and value to the dictionary.

public ValueDictionary<TKey, TValue>.Builder Add(TKey key, TValue value)

Parameters

key TKey

value TValue

Returns

ValueDictionary<TKey, TValue>.Builder

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(scoped ReadOnlySpan<KeyValuePair<TKey, TValue>>)

Add multiple entries to the dictionary.

public ValueDictionary<TKey, TValue>.Builder AddRange(scoped ReadOnlySpan<KeyValuePair<TKey, TValue>> items)

Parameters

items ReadOnlySpan<KeyValuePair<TKey, TValue>>

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

An overload that takes any IEnumerable exists as an extension method.

Exceptions

ArgumentException

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

AsCollection()

Create a new heap-allocated live view of the builder.

public ValueDictionary<TKey, TValue>.Builder.Collection AsCollection()

Returns

ValueDictionary<TKey, TValue>.Builder.Collection

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 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 no heap allocations.

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 ValueDictionary<TKey, TValue>.Builder Clear()

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

The capacity remains unchanged until a call to TrimExcess() is made.

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 ValueDictionary<TKey, TValue>.Builder EnsureCapacity(int minimumCapacity)

Parameters

minimumCapacity int

Returns

ValueDictionary<TKey, TValue>.Builder

Exceptions

ArgumentOutOfRangeException

minimumCapacity is less than 0.

Equals(Builder)

Returns true when the two builders refer to the same allocation.

[Pure]
public bool Equals(ValueDictionary<TKey, TValue>.Builder other)

Parameters

other ValueDictionary<TKey, TValue>.Builder

Returns

bool

GetEnumerator()

Returns an enumerator for this ValueDictionary<TKey, TValue>.Builder.

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

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

Returns

ValueDictionary<TKey, TValue>.Builder.Enumerator

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.

GetOrAdd(TKey, Func<TKey, TValue>)

Get the value by the provided key. If the key does not already exist, the valueFactory is invoked to generate a new value, which will then be inserted and returned.

public TValue GetOrAdd(TKey key, Func<TKey, TValue> valueFactory)

Parameters

key TKey

valueFactory Func<TKey, TValue>

Returns

TValue

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 ValueDictionary<TKey, TValue>.Builder Remove(TKey key)

Parameters

key TKey

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

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

RemoveRange(scoped ReadOnlySpan<TKey>)

Remove the provided keys from the dictionary.

public ValueDictionary<TKey, TValue>.Builder RemoveRange(scoped ReadOnlySpan<TKey> keys)

Parameters

keys ReadOnlySpan<TKey>

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

An overload that takes any IEnumerable exists as an extension method.

SetItem(TKey, TValue)

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

public ValueDictionary<TKey, TValue>.Builder SetItem(TKey key, TValue value)

Parameters

key TKey

value TValue

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

Functionally equivalent to:

builder[key] = value;

SetItems(scoped ReadOnlySpan<KeyValuePair<TKey, TValue>>)

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

public ValueDictionary<TKey, TValue>.Builder SetItems(scoped ReadOnlySpan<KeyValuePair<TKey, TValue>> items)

Parameters

items ReadOnlySpan<KeyValuePair<TKey, TValue>>

Returns

ValueDictionary<TKey, TValue>.Builder

Remarks

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

An overload that takes any IEnumerable exists as an extension method.

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

string

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.

ToValueDictionaryBuilder()

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

[Pure]
public ValueDictionary<TKey, TValue>.Builder ToValueDictionaryBuilder()

Returns

ValueDictionary<TKey, TValue>.Builder

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 ValueDictionary<TKey, TValue>.Builder TrimExcess()

Returns

ValueDictionary<TKey, TValue>.Builder

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

public ValueDictionary<TKey, TValue>.Builder TrimExcess(int targetCapacity)

Parameters

targetCapacity int

Returns

ValueDictionary<TKey, TValue>.Builder

Exceptions

ArgumentOutOfRangeException

targetCapacity 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

Operators

operator ==(Builder, Builder)

Check for equality.

[Pure]
public static bool operator ==(ValueDictionary<TKey, TValue>.Builder left, ValueDictionary<TKey, TValue>.Builder right)

Parameters

left ValueDictionary<TKey, TValue>.Builder

right ValueDictionary<TKey, TValue>.Builder

Returns

bool

operator !=(Builder, Builder)

Check for inequality.

[Pure]
public static bool operator !=(ValueDictionary<TKey, TValue>.Builder left, ValueDictionary<TKey, TValue>.Builder right)

Parameters

left ValueDictionary<TKey, TValue>.Builder

right ValueDictionary<TKey, TValue>.Builder

Returns

bool