Map ¶The Map_K_V structure itself is defined in the templated module
collections.map(K,V). To initialize a Map_K_V, you need
to use a function from collections.hashmap or
collections.btreemap:
HashMap_K_V() ¶HashMap_K_V(V keyword nullValue, bool keyword isNullValue(V v) =
new bool(V v) {return v == nullValue; })These two functions, which create a hash map, must be accessed from the
collections.hashmap(K,V) templated module. The key type must
have a hash method, see Hash functions.
BTreeMap_K_V()BTreeMap_K_V(V keyword nullValue, bool keyword isNullValue(V v) =
new bool(V v) {return v == nullValue; })These two functions must be accessed from the collections.btreemap(K,V)
templated module. They create a b-tree map, which stores its keys in
sorted order. The key type must have a < operator.
Note: HashMap_K_V is an appropriate choice for most purposes.
If nullValue is not provided, looking up a missing key will throw an error.
The nullValue parameter gives the map something to return when
a nonexistent key is looked up. This is useful in scenarios where missing keys
are expected and should be handled gracefully.
The isNullValue parameter defaults to a function that checks whether
its argument is equal to nullValue via operator ==.
This is usually the desired behavior, but it is occasionally necessary to
override it;
for instance,
if you have overridden operator == assuming its parameters are not null,
then something like isNullValue=new bool(V v){return alias(v,null);}
might
be appropriate.
Both HashMap_K_V and BTreeMap_K_V can be implicitly cast
to Map_K_V. Even without being cast, the two types have
the same methods as Map_K_V.
Similarly, the nullValue and isNullValue optional
parameters behave the same way for both types. See The Map API.
In theory, adding, removing, or looking up an element should require,
on average, O(1) time for HashMap_K_V and
O(\log n) time for BTreeMap_K_V (where n represents
the number of elements in the container).
In practice, HashMap_K_V is faster than
BTreeMap_K_V by about a factor of 2, assuming no more than a
few million entries. (This is a very rough estimate
that depends on the key type K having cheap hash, equality, and
comparison functions.) The relative performance of these map implementations
could change in the future as the code is optimized.