Table of Contents

Class Dict

Namespace
Gym.Collections
Assembly
Gym.dll

Alias to Dictionary<TKey, TValue> of string to object with ability to construct inline, as dynamic, merging and cloning: 0.2's info and metadata type, which Gym.Legacy still returns (Step.Information, ILegacyEnv.Metadata, VecEnv.Metadata).

[Serializable]
[Obsolete("Dict is the legacy API's info and metadata type: use Gym.Envs.Info for infos and Gym.Envs.Metadata for metadata. Removed in 2.0 with Gym.Legacy.")]
public class Dict : Dictionary<string, object>, IDictionary<string, object>, ICollection<KeyValuePair<string, object>>, IReadOnlyDictionary<string, object>, IReadOnlyCollection<KeyValuePair<string, object>>, IEnumerable<KeyValuePair<string, object>>, IDictionary, ICollection, IEnumerable, IDeserializationCallback, ISerializable, IMergable<IDictionary>, IMergable<IList>, IMergable<IMergable>, IMergable
Inheritance
Dict
Implements
Inherited Members
Extension Methods

Remarks

Obsolete (DR-56) and removed in 2.0 with Gym.Legacy. 1.0's envs use Info for infos (Python's dict: insertion order kept, Get(key, default), Update, Copy/DeepCopy, Pop) and Metadata for metadata. Unlike Info, enumeration order is Dictionary<TKey, TValue>'s, which removals can reorder. It shares its name with the Dict space (Gym.Spaces.Dict): a file importing both namespaces must alias one (CS0104).

Constructors

Dict()

An empty dictionary with the default (ordinal) key comparer.

public Dict()

Dict(IDictionary<string, object>)

A shallow copy of dictionary's entries (the values are shared, not copied).

public Dict(IDictionary<string, object> dictionary)

Parameters

dictionary IDictionary<string, object>

The entries to copy.

Exceptions

ArgumentNullException

When dictionary is null.

Dict(IDictionary<string, object>, IEqualityComparer<string>)

A shallow copy of dictionary's entries, comparing keys with comparer.

public Dict(IDictionary<string, object> dictionary, IEqualityComparer<string> comparer)

Parameters

dictionary IDictionary<string, object>

The entries to copy.

comparer IEqualityComparer<string>

The key comparer; null means the default.

Exceptions

ArgumentNullException

When dictionary is null.

ArgumentException

When two keys are equal under comparer.

Dict(IEnumerable<KeyValuePair<string, object>>)

A dictionary of the given pairs, in order (values shared, not copied).

public Dict(IEnumerable<KeyValuePair<string, object>> keyValuePairs)

Parameters

keyValuePairs IEnumerable<KeyValuePair<string, object>>

The pairs.

Exceptions

ArgumentException

When two pairs share a key.

NullReferenceException

When keyValuePairs is null.

Dict(IEqualityComparer<string>)

An empty dictionary comparing keys with comparer.

public Dict(IEqualityComparer<string> comparer)

Parameters

comparer IEqualityComparer<string>

The key comparer (for example OrdinalIgnoreCase); null means the default.

Dict(int)

An empty dictionary with room for capacity entries before it grows.

public Dict(int capacity)

Parameters

capacity int

The initial capacity. Footgun: new Dict(5) is this constructor, not one inline value.

Exceptions

ArgumentOutOfRangeException

When capacity is negative.

Dict(int, IEqualityComparer<string>)

An empty dictionary with an initial capacity and a key comparer.

public Dict(int capacity, IEqualityComparer<string> comparer)

Parameters

capacity int

The initial capacity.

comparer IEqualityComparer<string>

The key comparer; null means the default.

Exceptions

ArgumentOutOfRangeException

When capacity is negative.

Dict(params object[])

A dictionary of inline key-value pairs: new Dict("render.modes", modes, "video.frames_per_second", 50). A later pair with the same key overwrites the earlier.

public Dict(params object[] inlines)

Parameters

inlines object[]

Keys and values, alternating; each key must be a string.

Exceptions

DictInlineInitializationException

When the count is odd, or a key is null or not a string.

Properties

Empty

Returns a new empty Dict with 0 capacity (not fixed, meaning you can add items to it).

public static Dict Empty { get; }

Property Value

Dict

Remarks

A new dictionary on every read, not a shared instance, so mutating it is safe.

Methods

AddInline(params object[])

Adds or overwrites inline props, for example ("A", 1) will will do dictionary["A"] = 1;
But ("A", 1, "B") will throw because no value is assigned to "B" (No even arguments passed).

public void AddInline(params object[] inlines)

Parameters

inlines object[]

Keys and values, alternating; each key must be exactly a string.

Exceptions

DictInlineInitializationException

When the count is odd (checked first, so nothing is set), or a key is null or not a string (the pairs before it are set).

NullReferenceException

When inlines itself is null.

Append(IDictionary)

Appends or sets given value to given key. returns self, not a copy.

public Dict Append(IDictionary dict)

Parameters

dict IDictionary

The entries to set; despite the name, existing keys are overwritten (as Update(IDictionary)).

Returns

Dict

This dictionary, for chaining.

Exceptions

NullReferenceException

When an entry's key is null.

Append(string, object)

Appends or sets given value to given key. returns self, not a copy.

public Dict Append(string key, object val)

Parameters

key string

The key.

val object

The value, stored as given.

Returns

Dict

This dictionary, for chaining.

Exceptions

ArgumentNullException

When key is null.

AsDynamic()

Returns this wrapped in private class, allowing to class AddRange, Set, Update in a dynamic manner like python: named arguments become keys, and a dynamic member read finds the dictionary's keys.

public dynamic AsDynamic()

Returns

dynamic

A dynamic view over this dictionary (writes go to it), convertible back to Dict. Footguns: AddRange takes named arguments only, since a positional one shifts the names onto the wrong values; and the view resolves reflected members on its own type, not the dictionary's, so read the dictionary's own properties (Count, Keys) on the Dict itself.

Examples

Dict d = new Dict().AsDynamic().AddRange(x: 1, y: 2);

Clone()

Creates a copy of current Dict.

public Dict Clone()

Returns

Dict

A new copy of this dict, doesn't clone the contents, just references to them.

Get<T>(string)

Simple this[key] and cast.

public T Get<T>(string key)

Parameters

key string

The key.

Returns

T

The value cast to T. Footgun: a missing key returns default(T) silently.

Type Parameters

T

The type to cast to; a boxed value casts only to its exact type (an int stored is not a long).

Exceptions

InvalidCastException

When the object in dictionary corresponding to key key is not T

ArgumentNullException

When key is null.

Get<T>(string, Func<T>)

Simple this[key] and cast or return default.

public T Get<T>(string key, Func<T> @default)

Parameters

key string

The key.

default Func<T>

Called for the value to return when the key is missing; not called otherwise.

Returns

T

The value cast to T, or what default returns.

Type Parameters

T

The type to cast to.

Exceptions

InvalidCastException

When the object in dictionary corresponding to key key is not T

ArgumentNullException

When key is null.

NullReferenceException

When the key is missing and default is null.

Get<T>(string, T)

Simple this[key] and cast or return default.

public T Get<T>(string key, T @default)

Parameters

key string

The key.

default T

Returned when the key is missing.

Returns

T

The value cast to T, or default.

Type Parameters

T

The type to cast to.

Exceptions

InvalidCastException

When the object in dictionary corresponding to key key is not T

ArgumentNullException

When key is null.

Merge(IDictionary, MergePrefer)

Deep-merges right into this dictionary with Merger: nested dictionaries merged, lists appended, new values copied in, and preference settling two plain values.

public void Merge(IDictionary right, MergePrefer preference)

Parameters

right IDictionary

The dictionary to merge in.

preference MergePrefer

The side that wins when two values cannot be merged.

Exceptions

DictMergingException

When one key's merge fails; the keys before it stay merged.

Merge(object, MergePrefer)

Deep-merges right into this dictionary: a dictionary, another IMergable or a sequence of string-keyed pairs. Footgun: any other value merges nothing, silently.

public void Merge(object right, MergePrefer preference)

Parameters

right object

The value to merge in.

preference MergePrefer

The side that wins when two values cannot be merged.

Exceptions

DictMergingException

When one key's merge fails; the keys before it stay merged.

Override(IDictionary)

Sets every entry of dict, overwriting existing keys: the same as Append(IDictionary).

public Dict Override(IDictionary dict)

Parameters

dict IDictionary

The entries to set; null sets nothing.

Returns

Dict

This dictionary, for chaining.

Exceptions

NullReferenceException

When an entry's key is null.

RemoveWhere(Predicate<KeyValuePair<string, object>>)

public int RemoveWhere(Predicate<KeyValuePair<string, object>> comparer)

Parameters

comparer Predicate<KeyValuePair<string, object>>

The comparer that returns true when to remove and false to keep.

Returns

int

The amount of matching predictions and successful removals

Exceptions

NullReferenceException

When comparer is null and the dictionary is not empty.

SetWhere(Func<KeyValuePair<string, object>, bool>, Func<KeyValuePair<string, object>, object>)

Updates properties that return (true, ...).

public int SetWhere(Func<KeyValuePair<string, object>, bool> settingsComparer, Func<KeyValuePair<string, object>, object> valueFactory)

Parameters

settingsComparer Func<KeyValuePair<string, object>, bool>

The comparer that returns if this key should have it's value replaced.

valueFactory Func<KeyValuePair<string, object>, object>

Called for each selected entry, after all entries were tested, for its new value.

Returns

int

The amount of matching predictions and successful updates

Exceptions

ArgumentNullException

When settingsComparer or valueFactory is null.

SetWhere(Func<KeyValuePair<string, object>, (bool Set, object Value)>)

Updates properties that return (true, ...).

public int SetWhere(Func<KeyValuePair<string, object>, (bool Set, object Value)> comparer)

Parameters

comparer Func<KeyValuePair<string, object>, (bool Set, object Value)>

The comparer that returns (bool Set, object Value).

Returns

int

The amount of matching predictions and successful updates

Exceptions

ArgumentNullException

When comparer is null.

Update(Dict)

Updates/adds all values in this dictionary, based on dict.

public void Update(Dict dict)

Parameters

dict Dict

The entries to set, overwriting existing keys; null sets nothing.

Exceptions

NullReferenceException

When an entry's key is null (a Dict cannot hold one).

Update(IDictionary)

Updates/adds all values in this dictionary, based on dict.

public void Update(IDictionary dict)

Parameters

dict IDictionary

The entries to set, overwriting existing keys; a key that is not a string is stored under its ToString(). null sets nothing.

Exceptions

NullReferenceException

When an entry's key is null; the entries before it are already set.