Map¶
Usage
use Map;
or
import Map;
This module contains the implementation of the map type which is a container that stores key-value associations.
Maps are not parallel safe by default, but can be made parallel safe by setting the param formal parSafe to true in any map constructor. When constructed from another map, the new map will inherit the parallel safety mode of its originating map.
-
record
map
¶ -
type
keyType
¶ Type of map keys.
-
type
valType
¶ Type of map values.
-
param
parSafe
= false¶ If true, this map will perform parallel safe operations.
-
proc
init
(type keyType, type valType, param parSafe = false)¶ Initializes an empty map containing keys and values of given types.
Arguments: - keyType – The type of the keys of this map.
- valType – The type of the values of this map.
- parSafe – If true, this map will use parallel safe operations.
-
proc
init
(type keyType, type valType, param parSafe = false)
-
proc
init=
(other: map(?kt, ?vt, ?ps))¶ Initializes a map containing elements that are copy initialized from the elements contained in another map.
Arguments: - other : map – The map to initialize from.
- parSafe : bool – If true, this map will use parallel safe operations.
-
proc
clear
()¶ Clears the contents of this map.
Warning
Clearing the contents of this map will invalidate all existing references to the elements contained in this map.
-
proc
size
¶ The current number of keys contained in this map.
-
proc
isEmpty
(): bool¶ Returns true if this map contains zero keys.
Returns: true if this map is empty. Return type: bool
-
proc
contains
(const k: keyType): bool¶ Returns true if the given key is a member of this map, and false otherwise.
Arguments: k : keyType – The key to test for membership. Returns: Whether or not the given key is a member of this map. Return type: bool
-
proc
update
(const ref m: map(keyType, valType, parSafe))¶ Updates this map with the contents of the other, overwriting the values for already-existing keys.
Arguments: m : map(keyType, valType) – The other map
-
proc
this
(k: keyType) ref¶ Get the value mapped to the given key, or add the mapping if key does not exist.
Arguments: k : keyType – The key to access Returns: Reference to the value mapped to the given key.
-
proc
getBorrowed
(k: keyType)¶ Get a borrowed reference to the element at position k.
-
proc
getReference
(k: keyType) ref¶ Get a reference to the element at position k. This method is not available for non-nilable types.
-
proc
getValue
(k: keyType)¶
-
proc
getAndRemove
(k: keyType)¶ Remove the element at position k from the map and return its value
-
iter
these
() const ref¶ Iterates over the keys of this map. This is a shortcut for
keys
.Yields: A reference to one of the keys contained in this map.
-
iter
keys
() const ref¶ Iterates over the keys of this map.
Yields: A reference to one of the keys contained in this map.
-
iter
items
() const ref¶ Iterates over the key-value pairs of this map.
Yields: A tuple of references to one of the key-value pairs contained in this map.
-
iter
values
() ref¶ Iterates over the values of this map.
Yields: A reference to one of the values contained in this map.
-
proc
readWriteThis
(ch: channel) throws¶ Writes the contents of this map to a channel. The format looks like:
{k1: v1, k2: v2, .... , kn: vn}
Arguments: ch – A channel to write to.
-
proc
add
(in k: keyType, in v: valType): bool¶ - Adds a key-value pair to the map. Method returns false if the key already exists in the map.
Arguments: - k : valueType – The key to add to the map
- v – The value that maps to
k
Returns: true if k was not in the map and added with value v. false otherwise.
Return type: bool
-
proc
set
(k: keyType, in v: valType): bool¶ - Sets the value associated with a key. Method returns false if the key does not exist in the map.
Arguments: - k : valueType – The key whose value needs to change
- v – The desired value to the key
k
Returns: true if k was in the map and its value is updated with v. false otherwise.
Return type: bool
-
proc
addOrSet
(in k: keyType, in v: valType)¶ If the map doesn’t contain a value at position k add one and set it to v. If the map already contains a value at position k, update it to the value v.
-
proc
remove
(k: keyType): bool¶ - Removes a key-value pair from the map, with the given key.
Arguments: k : keyType – The key to remove from the map Returns: false if k was not in the map. true if it was and removed. Return type: bool
-
proc
toArray
(): [] (keyType, valType)¶ Returns a new 0-based array containing a copy of key-value pairs as tuples.
Returns: A new DefaultRectangular array. Return type: [] (keyType, valType)
-
proc
keysToArray
(): [] keyType¶ Returns a new 0-based array containing a copy of keys. Array is not guaranteed to be in any particular order.
Returns: A new DefaultRectangular array. Return type: [] keyType
-
proc
valuesToArray
(): [] valType¶ Returns a new 0-based array containing a copy of values. Array is not guaranteed to be in any particular order.
Returns: A new DefaultRectangular array. Return type: [] valType
-
type
-
proc
=
(ref lhs: map(?kt, ?vt, ?ps), const ref rhs: map(kt, vt, ps))¶ Replace the content of this map with the other’s.
Warning
This will invalidate any references to elements previously contained in lhs.
Arguments: - lhs – The map to assign to.
- rhs – The map to assign from.
-
proc
==
(const ref a: map(?kt, ?vt, ?ps), const ref b: map(kt, vt, ps)): bool¶ Returns true if the contents of two maps are the same.
Arguments: - a : map – A map to compare.
- b : map (with same keyType and valType) – A map to compare.
Returns: true if the contents of two maps are equal.
Return type: bool
-
proc
!=
(const ref a: map(?kt, ?vt, ?ps), const ref b: map(kt, vt, ps)): bool¶ Returns true if the contents of two maps are not the same.
Arguments: - a : map – A map to compare.
- b : map (with same keyType and valType) – A map to compare.
Returns: true if the contents of two maps are not equal.
Return type: bool
-
proc
+
(a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))¶ Returns a new map containing the keys and values in either a or b.
-
proc
+=
(ref a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))¶ Sets the left-hand side map to contain the keys and values in either a or b.
-
proc |(a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Returns a new map containing the keys and values in either a or b.
-
proc |=(ref a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Sets the left-hand side map to contain the keys and values in either a or b.
-
proc &(a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Returns a new map containing the keys that are in both a and b.
-
proc &=(ref a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Sets the left-hand side map to contain the keys that are in both a and b.
-
proc
-
(a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))¶ Returns a new map containing the keys that are only in a, but not b.
-
proc
-=
(ref a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))¶ Sets the left-hand side map to contain the keys that are in the left-hand map, but not the right-hand map.
-
proc ^(a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Returns a new map containing the keys that are in either a or b, but not both.
-
proc ^=(ref a: map(?keyType, ?valueType, ?parSafe), b: map(keyType, valueType, parSafe))
Sets the left-hand side map to contain the keys that are in either the left-hand map or the right-hand map, but not both.