Portability | portable |
---|---|

Stability | provisional |

Maintainer | johan.tibell@gmail.com |

A map from *hashable* keys to values. A map cannot contain
duplicate keys; each key can map to at most one value. A `HashMap`

makes no guarantees as to the order of its elements.

This map is strict in both the keys and the values; keys and values
are evaluated to *weak head normal form* before they are added to
the map. Exception: the provided instances are the same as for the
lazy version of this module.

The implementation is based on *big-endian patricia trees*, keyed
by a hash of the original key. A `HashMap`

is often faster than
other tree-based maps, especially when key comparison is expensive,
as in the case of strings.

Many operations have a worst-case complexity of *O(min(n,W))*.
This means that the operation can become linear in the number of
elements with a maximum of *W* -- the number of bits in an `Int`

(32 or 64).

- data HashMap k v
- empty :: HashMap k v
- singleton :: Hashable k => k -> v -> HashMap k v
- null :: HashMap k v -> Bool
- size :: HashMap k v -> Int
- lookup :: (Eq k, Hashable k) => k -> HashMap k v -> Maybe v
- lookupDefault :: (Eq k, Hashable k) => v -> k -> HashMap k v -> v
- insert :: (Eq k, Hashable k) => k -> v -> HashMap k v -> HashMap k v
- delete :: (Eq k, Hashable k) => k -> HashMap k v -> HashMap k v
- insertWith :: (Eq k, Hashable k) => (v -> v -> v) -> k -> v -> HashMap k v -> HashMap k v
- adjust :: (Eq k, Hashable k) => (v -> v) -> k -> HashMap k v -> HashMap k v
- union :: Eq k => HashMap k v -> HashMap k v -> HashMap k v
- unionWith :: Eq k => (v -> v -> v) -> HashMap k v -> HashMap k v -> HashMap k v
- map :: (v1 -> v2) -> HashMap k v1 -> HashMap k v2
- traverseWithKey :: Applicative f => (k -> v1 -> f v2) -> HashMap k v1 -> f (HashMap k v2)
- difference :: (Eq k, Hashable k) => HashMap k v -> HashMap k w -> HashMap k v
- intersection :: (Eq k, Hashable k) => HashMap k v -> HashMap k w -> HashMap k v
- foldl' :: (a -> v -> a) -> a -> HashMap k v -> a
- foldlWithKey' :: (a -> k -> v -> a) -> a -> HashMap k v -> a
- foldr :: (v -> a -> a) -> a -> HashMap k v -> a
- foldrWithKey :: (k -> v -> a -> a) -> a -> HashMap k v -> a
- filter :: (v -> Bool) -> HashMap k v -> HashMap k v
- filterWithKey :: (k -> v -> Bool) -> HashMap k v -> HashMap k v
- elems :: HashMap k v -> [v]
- keys :: HashMap k v -> [k]
- toList :: HashMap k v -> [(k, v)]
- fromList :: (Eq k, Hashable k) => [(k, v)] -> HashMap k v
- fromListWith :: (Eq k, Hashable k) => (v -> v -> v) -> [(k, v)] -> HashMap k v

# Documentation

A map from keys to values. A map cannot contain duplicate keys; each key can map to at most one value.

# Construction

# Basic interface

lookup :: (Eq k, Hashable k) => k -> HashMap k v -> Maybe vSource

*O(min(n,W))* Return the value to which the specified key is
mapped, or `Nothing`

if this map contains no mapping for the key.

*O(min(n,W))* Return the value to which the specified key is
mapped, or the default value if this map contains no mapping for
the key.

insert :: (Eq k, Hashable k) => k -> v -> HashMap k v -> HashMap k vSource

*O(min(n,W))* Associate the specified value with the specified
key in this map. If this map previously contained a mapping for
the key, the old value is replaced.

delete :: (Eq k, Hashable k) => k -> HashMap k v -> HashMap k vSource

*O(min(n,W))* Remove the mapping for the specified key from this
map if present.

insertWith :: (Eq k, Hashable k) => (v -> v -> v) -> k -> v -> HashMap k v -> HashMap k vSource

*O(min(n,W))* Associate the value with the key in this map. If
this map previously contained a mapping for the key, the old value
is replaced by the result of applying the given function to the new
and old value. Example:

insertWith f k v map where f new old = new + old

adjust :: (Eq k, Hashable k) => (v -> v) -> k -> HashMap k v -> HashMap k vSource

*O(min(n,W)* Adjust the value tied to a given key in this map
only if it is present. Otherwise, leave the map alone.

# Combine

## Union

union :: Eq k => HashMap k v -> HashMap k v -> HashMap k vSource

*O(n+m)* The union of two maps. If a key occurs in both maps,
the mapping from the first will be the mapping in the result.

unionWith :: Eq k => (v -> v -> v) -> HashMap k v -> HashMap k v -> HashMap k vSource

*O(n+m)* The union of two maps. If a key occurs in both maps,
the provided function (first argument) will be used to compute the result.

# Transformations

map :: (v1 -> v2) -> HashMap k v1 -> HashMap k v2Source

*O(n)* Transform this map by applying a function to every value.

traverseWithKey :: Applicative f => (k -> v1 -> f v2) -> HashMap k v1 -> f (HashMap k v2)Source

*O(n)* Transform this map by accumulating an Applicative result
from every value.

# Difference and intersection

difference :: (Eq k, Hashable k) => HashMap k v -> HashMap k w -> HashMap k vSource

*O(n)* Difference of two maps. Return elements of the first map
not existing in the second.

intersection :: (Eq k, Hashable k) => HashMap k v -> HashMap k w -> HashMap k vSource

*O(n)* Intersection of two maps. Return elements of the first map
for keys existing in the second.

# Folds

foldl' :: (a -> v -> a) -> a -> HashMap k v -> aSource

*O(n)* Reduce this map by applying a binary operator to all
elements, using the given starting value (typically the
left-identity of the operator). Each application of the operator
is evaluated before before using the result in the next
application. This function is strict in the starting value.

foldlWithKey' :: (a -> k -> v -> a) -> a -> HashMap k v -> aSource

*O(n)* Reduce this map by applying a binary operator to all
elements, using the given starting value (typically the
left-identity of the operator). Each application of the operator
is evaluated before before using the result in the next
application. This function is strict in the starting value.

foldr :: (v -> a -> a) -> a -> HashMap k v -> aSource

*O(n)* Reduce this map by applying a binary operator to all
elements, using the given starting value (typically the
right-identity of the operator).

foldrWithKey :: (k -> v -> a -> a) -> a -> HashMap k v -> aSource

*O(n)* Reduce this map by applying a binary operator to all
elements, using the given starting value (typically the
right-identity of the operator).

# Filter

filter :: (v -> Bool) -> HashMap k v -> HashMap k vSource

*O(n)* Filter this map by retaining only elements which values
satisfy a predicate.

filterWithKey :: (k -> v -> Bool) -> HashMap k v -> HashMap k vSource

*O(n)* Filter this map by retaining only elements satisfying a
predicate.

# Conversions

elems :: HashMap k v -> [v]Source

*O(n)* Return a list of this map's values. The list is produced
lazily.

## Lists

toList :: HashMap k v -> [(k, v)]Source

*O(n)* Return a list of this map's elements. The list is
produced lazily.

fromList :: (Eq k, Hashable k) => [(k, v)] -> HashMap k vSource

*O(n*min(W, n))* Construct a map from a list of elements.

fromListWith :: (Eq k, Hashable k) => (v -> v -> v) -> [(k, v)] -> HashMap k vSource

*O(n*min(W, n))* Construct a map from a list of elements. Uses
the provided function to merge duplicate entries.