Map¶

Usage

use Map;

or

import Map;

Chapel’s standard ‘map’ type for key-value storage.

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.

const resizeThreshold = defaultHashTableResizeThreshold¶: Fractional value that specifies how full this map can be before requesting additional memory. The default value of 0.5 means that the map will not resize until the map is more than 50% full. The acceptable values for this argument are between 0 and 1, exclusive, meaning (0,1). This is useful when you would like to reduce memory impact or potentially speed up how fast the map finds a slot. To override the default value of 0.5, the defaultHashTableResizeThreshold config flag can be set at runtime. Note that this default affects all hash-based data structures, including associative domains and sets.

proc init(type keyType, type valType, resizeThreshold = defaultHashTableResizeThreshold, initialCapacity = 16)¶

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.
resizeThreshold – Fractional value that specifies how full this map can be before requesting additional memory.
initialCapacity – Integer value that specifies starting map size. The map can hold at least this many values before attempting to resize.

proc init(type keyType, type valType, param parSafe, resizeThreshold = defaultHashTableResizeThreshold, initialCapacity = 16)

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.
resizeThreshold – Fractional value that specifies how full this map can be before requesting additional memory.
initialCapacity – Integer value that specifies starting map size. The map can hold at least this many values before attempting to resize.

Warning

‘Map.parSafe’ is unstable

proc init(type keyType, type valType, resizeThreshold = defaultHashTableResizeThreshold, initialCapacity = 16)

proc init(type keyType, type valType, param parSafe, resizeThreshold = defaultHashTableResizeThreshold, initialCapacity = 16): Warning

‘Map.parSafe’ is unstable

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 extend(m: map(keyType, valType, parSafe))¶

Extends this map with the contents of the other, overwriting the values for already-existing keys.

Arguments: m : map(keyType, valType) – The other map

proc update(const ref k: keyType, updater) throws¶

Update a value in this map in a parallel safe manner via an updater object.

The updater object passed to the update() method must define a this() method that takes two arguments: the first has this map’s keyType, and the second has this map’s valType.

The updater object’s this() method must return some sort of value. Updater objects that do not need to return anything may return none.

If the updater object’s this() method throws, the thrown error will be propagated out of update().

Arguments

k : keyType – The key to update
updater – A class or record used to update the value at i

Throws

KeyNotFoundError – if k not in map

Returns

What the updater returns

proc ref this(k: keyType) ref throws

If the key exists in the map, get a reference to the value mapped to the given key. If the key does not exist in the map, the value type is default initializable, and this proc is called in an attempt to modify the map, then the mapping is added and a reference to that value is returned. If the key does not exist in the map and either the value type is not default initializable or this proc is called without attempting to modify the map, then an error will be thrown.

Arguments: k : keyType – The key to access
Throws: KeyNotFoundError – if k not in map, valType is not default initializable, and proc is called in an attempt to modify the map.
Returns: Reference to the value mapped to the given key.

proc ref this(k: keyType) ref throws

proc getBorrowed(k: keyType)¶: Get a borrowed reference to the element at position k.

Warning

‘Map.getBorrowed’ is deprecated. Please rely on ‘[]’ accessors instead.

proc getReference(k: keyType) ref¶: Get a reference to the element at position k. This method is not available for maps initialized with parSafe=true.

Warning

‘Map.getReference’ is deprecated. Please rely on ‘[]’ accessors instead.

proc getValue(k: keyType) throws¶

Get a copy of the element stored at position k.

Arguments: k – The key to lookup in the map
Throws: KeyNotFoundError – if k not in map
Returns: A copy of the value at position k

Warning

‘Map.getValue’ is deprecated. Please rely on ‘[]’ accessors instead.

proc get(k: keyType, const sentinel: valType)¶

Get a copy of the element stored at position k or a sentinel: value if an element at position k does not exist.

Arguments

k – The key to lookup in the map
sentinel – The value to return if the map does not contain an entry at position k

Returns

A copy of the value at position k or a sentinel value if the map does not have an entry at position k

proc getValue(k: keyType, const sentinel: valType): Warning

‘Map.getValue’ is deprecated. Please use ‘Map.get’ instead.

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.

Warning

‘Map.these’ is deprecated. Consider ‘Map.keys’ to iterate over keys or ‘Map.values’ to iterate over values.

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()¶

Iterates over the key-value pairs of this map.

Yields: A tuple whose elements are a copy of one of the key-value pairs contained in this map.

Warning

‘Map.items’ is deprecated. Consider ‘Map.keys’ to iterate over keys or ‘Map.values’ to iterate over values.

iter values() ref¶

Iterates over the values of this map.

Yields: A reference to one of the values contained in this map.

proc readThis(ch: fileReader) throws¶

Reads the contents of this map from a channel. The format looks like:

{k1: v1, k2: v2, .... , kn: vn}

Arguments: ch – A channel to read from.

proc writeThis(ch: fileWriter) 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 : keyType – The key to add to the map
v : valueType – 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¶: Warning

‘Map.set’ is deprecated. Please use ‘Map.replace’ instead.

proc replace(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 – 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

operator map. = (ref lhs: map(?kt, ?vt, ?), const ref rhs: map(kt, vt, ?))

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.

operator map.==(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

operator map.!=(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

class KeyNotFoundError: Error¶

A KeyNotFoundError is thrown at runtime if an attempt is made to access a map value at a given key that is not in the current state of the map. An example of this is calling map.getValue().

proc init()¶

proc init(k: string)