.. default-domain:: chpl .. module:: SortedMap :synopsis: Provides the 'sortedMap' type for storing sorted key-value associations. SortedMap ========= **Usage** .. code-block:: chapel use SortedMap; or .. code-block:: chapel import SortedMap; Provides the 'sortedMap' type for storing sorted key-value associations. sortedMaps are not parallel safe by default, but can be made parallel safe by setting the param formal `parSafe` to true in any sortedMap constructor. When constructed from another sortedMap, the new sortedMap will inherit the parallel safety mode of its originating sortedMap. SortedSet supports searching for a certain key, insertion and deletion in O(logN). .. record:: sortedMap : writeSerializable .. attribute:: type keyType Type of sortedMap keys. .. attribute:: type valType Type of sortedMap values. .. attribute:: param parSafe = false If `true`, this sortedMap will perform parallel safe operations. .. attribute:: var comparator: record = defaultComparator The comparator used to compare keys .. method:: proc init(type keyType, type valType, param parSafe = false, comparator: record = defaultComparator) Initializes an empty sortedMap containing keys and values of given types. :arg keyType: The type of the keys of this sortedMap. :arg valType: The type of the values of this sortedMap. :arg parSafe: If `true`, this sortedMap will use parallel safe operations. :type parSafe: bool :arg comparator: The comparator used to compare keys. .. method:: proc init=(const ref other: sortedMap(?kt, ?vt)) Initialize this sortedMap with a copy of each of the elements contained in the sortedMap `other`. This sortedMap will inherit the `parSafe` value of the sortedMap `other`. :arg other: An sortedMap to initialize this sortedMap with. .. method:: proc ref clear() Clears the contents of this sortedMap. .. warning:: Clearing the contents of this sortedMap will invalidate all existing references to the elements contained in this sortedMap. .. method:: proc size The current number of keys contained in this sortedMap. .. method:: proc isEmpty(): bool Returns `true` if this sortedMap contains zero keys. :returns: `true` if this sortedMap is empty. :rtype: `bool` .. method:: proc contains(const k: keyType): bool Returns `true` if the given key is a member of this sortedMap, and `false` otherwise. :arg k: The key to test for membership. :type k: keyType :returns: Whether or not the given key is a member of this sortedMap. :rtype: `bool` .. method:: proc ref update(other: sortedMap(keyType, valType, ?p)) Updates this sortedMap with the contents of the other, overwriting the values for already-existing keys. :arg other: The other sortedMap .. method:: proc ref this(k: keyType) ref where isDefaultInitializable(valType) Get the value mapped to the given key, or add the mapping if key does not exist. :arg k: The key to access :type k: keyType :returns: Reference to the value mapped to the given key. .. method:: proc ref getBorrowed(k: keyType) where isClass(valType) Get a borrowed reference to the element at position `k`. .. method:: proc ref getReference(k: keyType) ref where !isNonNilableClass(valType) Get a reference to the element at position `k`. This method is not available for non-nilable types. .. method:: proc getValue(k: keyType) Get a copy of the element stored at position `k`. This method is only available when a sortedMap's `valType` is a non-nilable class. .. method:: proc ref getAndRemove(k: keyType) Remove the element at position `k` from the sortedMap and return its value .. itermethod:: iter these() const ref Iterates over the keys of this sortedMap. This is a shortcut for :iter:`keys`. :yields: A reference to one of the keys contained in this sortedMap. .. itermethod:: iter keys() const ref Iterates over the keys of this sortedMap. :yields: A reference to one of the keys contained in this sortedMap. .. itermethod:: iter items() Iterates over the key-value pairs of this sortedMap. :yields: A tuple whose elements are a copy of one of the key-value pairs contained in this map. .. itermethod:: iter values() ref Iterates over the values of this sortedMap. :yields: A reference to one of the values contained in this sortedMap. .. method:: proc ref add(in k: keyType, in v: valType): bool Adds a key-value pair to the sortedMap. Method returns `false` if the key already exists in the sortedMap. :arg k: The key to add to the sortedMap :type k: keyType :arg v: The value that maps to ``k`` :type v: valueType :returns: `true` if `k` was not in the sortedMap and added with value `v`. `false` otherwise. :rtype: bool .. method:: proc ref 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 sortedMap. :arg k: The key whose value needs to change :type k: keyType :arg v: The desired value to the key ``k`` :type v: valueType :returns: `true` if `k` was in the sortedMap and its value is updated with `v`. `false` otherwise. :rtype: bool .. method:: proc ref addOrReplace(in k: keyType, in v: valType) If the sortedMap doesn't contain a value at position `k` add one and set it to `v`. If the sortedMap already contains a value at position `k`, update it to the value `v`. .. method:: proc ref remove(k: keyType): bool Removes a key-value pair from the sortedMap, with the given key. :arg k: The key to remove from the sortedMap :returns: `false` if `k` was not in the sortedMap. `true` if it was and removed. :rtype: bool .. method:: proc toArray(): [] (keyType, valType) Returns a new 0-based array containing a copy of key-value pairs as tuples. :return: A new DefaultRectangular array. :rtype: [] (keyType, valType) .. method:: proc keysToArray(): [] keyType Returns a new 0-based array containing a copy of keys. Array is sorted using the comparator. :return: A new DefaultRectangular array. :rtype: [] keyType .. method:: proc valuesToArray(): [] valType Returns a new 0-based array containing a copy of values. Array is not guaranteed to be in any particular order. :return: A new DefaultRectangular array. :rtype: [] valType .. method:: operator sortedMap. = (ref lhs: sortedMap(?kt, ?vt, ?ps), const ref rhs: sortedMap(kt, vt, ps)) Replace the content of this sortedMap with the other's. .. warning:: This will invalidate any references to elements previously contained in `lhs`. :arg lhs: The sortedMap to assign to. :arg rhs: The sortedMap to assign from. .. method:: operator sortedMap.==(const ref a: sortedMap(?kt, ?vt, ?ps), const ref b: sortedMap(kt, vt, ps)): bool Returns `true` if the contents of two sortedMaps are the same. :arg a: A sortedMap to compare. :arg b: A sortedMap to compare. :return: `true` if the contents of two sortedMaps are equal. :rtype: `bool` .. method:: operator sortedMap.!=(const ref a: sortedMap(?kt, ?vt, ?ps), const ref b: sortedMap(kt, vt, ps)): bool Returns `true` if the contents of two sortedMaps are not the same. :arg a: A sortedMap to compare. :arg b: A sortedMap to compare. :return: `true` if the contents of two sortedMaps are not equal. :rtype: `bool` .. method:: operator sortedMap.+(a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Returns a new sortedMap containing the keys and values in either a or b. .. method:: operator sortedMap.+=(ref a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Sets the left-hand side sortedMap to contain the keys and values in either a or b. .. method:: operator sortedMap.|(a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Returns a new sortedMap containing the keys and values in either a or b. .. method:: operator sortedMap.|=(ref a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Sets the left-hand side map to contain the keys and values in either a or b. .. method:: operator sortedMap.&(a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Returns a new sortedMap containing the keys that are in both a and b. .. method:: operator sortedMap.&=(ref a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Sets the left-hand side sortedMap to contain the keys that are in both a and b. .. warning:: This will invalidate any references to elements previously contained in `lhs`. .. method:: operator sortedMap.-(a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Returns a new sortedMap containing the keys that are only in a, but not b. .. method:: operator sortedMap.-=(ref a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Sets the left-hand side sortedMap to contain the keys that are in the left-hand sortedMap, but not the right-hand sortedMap. .. method:: operator sortedMap.^(a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Returns a new sortedMap containing the keys that are in either a or b, but not both. .. method:: operator sortedMap.^=(ref a: sortedMap(?keyType, ?valueType, ?parSafe), b: sortedMap(keyType, valueType, parSafe)) Sets the left-hand side sortedMap to contain the keys that are in either the left-hand sortedMap or the right-hand sortedMap, but not both.