Class OrderedDict<TKey, TValue>

Namespace

OptunaSharp.Collections

Assembly

OptunaSharp.dll

Insertion-order-preserving dictionary helpers shared by all target frameworks.

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

Type Parameters

TKey

The non-null key type compared by the dictionary comparer.

TValue

The type of values stored with each key.

Inheritance

object

OrderedDict<TKey, TValue>

Implements

IDictionary<TKey, TValue>

IReadOnlyDictionary<TKey, TValue>

IDictionary

IList<KeyValuePair<TKey, TValue>>

ICollection<KeyValuePair<TKey, TValue>>

IReadOnlyList<KeyValuePair<TKey, TValue>>

IReadOnlyCollection<KeyValuePair<TKey, TValue>>

IEnumerable<KeyValuePair<TKey, TValue>>

IList

ICollection

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Operations on the collection have algorithmic complexities that are similar to that of the List<T> class, except with lookups by key similar in complexity to that of Dictionary<TKey, TValue>.

Constructors

OrderedDict()

Initializes a new instance of the OrderedDict<TKey, TValue> class that is empty, has the default initial capacity, and uses the default equality comparer for the key type.

public OrderedDict()

OrderedDict(IDictionary<TKey, TValue>)

Initializes a new instance of the OrderedDict<TKey, TValue> class that contains elements copied from the specified IDictionary<TKey, TValue> and uses the default equality comparer for the key type.

public OrderedDict(IDictionary<TKey, TValue> dictionary)

Parameters

dictionary IDictionary<TKey, TValue>

The IDictionary<TKey, TValue> whose elements are copied to the new OrderedDict<TKey, TValue>. The initial order of the elements in the new collection is the order the elements are enumerated from the supplied dictionary.

Exceptions

ArgumentNullException

dictionary is null.

OrderedDict(IDictionary<TKey, TValue>, IEqualityComparer<TKey>?)

Initializes a new instance of the OrderedDict<TKey, TValue> class that contains elements copied from the specified IDictionary<TKey, TValue> and uses the specified IEqualityComparer<T>.

public OrderedDict(IDictionary<TKey, TValue> dictionary, IEqualityComparer<TKey>? comparer)

Parameters

dictionary IDictionary<TKey, TValue>

The IDictionary<TKey, TValue> whose elements are copied to the new OrderedDict<TKey, TValue>. The initial order of the elements in the new collection is the order the elements are enumerated from the supplied dictionary.

comparer IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentNullException

dictionary is null.

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

Initializes a new instance of the OrderedDict<TKey, TValue> class that contains elements copied from the specified IEnumerable<T> and uses the default equality comparer for the key type.

public OrderedDict(IEnumerable<KeyValuePair<TKey, TValue>> collection)

Parameters

collection IEnumerable<KeyValuePair<TKey, TValue>>

The IEnumerable<T> whose elements are copied to the new OrderedDict<TKey, TValue>. The initial order of the elements in the new collection is the order the elements are enumerated from the supplied collection.

Exceptions

ArgumentNullException

collection is null.

OrderedDict(IEnumerable<KeyValuePair<TKey, TValue>>, IEqualityComparer<TKey>?)

Initializes a new instance of the OrderedDict<TKey, TValue> class that contains elements copied from the specified IEnumerable<T> and uses the specified IEqualityComparer<T>.

public OrderedDict(IEnumerable<KeyValuePair<TKey, TValue>> collection, IEqualityComparer<TKey>? comparer)

Parameters

collection IEnumerable<KeyValuePair<TKey, TValue>>

The IEnumerable<T> whose elements are copied to the new OrderedDict<TKey, TValue>. The initial order of the elements in the new collection is the order the elements are enumerated from the supplied collection.

comparer IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentNullException

collection is null.

OrderedDict(IEqualityComparer<TKey>?)

Initializes a new instance of the OrderedDict<TKey, TValue> class that is empty, has the default initial capacity, and uses the specified IEqualityComparer<T>.

public OrderedDict(IEqualityComparer<TKey>? comparer)

Parameters

comparer IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

OrderedDict(int)

Initializes a new instance of the OrderedDict<TKey, TValue> class that is empty, has the specified initial capacity, and uses the default equality comparer for the key type.

public OrderedDict(int capacity)

Parameters

capacity int

The initial number of elements that the OrderedDict<TKey, TValue> can contain.

Exceptions

ArgumentOutOfRangeException

capacity is less than 0.

OrderedDict(int, IEqualityComparer<TKey>?)

Initializes a new instance of the OrderedDict<TKey, TValue> class that is empty, has the specified initial capacity, and uses the specified IEqualityComparer<T>.

public OrderedDict(int capacity, IEqualityComparer<TKey>? comparer)

Parameters

capacity int

The initial number of elements that the OrderedDict<TKey, TValue> can contain.

comparer IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentOutOfRangeException

capacity is less than 0.

Properties

Capacity

Gets the total number of key/value pairs the internal data structure can hold without resizing.

public int Capacity { get; }

Property Value

int

Comparer

Gets the IEqualityComparer<T> that is used to determine equality of keys for the dictionary.

public IEqualityComparer<TKey> Comparer { get; }

Property Value

IEqualityComparer<TKey>

Count

Gets the number of key/value pairs contained in the OrderedDict<TKey, TValue>.

public int Count { get; }

Property Value

int

this[TKey]

Gets or sets the value associated with the specified key.

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

Parameters

key TKey

The key of the value to get or set.

Property Value

TValue

The value associated with the specified key. If the specified key is not found, a get operation throws a KeyNotFoundException, and a set operation creates a new element with the specified key.

Remarks

Setting the value of an existing key does not impact its order in the collection.

Exceptions

ArgumentNullException

key is null.

KeyNotFoundException

The property is retrieved and key does not exist in the collection.

Keys

Gets a collection containing the keys in the OrderedDict<TKey, TValue>.

public OrderedDict<TKey, TValue>.KeyCollection Keys { get; }

Property Value

OrderedDict<TKey, TValue>.KeyCollection

Values

Gets a collection containing the values in the OrderedDict<TKey, TValue>.

public OrderedDict<TKey, TValue>.ValueCollection Values { get; }

Property Value

OrderedDict<TKey, TValue>.ValueCollection

Methods

Add(TKey, TValue)

Adds the specified key and value to the dictionary.

public void Add(TKey key, TValue value)

Parameters

key TKey

The key of the element to add.

value TValue

The value of the element to add. The value can be null for reference types.

Exceptions

ArgumentNullException

key is null.

ArgumentException

An element with the same key already exists in the OrderedDict<TKey, TValue>.

Clear()

Removes all keys and values from the OrderedDict<TKey, TValue>.

public void Clear()

ContainsKey(TKey)

Determines whether the OrderedDict<TKey, TValue> contains the specified key.

public bool ContainsKey(TKey key)

Parameters

key TKey

The key to locate in the OrderedDict<TKey, TValue>.

Returns

bool

true if the OrderedDict<TKey, TValue> contains an element with the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

ContainsValue(TValue)

Determines whether the OrderedDict<TKey, TValue> contains a specific value.

public bool ContainsValue(TValue value)

Parameters

value TValue

The value to locate in the OrderedDict<TKey, TValue>. The value can be null for reference types.

Returns

bool

true if the OrderedDict<TKey, TValue> contains an element with the specified value; otherwise, false.

EnsureCapacity(int)

Ensures that the dictionary can hold up to capacity entries without resizing.

public int EnsureCapacity(int capacity)

Parameters

capacity int

The desired minimum capacity of the dictionary. The actual capacity provided may be larger.

Returns

int

The new capacity of the dictionary.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

GetAt(int)

Gets the key/value pair at the specified index.

public KeyValuePair<TKey, TValue> GetAt(int index)

Parameters

index int

The zero-based index of the pair to get.

Returns

KeyValuePair<TKey, TValue>

The element at the specified index.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than or equal to Count.

GetEnumerator()

Returns an enumerator that iterates through the OrderedDict<TKey, TValue>.

public OrderedDict<TKey, TValue>.Enumerator GetEnumerator()

Returns

OrderedDict<TKey, TValue>.Enumerator

A OrderedDict<TKey, TValue>.Enumerator structure for the OrderedDict<TKey, TValue>.

GetValueOrDefault(TKey, TValue?)

Python dict.get(key, default).

public TValue? GetValueOrDefault(TKey key, TValue? defaultValue = default)

Parameters

key TKey

The non-null lookup key, compared with the dictionary's configured comparer.

defaultValue TValue

The value returned when the key has no entry.

Returns

TValue

The stored value when the key exists, otherwise the supplied fallback.

IndexOf(TKey)

Determines the index of a specific key in the OrderedDict<TKey, TValue>.

public int IndexOf(TKey key)

Parameters

key TKey

The key to locate.

Returns

int

The index of key if found; otherwise, -1.

Exceptions

ArgumentNullException

key is null.

Insert(int, TKey, TValue)

Inserts an item into the collection at the specified index.

public void Insert(int index, TKey key, TValue value)

Parameters

index int

The zero-based index at which item should be inserted.

key TKey

The key to insert.

value TValue

The value to insert.

Exceptions

ArgumentNullException

key is null.

ArgumentException

An element with the same key already exists in the OrderedDict<TKey, TValue>.

ArgumentOutOfRangeException

index is less than 0 or greater than Count.

Remove(TKey)

Removes the value with the specified key from the OrderedDict<TKey, TValue>.

public bool Remove(TKey key)

Parameters

key TKey

The key of the element to remove.

Returns

bool

true if the element is successfully found and removed; otherwise, false.

Exceptions

ArgumentNullException

key is null.

Remove(TKey, out TValue)

Removes the value with the specified key from the OrderedDict<TKey, TValue> and copies the element to the value parameter.

public bool Remove(TKey key, out TValue value)

Parameters

key TKey

The key of the element to remove.

value TValue

The removed element.

Returns

bool

true if the element is successfully found and removed; otherwise, false.

Exceptions

ArgumentNullException

key is null.

RemoveAt(int)

Removes the key/value pair at the specified index.

public void RemoveAt(int index)

Parameters

index int

The zero-based index of the item to remove.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than or equal to Count.

SetAt(int, TKey, TValue)

Sets the key/value pair at the specified index.

public void SetAt(int index, TKey key, TValue value)

Parameters

index int

The zero-based index at which to set the key/value pair.

key TKey

The key to store at the specified index.

value TValue

The value to store at the specified index.

Exceptions

ArgumentNullException

key is null.

ArgumentException

An element with the same key already exists at an index different to index.

ArgumentOutOfRangeException

index is less than 0 or greater than or equal to Count.

SetAt(int, TValue)

Sets the value for the key at the specified index.

public void SetAt(int index, TValue value)

Parameters

index int

The zero-based index at which to set the value.

value TValue

The value to store at the specified index.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than or equal to Count.

ShallowClone()

Shallow copy preserving insertion order (Python copy.copy(dict)).

public OrderedDict<TKey, TValue> ShallowClone()

Returns

OrderedDict<TKey, TValue>

A new dictionary preserving insertion order and sharing the original key and value objects.

TrimExcess()

Sets the capacity of this dictionary to what it would be if it had been originally initialized with all its entries.

public void TrimExcess()

TrimExcess(int)

Sets the capacity of this dictionary to hold up a specified number of entries without resizing.

public void TrimExcess(int capacity)

Parameters

capacity int

The desired capacity to which to shrink the dictionary.

Exceptions

ArgumentOutOfRangeException

capacity is less than Count.

TryAdd(TKey, TValue)

Adds the specified key and value to the dictionary if the key doesn't already exist.

public bool TryAdd(TKey key, TValue value)

Parameters

key TKey

The key of the element to add.

value TValue

The value of the element to add. The value can be null for reference types.

Returns

bool

true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.

Exceptions

ArgumentNullException

key is null.

TryAdd(TKey, TValue, out int)

Adds the specified key and value to the dictionary if the key doesn't already exist.

public bool TryAdd(TKey key, TValue value, out int index)

Parameters

key TKey

The key of the element to add.

value TValue

The value of the element to add. The value can be null for reference types.

index int

The index of the added or existing key. This is always a valid index into the dictionary.

Returns

bool

true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.

Exceptions

ArgumentNullException

key is null.

TryGetValue(TKey, out TValue)

Gets the value associated with the specified key.

public bool TryGetValue(TKey key, out TValue value)

Parameters

key TKey

The key of the value to get.

value TValue

When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter.

Returns

bool

true if the OrderedDict<TKey, TValue> contains an element with the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

TryGetValue(TKey, out TValue, out int)

Gets the value associated with the specified key.

public bool TryGetValue(TKey key, out TValue value, out int index)

Parameters

key TKey

The key of the value to get.

value TValue

When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter.

index int

The index of key if found; otherwise, -1.

Returns

bool

true if the OrderedDict<TKey, TValue> contains an element with the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.