Module MMap

Removes all entries from the map.

Creates a new map with the same entries as the given map.

The copy is shallow: the new map is independent, so adding or removing entries in one does not affect the other, but the keys and values themselves are shared. Mutating a value reached through one map is visible through the other.

Example:

> inner = MList.fromList [1, 2]
> m = MMap.fromEntryList [("a", inner)]
> c = MMap.clone m
> MList.add inner 3
> MList.toList (fromJust (MMap.get c "a"))
[1, 2, 3]

Returns True if the map contains the given key.

Returns True if the map contains the given value.

Creates a new empty map.

Creates a new empty map with room for the given number of entries.

The entries of the map as a list of key-value pairs. Unlike the entrySet view, this is a snapshot, not a view; see keys.

A set view of the entries of the map. This is a live view, not a copy: changes to the map are reflected in the view, and removing entries from the view removes them from the map. Use entries when an independent snapshot is wanted.

The entries are opaque; read them with keyOf and valueOf.

Example:

> m = MMap.fromEntryList [("a", 1)]
> es = MMap.entrySet m
> MSet.toList (MSet.map (\e -> (MMap.keyOf e, MMap.valueOf e)) es)
[("a", 1)]
> MSet.clear es
> MMap.entries m
[]

Folds over all key-value pairs of the map starting with the given initial value.

Creates a new map from the given list of key-value pairs.

The value associated with the given key, or Nothing if the map contains no such key.

getOrCreate m f k returns the value associated with the key k. If the map contains no such key, f k is evaluated, associated with k and returned.

Note the argument order: the creating function sits between the map and the key. Note also that the created value is stored in the map, not just returned, so a later call with the same key returns the cached value without calling f again.

Example:

> m = MMap.fromEntryList [("a", 1)]
> MMap.getOrCreate m (\k -> length k) "hello"
5
> sort (MMap.entries m)
[("a", 1), ("hello", 5)]
> MMap.getOrCreate m (\k -> 999) "hello"
5

Returns True if the map contains no entries.

Calls the given function with all key-value pairs of the map.

Calls the given function with the key-value pairs of the map until it returns False. Returns False if the iteration was interrupted this way and True if the function accepted all entries.

The result therefore means "was not interrupted", not "found something": it is True exactly when the function accepted every entry, which for an empty map is vacuously the case.

Example:

> m = MMap.fromEntryList [("a", 1), ("b", 2)]
> MMap.iterB (\k v -> v < 10) m
True
> MMap.iterB (\k v -> v < 2) m
False

The key of the entry. Entries can only be obtained from entrySet, so this declaration is only usable together with it; see entrySet for an example.

A set view of the keys of the map. Obtaining the view reads nothing, which is why this is the only declaration in this module without <Proc>.

The view is live, not a copy: changes to the map are reflected in the view, and removing a key from the view removes the whole entry from the map. Use keys when an independent snapshot is wanted.

Example:

> m = MMap.fromEntryList [("a", 1), ("b", 2)]
> ks = MMap.keySet m
> MSet.remove ks "a"
True
> sort (MMap.entries m)
[("b", 2)]

The keys of the map as a list.

Unlike the keySet view, this is a snapshot taken at the time of the call: later changes to the map do not show up in the returned list. The same holds for values and entries.

The map is hash-based, so the order of the returned list is not a contract. sort the result if a stable order is needed.

Example:

> m = MMap.fromEntryList [("a", 1), ("b", 2)]
> ks = MMap.keys m
> MSet.remove (MMap.keySet m) "a"
True
> sort ks
["a", "b"]
> sort (MMap.entries m)
[("b", 2)]

Creates a new map with the same keys as the given map and the values mapped with the given function.

Only the values are mapped; the keys are carried over unchanged. The result is a new mutable map, independent of the original.

Example:

> m = MMap.fromEntryList [("a", 1), ("b", 2)]
> d = MMap.map (\v -> v * 10) m
> sort (MMap.entries d)
[("a", 10), ("b", 20)]
> ignore (MMap.put d "c" 30)
> sort (MMap.entries m)
[("a", 1), ("b", 2)]

put m k v associates the value v with the key k and returns the value previously associated with k, or Nothing if there was none.

The return value is rarely wanted, so call sites almost always discard it with Prelude.ignore.

Example:

> m = MMap.fromEntryList [("a", 1)]
> MMap.put m "a" 2
Just 1
> MMap.put m "b" 3
Nothing
> ignore (MMap.put m "c" 4)
> sort (MMap.entries m)
[("a", 2), ("b", 3), ("c", 4)]

putM merge m k v associates v with the key k. If the map already associates a value v2 with k, the value merge v v2 is associated instead.

Mind the argument order of merge: it receives the new value first and the old one second, which is the opposite of what a name like "combine old with new" would suggest. The order only matters for a non-commutative merge, and then it matters a lot.

Example:

> m = MMap.fromEntryList [("a", 10)]
> MMap.putM (\new old -> new - old) m "a" 3
> MMap.entries m
[("a", -7)]
> MMap.putM (\new old -> new - old) m "b" 5
> sort (MMap.entries m)
[("a", -7), ("b", 5)]

Removes the given key from the map and returns the value that was associated with it, or Nothing if the map contained no such key. Like put, the result is usually discarded with Prelude.ignore.

Example:

> m = MMap.fromEntryList [("a", 1)]
> MMap.remove m "a"
Just 1
> MMap.remove m "a"
Nothing
> MMap.entries m
[]

The number of entries in the map.

Like get, but returns the value directly instead of wrapping it in Maybe.

If the map contains no such key, the result is a raw Java null. SCL has no representation for that, so nothing fails at the call site: the null escapes into the program as if it were a value of type b and typically surfaces much later as a NullPointerException in unrelated code. Only use this when the key is known to be present; otherwise use get.

The value of the entry. Entries can only be obtained from entrySet, so this declaration is only usable together with it; see entrySet for an example.

The values of the map as a list. A snapshot, not a view; see keys.