rio-0.1.22.0: A standard library for Haskell

Safe Haskell | Safe-Inferred
Language | Haskell2010

RIO.Map.Unchecked

Contents

- Traversal
  - Map
- Conversion
  - Ordered lists

Description

This module contains functions from Data.Map.Strict that have unchecked preconditions on their input. If these preconditions are not satisfied, the data structure may end up in an invalid state and other operations may misbehave. Import as:

    import qualified RIO.Map.Unchecked as Map'

Synopsis

- mapKeysMonotonic :: (k1 -> k2) -> Map k1 a -> Map k2 a
- toAscList :: Map k a -> [(k, a)]
- fromAscList :: Eq k => [(k, a)] -> Map k a
- fromAscListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a
- fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a
- fromDistinctAscList :: [(k, a)] -> Map k a
- toDescList :: Map k a -> [(k, a)]
- fromDescList :: Eq k => [(k, a)] -> Map k a
- fromDescListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a
- fromDescListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a
- fromDistinctDescList :: [(k, a)] -> Map k a

# Traversal

## Map

mapKeysMonotonic :: (k1 -> k2) -> Map k1 a -> Map k2 a #

\(O(n)\). ``mapKeysMonotonic` f s == `mapKeys` f s`, but works only when `f` is strictly monotonic. That is, for any values `x` and `y`, if `x` < `y` then `f x` < `f y`. The precondition is not checked. Semi-formally, we have:

    and [x < y ==> f x < f y | x <- ls, y <- ls]
                        ==> mapKeysMonotonic f s == mapKeys f s
        where ls = keys s

This means that `f` maps distinct original keys to distinct resulting keys. This function has better performance than `mapKeys`.

    mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
    valid (mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")])) == True
    valid (mapKeysMonotonic (\ _ -> 1)     (fromList [(5,"a"), (3,"b")])) == False

# Conversion

## Ordered lists

toAscList :: Map k a -> [(k, a)] #

\(O(n)\). Convert the map to a list of key/value pairs where the keys are in ascending order. Subject to list fusion.

    toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")]

fromAscList :: Eq k => [(k, a)] -> Map k a #

\(O(n)\). Build a map from an ascending list in linear time. The precondition (input list is ascending) is not checked.

    fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
    fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
    valid (fromAscList [(3,"b"), (5,"a"), (5,"b")]) == True
    valid (fromAscList [(5,"a"), (3,"b"), (5,"b")]) == False

fromAscListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a #

\(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys. The precondition (input list is ascending) is not checked.

    fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
    valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
    valid (fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False

Also see the performance note on `fromListWith`.

fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a #

\(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys. The precondition (input list is ascending) is not checked.

    let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
    fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
    valid (fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")]) == True
    valid (fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]) == False

Also see the performance note on `fromListWith`.

fromDistinctAscList :: [(k, a)] -> Map k a #

\(O(n)\). Build a map from an ascending list of distinct elements in linear time. The precondition is not checked.

    fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
    valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
    valid (fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")]) == False

toDescList :: Map k a -> [(k, a)] #

\(O(n)\). Convert the map to a list of key/value pairs where the keys are in descending order. Subject to list fusion.

    toDescList (fromList [(5,"a"), (3,"b")]) == [(5,"a"), (3,"b")]

fromDescList :: Eq k => [(k, a)] -> Map k a #

\(O(n)\). Build a map from a descending list in linear time. The precondition (input list is descending) is not checked.

    fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
    fromDescList [(5,"a"), (5,"b"), (3,"a")] == fromList [(3, "b"), (5, "b")]
    valid (fromDescList [(5,"a"), (5,"b"), (3,"b")]) == True
    valid (fromDescList [(5,"a"), (3,"b"), (5,"b")]) == False

fromDescListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a #

\(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys. The precondition (input list is descending) is not checked.

    fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
    valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
    valid (fromDescListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False

Also see the performance note on `fromListWith`.

fromDescListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a #

\(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys. The precondition (input list is descending) is not checked.

    let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
    fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
    valid (fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")]) == True
    valid (fromDescListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]) == False

Also see the performance note on `fromListWith`.

fromDistinctDescList :: [(k, a)] -> Map k a #

\(O(n)\). Build a map from a descending list of distinct elements in linear time. The precondition is not checked.

    fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
    valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True
    valid (fromDistinctDescList [(5,"a"), (3,"b"), (3,"a")]) == False