Map

The Map class is fundamental to the all map classes as it contains the backend code. The templated map classes just wrap this class to simplify the API. Map has minimal validation in the function calls to simplify the code and optimize performance. I also chose to keep the parameter validation as simple as possible because the templated map types enforce valid input through strong typed functions.

If you find that the templated maps do not suit your needs use this map class, but with care. Because the templated types use encapsulation to protect the underlying map and to symplify the API, this map class exposes all of its functions publically. That does not mean all the functions are meant to be used even in complex cases.

Therefore, I will decribe the meaningful API of Map. Note that many of these functions are wrapped by templated maps and those functions will be linked back here. In the following functions, many take a params object[] keys parameter. In each of these cases, keys.Length must be fewer than or equal to the depth of the map, default 1. See Depth.

Dictionary<> like API

public object Get(params object[] keys)

Returns the value specified by a unique set of keys.

public void Set(object value, params object[] keys)

Sets value specified by a unique set of keys.

public bool Remove(params object[] keys)

Removes the value, if it exists, specified by a unique set of keys. Returns true if the value was removed.

public bool ContainsKey(params object[] keys)

Returns true if the unique set of keys exists.

public void Clear()

Removes all keys and values.

public int Count

Returns the number of unique key sets.

public List<KeyValueSet> KeyValues

Returns a list of KeyValueSet, each of which represents a unique key and value in the map.

public List<object> Values

Returns a list of values, without the keys.

public List<List<object>> Keys

Returns all the unique key sets in the map.

New API

public KeyNotFoundBehavior KeyNotFoundBehavior

Returns or sets the behavior the map takes when Get() is called for a key that does not exist. The possible values are:

• ThrowKeyNotFoundException: (default) Throw a KeyNotFoundException

DefaultGeneration: Invoke a callback to generate a value and set it in the map.
DefaultValue: Return a default error value and do not set it in the map.

public object DefaultValue

When set, behavior is set to DefaultValue and this value is returned for failed Get() calls.

public Func<object[], object> DefaultGeneration

When set, behavior is set to DefaultGeneration, and this callback is invoked for failed Get() calls.

public int Depth

Defines the maximum number of keys the map holds per value. The default depth is 1, the same a Dictionary<>. A map depth can be changed, but the results are not defined. If you want to reuse the same map instance for multiple depths, it would be advisable to clear the map first.

public List<object> GetLayer(params object[] keys)

Returns the keys at the specified set of keys. Returns null if the key set is not found or if the key set identifies single value, and not a group. To get the top layer of keys call GetLayer with an empty array.

public Map GetMap(params object[] keys)

Returns a map wrapper of an internal dictionary specified by keys or null if none found.

public void SetMap(Map map, params object[] keys)

Sets the internal dictionary of map to a unique node specified by keys.