Class ValueDictionary<TKey, TValue>

Namespace

Badeend.ValueCollections

Assembly

Badeend.ValueCollections.dll

An immutable, thread-safe dictionary with value semantics.

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

Type Parameters

TKey

The type of keys in the dictionary.

TValue

The type of values in the dictionary.

Inheritance

object

ValueDictionary<TKey, TValue>

Implements

IDictionary<TKey, TValue>

ICollection<KeyValuePair<TKey, TValue>>

IReadOnlyDictionary<TKey, TValue>

IReadOnlyCollection<KeyValuePair<TKey, TValue>>

IEnumerable<KeyValuePair<TKey, TValue>>

IEnumerable

IEquatable<ValueDictionary<TKey, TValue>>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

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

A dictionary provides a mapping from a set of keys to a set of values, contains no duplicate keys, and stores its elements in no particular order.

Constructing new instances can be done using Builder<TKey, TValue>() or ToBuilder(). For creating ValueDictionaries, ValueDictionaryBuilder<TKey, TValue> is generally more efficient than Dictionary<TKey, TValue>.

ValueDictionaries have "structural equality". This means that two dictionaries are considered equal only when their contents are equal. As long as a key or a value is present in a ValueDictionary, its hash code may not change.

The order in which the entries are enumerated is undefined.

Properties

Count

Number of items in the dictionary.

[Pure]
public int Count { get; }

Property Value

int

Empty

Get a new empty dictionary.

This does not allocate any memory.

[Pure]
public static ValueDictionary<TKey, TValue> Empty { get; }

Property Value

ValueDictionary<TKey, TValue>

IsEmpty

Shortcut for .Count == 0.

[Pure]
public bool IsEmpty { get; }

Property Value

bool

this[TKey]

Get the value associated with the specified key.

public TValue this[TKey key] { get; }

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>

Values

All values in the dictionary in no particular order.

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

Property Value

IReadOnlyCollection<TValue>

Methods

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.

Equals(ValueDictionary<TKey, TValue>?)

Returns true when the two dictionaries have identical length and content.

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

Parameters

other ValueDictionary<TKey, TValue>

Returns

bool

GetEnumerator()

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

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

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

Returns

ValueDictionary<TKey, TValue>.Enumerator

GetHashCode()

Serves as the default hash function.

[Pure]
public override sealed int GetHashCode()

Returns

int

A hash code for the current object.

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

ToBuilder()

Create a new ValueDictionaryBuilder<TKey, TValue> with this dictionary as its initial content. This builder can then be used to efficiently construct a new immutable ValueDictionary<TKey, TValue>.

[Pure]
public ValueDictionaryBuilder<TKey, TValue> ToBuilder()

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

The capacity of the returned builder may be larger than the size of this dictionary. How much larger exactly is undefined.

ToBuilder(int)

Create a new ValueDictionaryBuilder<TKey, TValue> with a capacity of at least minimumCapacity and with this dictionary as its initial content. This builder can then be used to efficiently construct a new immutable ValueDictionary<TKey, TValue>.

[Pure]
public ValueDictionaryBuilder<TKey, TValue> ToBuilder(int minimumCapacity)

Parameters

minimumCapacity int

Returns

ValueDictionaryBuilder<TKey, TValue>

Remarks

This is functionally equivalent to:

dictionary.ToBuilder().EnsureCapacity(minimumCapacity)

but without unnecessary intermediate copies.

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

Exceptions

ArgumentOutOfRangeException

minimumCapacity is less than 0.

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

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

Operators

operator ==(ValueDictionary<TKey, TValue>?, ValueDictionary<TKey, TValue>?)

Check for equality.

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

Parameters

left ValueDictionary<TKey, TValue>

right ValueDictionary<TKey, TValue>

Returns

bool

operator !=(ValueDictionary<TKey, TValue>?, ValueDictionary<TKey, TValue>?)

Check for inequality.

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

Parameters

left ValueDictionary<TKey, TValue>

right ValueDictionary<TKey, TValue>

Returns

bool