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
dictionaryIDictionary<string, object>The entries to copy.
Exceptions
- ArgumentNullException
When
dictionaryis 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
dictionaryIDictionary<string, object>The entries to copy.
comparerIEqualityComparer<string>The key comparer; null means the default.
Exceptions
- ArgumentNullException
When
dictionaryis 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
keyValuePairsIEnumerable<KeyValuePair<string, object>>The pairs.
Exceptions
- ArgumentException
When two pairs share a key.
- NullReferenceException
When
keyValuePairsis null.
Dict(IEqualityComparer<string>)
An empty dictionary comparing keys with comparer.
public Dict(IEqualityComparer<string> comparer)
Parameters
comparerIEqualityComparer<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
capacityintThe initial capacity. Footgun:
new Dict(5)is this constructor, not one inline value.
Exceptions
- ArgumentOutOfRangeException
When
capacityis negative.
Dict(int, IEqualityComparer<string>)
An empty dictionary with an initial capacity and a key comparer.
public Dict(int capacity, IEqualityComparer<string> comparer)
Parameters
capacityintThe initial capacity.
comparerIEqualityComparer<string>The key comparer; null means the default.
Exceptions
- ArgumentOutOfRangeException
When
capacityis 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
Exceptions
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
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
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
inlinesitself is null.
Append(IDictionary)
Appends or sets given value to given key. returns self, not a copy.
public Dict Append(IDictionary dict)
Parameters
dictIDictionaryThe 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
Returns
- Dict
This dictionary, for chaining.
Exceptions
- ArgumentNullException
When
keyis 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:
AddRangetakes 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
keystringThe key.
Returns
- T
The value cast to
T. Footgun: a missing key returnsdefault(T)silently.
Type Parameters
Exceptions
- InvalidCastException
When the object in dictionary corresponding to key
keyis notT- ArgumentNullException
When
keyis null.
Get<T>(string, Func<T>)
Simple this[key] and cast or return default.
public T Get<T>(string key, Func<T> @default)
Parameters
keystringThe key.
defaultFunc<T>Called for the value to return when the key is missing; not called otherwise.
Returns
- T
The value cast to
T, or whatdefaultreturns.
Type Parameters
TThe type to cast to.
Exceptions
- InvalidCastException
When the object in dictionary corresponding to key
keyis notT- ArgumentNullException
When
keyis null.- NullReferenceException
When the key is missing and
defaultis null.
Get<T>(string, T)
Simple this[key] and cast or return default.
public T Get<T>(string key, T @default)
Parameters
keystringThe key.
defaultTReturned when the key is missing.
Returns
- T
The value cast to
T, ordefault.
Type Parameters
TThe type to cast to.
Exceptions
- InvalidCastException
When the object in dictionary corresponding to key
keyis notT- ArgumentNullException
When
keyis 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
rightIDictionaryThe dictionary to merge in.
preferenceMergePreferThe 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
rightobjectThe value to merge in.
preferenceMergePreferThe 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
dictIDictionaryThe 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>>)
Similar to RemoveAll(Predicate<T>).
public int RemoveWhere(Predicate<KeyValuePair<string, object>> comparer)
Parameters
comparerPredicate<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
compareris 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
settingsComparerFunc<KeyValuePair<string, object>, bool>The comparer that returns if this key should have it's value replaced.
valueFactoryFunc<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
settingsComparerorvalueFactoryis 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
comparerFunc<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
compareris null.
Update(Dict)
Updates/adds all values in this dictionary, based on dict.
public void Update(Dict dict)
Parameters
Exceptions
Update(IDictionary)
Updates/adds all values in this dictionary, based on dict.
public void Update(IDictionary dict)
Parameters
dictIDictionaryThe 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.