Copyright | (c) Daan Leijen 2002 (c) Andriy Palamarchuk 2008 |
---|---|
License | BSD-style |
Maintainer | libraries@haskell.org |
Portability | portable |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
Finite Int Maps (strict interface)
The
type represents a finite map (sometimes called a dictionary)
from key of type IntMap
vInt
to values of type v
.
Each function in this module is careful to force values before installing
them in an IntMap
. This is usually more efficient when laziness is not
necessary. When laziness is required, use the functions in
Data.IntMap.Lazy.
In particular, the functions in this module obey the following law:
- If all values stored in all maps in the arguments are in WHNF, then all values stored in all maps in the results will be in WHNF once those maps are evaluated.
For a walkthrough of the most commonly used functions see the maps introduction.
This module is intended to be imported qualified, to avoid name clashes with Prelude functions:
import Data.IntMap.Strict (IntMap) import qualified Data.IntMap.Strict as IntMap
Note that the implementation is generally left-biased. Functions that take
two maps as arguments and combine them, such as union
and intersection
,
prefer the values in the first argument to those in the second.
Detailed performance information
The amortized running time is given for each operation, with \(n\) referring to
the number of entries in the map and \(W\) referring to the number of bits in
an Int
(32 or 64).
Benchmarks comparing Data.IntMap.Strict with other dictionary implementations can be found at https://github.com/haskell-perf/dictionaries.
Warning
The IntMap
type is shared between the lazy and strict modules, meaning that
the same IntMap
value can be passed to functions in both modules. This
means that the Functor
, Traversable
and Data
instances are
the same as for the Data.IntMap.Lazy module, so if they are used the
resulting map may contain suspended values (thunks).
Implementation
The implementation is based on big-endian patricia trees. This data
structure performs especially well on binary operations like union
and
intersection
. Additionally, benchmarks show that it is also (much) faster
on insertions and deletions when compared to a generic size-balanced map
implementation (see Data.Map).
- Chris Okasaki and Andy Gill, "Fast Mergeable Integer Maps", Workshop on ML, September 1998, pages 77-86, http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.37.5452
- D.R. Morrison, "PATRICIA -- Practical Algorithm To Retrieve Information Coded In Alphanumeric", Journal of the ACM, 15(4), October 1968, pages 514-534.
Synopsis
- data IntMap a
- type Key = Int
- empty :: IntMap a
- singleton :: Key -> a -> IntMap a
- fromSet :: (Key -> a) -> IntSet -> IntMap a
- fromList :: [(Key, a)] -> IntMap a
- fromListWith :: (a -> a -> a) -> [(Key, a)] -> IntMap a
- fromListWithKey :: (Key -> a -> a -> a) -> [(Key, a)] -> IntMap a
- fromAscList :: [(Key, a)] -> IntMap a
- fromAscListWith :: (a -> a -> a) -> [(Key, a)] -> IntMap a
- fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key, a)] -> IntMap a
- fromDistinctAscList :: [(Key, a)] -> IntMap a
- insert :: Key -> a -> IntMap a -> IntMap a
- insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
- insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
- insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> (Maybe a, IntMap a)
- delete :: Key -> IntMap a -> IntMap a
- adjust :: (a -> a) -> Key -> IntMap a -> IntMap a
- adjustWithKey :: (Key -> a -> a) -> Key -> IntMap a -> IntMap a
- update :: (a -> Maybe a) -> Key -> IntMap a -> IntMap a
- updateWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> IntMap a
- updateLookupWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> (Maybe a, IntMap a)
- alter :: (Maybe a -> Maybe a) -> Key -> IntMap a -> IntMap a
- alterF :: Functor f => (Maybe a -> f (Maybe a)) -> Key -> IntMap a -> f (IntMap a)
- lookup :: Key -> IntMap a -> Maybe a
- (!?) :: IntMap a -> Key -> Maybe a
- (!) :: IntMap a -> Key -> a
- findWithDefault :: a -> Key -> IntMap a -> a
- member :: Key -> IntMap a -> Bool
- notMember :: Key -> IntMap a -> Bool
- lookupLT :: Key -> IntMap a -> Maybe (Key, a)
- lookupGT :: Key -> IntMap a -> Maybe (Key, a)
- lookupLE :: Key -> IntMap a -> Maybe (Key, a)
- lookupGE :: Key -> IntMap a -> Maybe (Key, a)
- null :: IntMap a -> Bool
- size :: IntMap a -> Int
- union :: IntMap a -> IntMap a -> IntMap a
- unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
- unionWithKey :: (Key -> a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
- unions :: Foldable f => f (IntMap a) -> IntMap a
- unionsWith :: Foldable f => (a -> a -> a) -> f (IntMap a) -> IntMap a
- difference :: IntMap a -> IntMap b -> IntMap a
- (\\) :: IntMap a -> IntMap b -> IntMap a
- differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
- differenceWithKey :: (Key -> a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
- intersection :: IntMap a -> IntMap b -> IntMap a
- intersectionWith :: (a -> b -> c) -> IntMap a -> IntMap b -> IntMap c
- intersectionWithKey :: (Key -> a -> b -> c) -> IntMap a -> IntMap b -> IntMap c
- disjoint :: IntMap a -> IntMap b -> Bool
- compose :: IntMap c -> IntMap Int -> IntMap c
- mergeWithKey :: (Key -> a -> b -> Maybe c) -> (IntMap a -> IntMap c) -> (IntMap b -> IntMap c) -> IntMap a -> IntMap b -> IntMap c
- map :: (a -> b) -> IntMap a -> IntMap b
- mapWithKey :: (Key -> a -> b) -> IntMap a -> IntMap b
- traverseWithKey :: Applicative t => (Key -> a -> t b) -> IntMap a -> t (IntMap b)
- traverseMaybeWithKey :: Applicative f => (Key -> a -> f (Maybe b)) -> IntMap a -> f (IntMap b)
- mapAccum :: (a -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c)
- mapAccumWithKey :: (a -> Key -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c)
- mapAccumRWithKey :: (a -> Key -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c)
- mapKeys :: (Key -> Key) -> IntMap a -> IntMap a
- mapKeysWith :: (a -> a -> a) -> (Key -> Key) -> IntMap a -> IntMap a
- mapKeysMonotonic :: (Key -> Key) -> IntMap a -> IntMap a
- foldr :: (a -> b -> b) -> b -> IntMap a -> b
- foldl :: (a -> b -> a) -> a -> IntMap b -> a
- foldrWithKey :: (Key -> a -> b -> b) -> b -> IntMap a -> b
- foldlWithKey :: (a -> Key -> b -> a) -> a -> IntMap b -> a
- foldMapWithKey :: Monoid m => (Key -> a -> m) -> IntMap a -> m
- foldr' :: (a -> b -> b) -> b -> IntMap a -> b
- foldl' :: (a -> b -> a) -> a -> IntMap b -> a
- foldrWithKey' :: (Key -> a -> b -> b) -> b -> IntMap a -> b
- foldlWithKey' :: (a -> Key -> b -> a) -> a -> IntMap b -> a
- elems :: IntMap a -> [a]
- keys :: IntMap a -> [Key]
- assocs :: IntMap a -> [(Key, a)]
- keysSet :: IntMap a -> IntSet
- toList :: IntMap a -> [(Key, a)]
- toAscList :: IntMap a -> [(Key, a)]
- toDescList :: IntMap a -> [(Key, a)]
- filter :: (a -> Bool) -> IntMap a -> IntMap a
- filterWithKey :: (Key -> a -> Bool) -> IntMap a -> IntMap a
- restrictKeys :: IntMap a -> IntSet -> IntMap a
- withoutKeys :: IntMap a -> IntSet -> IntMap a
- partition :: (a -> Bool) -> IntMap a -> (IntMap a, IntMap a)
- partitionWithKey :: (Key -> a -> Bool) -> IntMap a -> (IntMap a, IntMap a)
- takeWhileAntitone :: (Key -> Bool) -> IntMap a -> IntMap a
- dropWhileAntitone :: (Key -> Bool) -> IntMap a -> IntMap a
- spanAntitone :: (Key -> Bool) -> IntMap a -> (IntMap a, IntMap a)
- mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b
- mapMaybeWithKey :: (Key -> a -> Maybe b) -> IntMap a -> IntMap b
- mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
- mapEitherWithKey :: (Key -> a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
- split :: Key -> IntMap a -> (IntMap a, IntMap a)
- splitLookup :: Key -> IntMap a -> (IntMap a, Maybe a, IntMap a)
- splitRoot :: IntMap a -> [IntMap a]
- isSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool
- isSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool
- isProperSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool
- isProperSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool
- lookupMin :: IntMap a -> Maybe (Key, a)
- lookupMax :: IntMap a -> Maybe (Key, a)
- findMin :: IntMap a -> (Key, a)
- findMax :: IntMap a -> (Key, a)
- deleteMin :: IntMap a -> IntMap a
- deleteMax :: IntMap a -> IntMap a
- deleteFindMin :: IntMap a -> ((Key, a), IntMap a)
- deleteFindMax :: IntMap a -> ((Key, a), IntMap a)
- updateMin :: (a -> Maybe a) -> IntMap a -> IntMap a
- updateMax :: (a -> Maybe a) -> IntMap a -> IntMap a
- updateMinWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a
- updateMaxWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a
- minView :: IntMap a -> Maybe (a, IntMap a)
- maxView :: IntMap a -> Maybe (a, IntMap a)
- minViewWithKey :: IntMap a -> Maybe ((Key, a), IntMap a)
- maxViewWithKey :: IntMap a -> Maybe ((Key, a), IntMap a)
- showTree :: Whoops "Data.IntMap.showTree has moved to Data.IntMap.Internal.Debug.showTree" => IntMap a -> String
- showTreeWith :: Whoops "Data.IntMap.showTreeWith has moved to Data.IntMap.Internal.Debug.showTreeWith" => Bool -> Bool -> IntMap a -> String
Map type
A map of integers to values a
.
Instances
Eq1 IntMap Source # | Since: containers-0.5.9 |
Ord1 IntMap Source # | Since: containers-0.5.9 |
Defined in Data.IntMap.Internal | |
Read1 IntMap Source # | Since: containers-0.5.9 |
Defined in Data.IntMap.Internal liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (IntMap a) Source # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [IntMap a] Source # liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (IntMap a) Source # liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [IntMap a] Source # | |
Show1 IntMap Source # | Since: containers-0.5.9 |
Functor IntMap Source # | |
Foldable IntMap Source # | Folds in order of increasing key. |
Defined in Data.IntMap.Internal fold :: Monoid m => IntMap m -> m # foldMap :: Monoid m => (a -> m) -> IntMap a -> m # foldMap' :: Monoid m => (a -> m) -> IntMap a -> m # foldr :: (a -> b -> b) -> b -> IntMap a -> b # foldr' :: (a -> b -> b) -> b -> IntMap a -> b # foldl :: (b -> a -> b) -> b -> IntMap a -> b # foldl' :: (b -> a -> b) -> b -> IntMap a -> b # foldr1 :: (a -> a -> a) -> IntMap a -> a # foldl1 :: (a -> a -> a) -> IntMap a -> a # elem :: Eq a => a -> IntMap a -> Bool # maximum :: Ord a => IntMap a -> a # minimum :: Ord a => IntMap a -> a # | |
Traversable IntMap Source # | Traverses in order of increasing key. |
Lift a => Lift (IntMap a :: Type) Source # | Since: containers-0.6.6 |
NFData a => NFData (IntMap a) Source # | |
Defined in Data.IntMap.Internal | |
Monoid (IntMap a) Source # | |
Semigroup (IntMap a) Source # | Since: containers-0.5.7 |
Data a => Data (IntMap a) Source # | |
Defined in Data.IntMap.Internal gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> IntMap a -> c (IntMap a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (IntMap a) # toConstr :: IntMap a -> Constr # dataTypeOf :: IntMap a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (IntMap a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (IntMap a)) # gmapT :: (forall b. Data b => b -> b) -> IntMap a -> IntMap a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> IntMap a -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> IntMap a -> r # gmapQ :: (forall d. Data d => d -> u) -> IntMap a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> IntMap a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> IntMap a -> m (IntMap a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> IntMap a -> m (IntMap a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> IntMap a -> m (IntMap a) # | |
IsList (IntMap a) Source # | Since: containers-0.5.6.2 |
Read e => Read (IntMap e) Source # | |
Show a => Show (IntMap a) Source # | |
Eq a => Eq (IntMap a) Source # | |
Ord a => Ord (IntMap a) Source # | |
Defined in Data.IntMap.Internal | |
type Item (IntMap a) Source # | |
Defined in Data.IntMap.Internal |
Construction
singleton :: Key -> a -> IntMap a Source #
\(O(1)\). A map of one element.
singleton 1 'a' == fromList [(1, 'a')] size (singleton 1 'a') == 1
fromSet :: (Key -> a) -> IntSet -> IntMap a Source #
\(O(n)\). Build a map from a set of keys and a function which for each key computes its value.
fromSet (\k -> replicate k 'a') (Data.IntSet.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")] fromSet undefined Data.IntSet.empty == empty
From Unordered Lists
fromList :: [(Key, a)] -> IntMap a Source #
\(O(n \min(n,W))\). Create a map from a list of key/value pairs.
fromList [] == empty fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")] fromList [(5,"c"), (3,"b"), (5, "a")] == fromList [(5,"a"), (3,"b")]
fromListWith :: (a -> a -> a) -> [(Key, a)] -> IntMap a Source #
\(O(n \min(n,W))\). Build a map from a list of key/value pairs with a combining function. See also fromAscListWith
.
fromListWith (++) [(5,"a"), (5,"b"), (3,"x"), (5,"c")] == fromList [(3, "x"), (5, "cba")] fromListWith (++) [] == empty
Note the reverse ordering of "cba"
in the example.
The symmetric combining function f
is applied in a left-fold over the list, as f new old
.
Performance
You should ensure that the given f
is fast with this order of arguments.
Symmetric functions may be slow in one order, and fast in another. For the common case of collecting values of matching keys in a list, as above:
The complexity of (++) a b
is \(O(a)\), so it is fast when given a short list as its first argument.
Thus:
fromListWith (++) (replicate 1000000 (3, "x")) -- O(n), fast fromListWith (flip (++)) (replicate 1000000 (3, "x")) -- O(n²), extremely slow
because they evaluate as, respectively:
fromList [(3, "x" ++ ("x" ++ "xxxxx..xxxxx"))] -- O(n) fromList [(3, ("xxxxx..xxxxx" ++ "x") ++ "x")] -- O(n²)
Thus, to get good performance with an operation like (++)
while also preserving
the same order as in the input list, reverse the input:
fromListWith (++) (reverse [(5,"a"), (5,"b"), (5,"c")]) == fromList [(5, "abc")]
and it is always fast to combine singleton-list values [v]
with fromListWith (++)
, as in:
fromListWith (++) $ reverse $ map (\(k, v) -> (k, [v])) someListOfTuples
fromListWithKey :: (Key -> a -> a -> a) -> [(Key, a)] -> IntMap a Source #
\(O(n \min(n,W))\). Build a map from a list of key/value pairs with a combining function. See also fromAscListWithKey'.
let f key new_value old_value = show key ++ ":" ++ new_value ++ "|" ++ old_value fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"c")] == fromList [(3, "3:a|b"), (5, "5:c|5:b|a")] fromListWithKey f [] == empty
Also see the performance note on fromListWith
.
From Ascending Lists
fromAscList :: [(Key, a)] -> IntMap a Source #
\(O(n)\). Build a map from a list of key/value pairs where the keys are in ascending order.
fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
fromAscListWith :: (a -> a -> a) -> [(Key, a)] -> IntMap a Source #
\(O(n)\). Build a map from a list of key/value pairs where the keys are in ascending order, with a combining function on equal keys. The precondition (input list is ascending) is not checked.
fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
Also see the performance note on fromListWith
.
fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key, a)] -> IntMap a Source #
\(O(n)\). Build a map from a list of key/value pairs where the keys are in ascending order, with a combining function on equal keys. The precondition (input list is ascending) is not checked.
fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
Also see the performance note on fromListWith
.
fromDistinctAscList :: [(Key, a)] -> IntMap a Source #
\(O(n)\). Build a map from a list of key/value pairs where the keys are in ascending order and all distinct. The precondition (input list is strictly ascending) is not checked.
fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
Insertion
insert :: Key -> a -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Insert a new key/value pair in the map.
If the key is already present in the map, the associated value is
replaced with the supplied value, i.e. insert
is equivalent to
.insertWith
const
insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')] insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')] insert 5 'x' empty == singleton 5 'x'
insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Insert with a combining function.
will insert the pair (key, value) into insertWith
f key value mpmp
if key does
not exist in the map. If the key does exist, the function will
insert f new_value old_value
.
insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")] insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")] insertWith (++) 5 "xxx" empty == singleton 5 "xxx"
Also see the performance note on fromListWith
.
insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Insert with a combining function.
will insert the pair (key, value) into insertWithKey
f key value mpmp
if key does
not exist in the map. If the key does exist, the function will
insert f key new_value old_value
.
let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")] insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")] insertWithKey f 5 "xxx" empty == singleton 5 "xxx"
If the key exists in the map, this function is lazy in value
but strict
in the result of f
.
Also see the performance note on fromListWith
.
insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> (Maybe a, IntMap a) Source #
\(O(\min(n,W))\). The expression (
)
is a pair where the first element is equal to (insertLookupWithKey
f k x map
)
and the second element equal to (lookup
k map
).insertWithKey
f k x map
let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")]) insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "xxx")]) insertLookupWithKey f 5 "xxx" empty == (Nothing, singleton 5 "xxx")
This is how to define insertLookup
using insertLookupWithKey
:
let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")]) insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "x")])
Also see the performance note on fromListWith
.
Deletion/Update
delete :: Key -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Delete a key and its value from the map. When the key is not a member of the map, the original map is returned.
delete 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" delete 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] delete 5 empty == empty
adjust :: (a -> a) -> Key -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Adjust a value at a specific key. When the key is not a member of the map, the original map is returned.
adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] adjust ("new " ++) 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] adjust ("new " ++) 7 empty == empty
adjustWithKey :: (Key -> a -> a) -> Key -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Adjust a value at a specific key. When the key is not a member of the map, the original map is returned.
let f key x = (show key) ++ ":new " ++ x adjustWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")] adjustWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] adjustWithKey f 7 empty == empty
update :: (a -> Maybe a) -> Key -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). The expression (
) updates the value update
f k mapx
at k
(if it is in the map). If (f x
) is Nothing
, the element is
deleted. If it is (
), the key Just
yk
is bound to the new value y
.
let f x = if x == "a" then Just "new a" else Nothing update f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] update f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] update f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
updateWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). The expression (
) updates the value update
f k mapx
at k
(if it is in the map). If (f k x
) is Nothing
, the element is
deleted. If it is (
), the key Just
yk
is bound to the new value y
.
let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing updateWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")] updateWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] updateWithKey f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
updateLookupWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> (Maybe a, IntMap a) Source #
\(O(\min(n,W))\). Lookup and update.
The function returns original value, if it is updated.
This is different behavior than updateLookupWithKey
.
Returns the original key value if the map entry is deleted.
let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing updateLookupWithKey f 5 (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:new a")]) updateLookupWithKey f 7 (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a")]) updateLookupWithKey f 3 (fromList [(5,"a"), (3,"b")]) == (Just "b", singleton 5 "a")
alterF :: Functor f => (Maybe a -> f (Maybe a)) -> Key -> IntMap a -> f (IntMap a) Source #
\(O(\log n)\). The expression (
) alters the value alterF
f k mapx
at
k
, or absence thereof. alterF
can be used to inspect, insert, delete,
or update a value in an IntMap
. In short :
.lookup
k $ alterF
f k m = f
(lookup
k m)
Example:
interactiveAlter :: Int -> IntMap String -> IO (IntMap String) interactiveAlter k m = alterF f k m where f Nothing = do putStrLn $ show k ++ " was not found in the map. Would you like to add it?" getUserResponse1 :: IO (Maybe String) f (Just old) = do putStrLn $ "The key is currently bound to " ++ show old ++ ". Would you like to change or delete it?" getUserResponse2 :: IO (Maybe String)
alterF
is the most general operation for working with an individual
key that may or may not be in a given map.
Query
Lookup
lookup :: Key -> IntMap a -> Maybe a Source #
\(O(\min(n,W))\). Lookup the value at a key in the map. See also lookup
.
(!?) :: IntMap a -> Key -> Maybe a infixl 9 Source #
\(O(\min(n,W))\). Find the value at a key.
Returns Nothing
when the element can not be found.
fromList [(5,'a'), (3,'b')] !? 1 == Nothing fromList [(5,'a'), (3,'b')] !? 5 == Just 'a'
Since: containers-0.5.11
(!) :: IntMap a -> Key -> a Source #
\(O(\min(n,W))\). Find the value at a key.
Calls error
when the element can not be found.
fromList [(5,'a'), (3,'b')] ! 1 Error: element not in the map fromList [(5,'a'), (3,'b')] ! 5 == 'a'
findWithDefault :: a -> Key -> IntMap a -> a Source #
\(O(\min(n,W))\). The expression (
returns the value at key findWithDefault
def k map)k
or returns def
when the key is not an
element of the map.
findWithDefault 'x' 1 (fromList [(5,'a'), (3,'b')]) == 'x' findWithDefault 'x' 5 (fromList [(5,'a'), (3,'b')]) == 'a'
member :: Key -> IntMap a -> Bool Source #
\(O(\min(n,W))\). Is the key a member of the map?
member 5 (fromList [(5,'a'), (3,'b')]) == True member 1 (fromList [(5,'a'), (3,'b')]) == False
notMember :: Key -> IntMap a -> Bool Source #
\(O(\min(n,W))\). Is the key not a member of the map?
notMember 5 (fromList [(5,'a'), (3,'b')]) == False notMember 1 (fromList [(5,'a'), (3,'b')]) == True
lookupLT :: Key -> IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). Find largest key smaller than the given one and return the corresponding (key, value) pair.
lookupLT 3 (fromList [(3,'a'), (5,'b')]) == Nothing lookupLT 4 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a')
lookupGT :: Key -> IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). Find smallest key greater than the given one and return the corresponding (key, value) pair.
lookupGT 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b') lookupGT 5 (fromList [(3,'a'), (5,'b')]) == Nothing
lookupLE :: Key -> IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). Find largest key smaller or equal to the given one and return the corresponding (key, value) pair.
lookupLE 2 (fromList [(3,'a'), (5,'b')]) == Nothing lookupLE 4 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a') lookupLE 5 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b')
lookupGE :: Key -> IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). Find smallest key greater or equal to the given one and return the corresponding (key, value) pair.
lookupGE 3 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a') lookupGE 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b') lookupGE 6 (fromList [(3,'a'), (5,'b')]) == Nothing
Size
null :: IntMap a -> Bool Source #
\(O(1)\). Is the map empty?
Data.IntMap.null (empty) == True Data.IntMap.null (singleton 1 'a') == False
size :: IntMap a -> Int Source #
\(O(n)\). Number of elements in the map.
size empty == 0 size (singleton 1 'a') == 1 size (fromList([(1,'a'), (2,'c'), (3,'b')])) == 3
Combine
Union
unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a Source #
\(O(n+m)\). The union with a combining function.
unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")]
Also see the performance note on fromListWith
.
unionWithKey :: (Key -> a -> a -> a) -> IntMap a -> IntMap a -> IntMap a Source #
\(O(n+m)\). The union with a combining function.
let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")]
Also see the performance note on fromListWith
.
unions :: Foldable f => f (IntMap a) -> IntMap a Source #
The union of a list of maps.
unions [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])] == fromList [(3, "b"), (5, "a"), (7, "C")] unions [(fromList [(5, "A3"), (3, "B3")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "a"), (3, "b")])] == fromList [(3, "B3"), (5, "A3"), (7, "C")]
unionsWith :: Foldable f => (a -> a -> a) -> f (IntMap a) -> IntMap a Source #
The union of a list of maps, with a combining operation.
unionsWith (++) [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])] == fromList [(3, "bB3"), (5, "aAA3"), (7, "C")]
Difference
difference :: IntMap a -> IntMap b -> IntMap a Source #
\(O(n+m)\). Difference between two maps (based on keys).
difference (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 3 "b"
differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a Source #
\(O(n+m)\). Difference with a combining function.
let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")]) == singleton 3 "b:B"
differenceWithKey :: (Key -> a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a Source #
\(O(n+m)\). Difference with a combining function. When two equal keys are
encountered, the combining function is applied to the key and both values.
If it returns Nothing
, the element is discarded (proper set difference).
If it returns (
), the element is updated with a new value Just
yy
.
let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing differenceWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (10, "C")]) == singleton 3 "3:b|B"
Intersection
intersection :: IntMap a -> IntMap b -> IntMap a Source #
\(O(n+m)\). The (left-biased) intersection of two maps (based on keys).
intersection (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "a"
intersectionWith :: (a -> b -> c) -> IntMap a -> IntMap b -> IntMap c Source #
\(O(n+m)\). The intersection with a combining function.
intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA"
intersectionWithKey :: (Key -> a -> b -> c) -> IntMap a -> IntMap b -> IntMap c Source #
\(O(n+m)\). The intersection with a combining function.
let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A"
Disjoint
disjoint :: IntMap a -> IntMap b -> Bool Source #
\(O(n+m)\). Check whether the key sets of two maps are disjoint
(i.e. their intersection
is empty).
disjoint (fromList [(2,'a')]) (fromList [(1,()), (3,())]) == True disjoint (fromList [(2,'a')]) (fromList [(1,'a'), (2,'b')]) == False disjoint (fromList []) (fromList []) == True
disjoint a b == null (intersection a b)
Since: containers-0.6.2.1
Compose
compose :: IntMap c -> IntMap Int -> IntMap c Source #
Relate the keys of one map to the values of the other, by using the values of the former as keys for lookups in the latter.
Complexity: \( O(n * \min(m,W)) \), where \(m\) is the size of the first argument
compose (fromList [('a', "A"), ('b', "B")]) (fromList [(1,'a'),(2,'b'),(3,'z')]) = fromList [(1,"A"),(2,"B")]
(compose
bc ab!?
) = (bc!?
) <=< (ab!?
)
Note: Prior to v0.6.4, Data.IntMap.Strict exposed a version of
compose
that forced the values of the output IntMap
. This version does
not force these values.
Since: containers-0.6.3.1
Universal combining function
mergeWithKey :: (Key -> a -> b -> Maybe c) -> (IntMap a -> IntMap c) -> (IntMap b -> IntMap c) -> IntMap a -> IntMap b -> IntMap c Source #
\(O(n+m)\). A high-performance universal combining function. Using
mergeWithKey
, all combining functions can be defined without any loss of
efficiency (with exception of union
, difference
and intersection
,
where sharing of some nodes is lost with mergeWithKey
).
Please make sure you know what is going on when using mergeWithKey
,
otherwise you can be surprised by unexpected code growth or even
corruption of the data structure.
When mergeWithKey
is given three arguments, it is inlined to the call
site. You should therefore use mergeWithKey
only to define your custom
combining functions. For example, you could define unionWithKey
,
differenceWithKey
and intersectionWithKey
as
myUnionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -> Just (f k x1 x2)) id id m1 m2 myDifferenceWithKey f m1 m2 = mergeWithKey f id (const empty) m1 m2 myIntersectionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -> Just (f k x1 x2)) (const empty) (const empty) m1 m2
When calling
, a function combining two
mergeWithKey
combine only1 only2IntMap
s is created, such that
- if a key is present in both maps, it is passed with both corresponding
values to the
combine
function. Depending on the result, the key is either present in the result with specified value, or is left out; - a nonempty subtree present only in the first map is passed to
only1
and the output is added to the result; - a nonempty subtree present only in the second map is passed to
only2
and the output is added to the result.
The only1
and only2
methods must return a map with a subset (possibly empty) of the keys of the given map.
The values can be modified arbitrarily. Most common variants of only1
and
only2
are id
and
, but for example const
empty
or
map
f
could be used for any filterWithKey
ff
.
Traversal
Map
map :: (a -> b) -> IntMap a -> IntMap b Source #
\(O(n)\). Map a function over all values in the map.
map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")]
mapWithKey :: (Key -> a -> b) -> IntMap a -> IntMap b Source #
\(O(n)\). Map a function over all values in the map.
let f key x = (show key) ++ ":" ++ x mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")]
traverseWithKey :: Applicative t => (Key -> a -> t b) -> IntMap a -> t (IntMap b) Source #
\(O(n)\).
That is, behaves exactly like a regular traverseWithKey
f s == fromList
$ traverse
((k, v) -> (,) k $ f k v) (toList
m)traverse
except that the traversing
function also has access to the key associated with a value.
traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(1, 'a'), (5, 'e')]) == Just (fromList [(1, 'b'), (5, 'f')]) traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(2, 'c')]) == Nothing
traverseMaybeWithKey :: Applicative f => (Key -> a -> f (Maybe b)) -> IntMap a -> f (IntMap b) Source #
\(O(n)\). Traverse keys/values and collect the Just
results.
Since: containers-0.6.4
mapAccum :: (a -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c) Source #
\(O(n)\). The function
threads an accumulating
argument through the map in ascending order of keys.mapAccum
let f a b = (a ++ b, b ++ "X") mapAccum f "Everything: " (fromList [(5,"a"), (3,"b")]) == ("Everything: ba", fromList [(3, "bX"), (5, "aX")])
mapAccumWithKey :: (a -> Key -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c) Source #
\(O(n)\). The function
threads an accumulating
argument through the map in ascending order of keys.mapAccumWithKey
let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") mapAccumWithKey f "Everything:" (fromList [(5,"a"), (3,"b")]) == ("Everything: 3-b 5-a", fromList [(3, "bX"), (5, "aX")])
mapAccumRWithKey :: (a -> Key -> b -> (a, c)) -> a -> IntMap b -> (a, IntMap c) Source #
\(O(n)\). The function
threads an accumulating
argument through the map in descending order of keys.mapAccumRWithKey
mapKeys :: (Key -> Key) -> IntMap a -> IntMap a Source #
\(O(n \min(n,W))\).
is the map obtained by applying mapKeys
f sf
to each key of s
.
The size of the result may be smaller if f
maps two or more distinct
keys to the same new key. In this case the value at the greatest of the
original keys is retained.
mapKeys (+ 1) (fromList [(5,"a"), (3,"b")]) == fromList [(4, "b"), (6, "a")] mapKeys (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "c" mapKeys (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "c"
mapKeysWith :: (a -> a -> a) -> (Key -> Key) -> IntMap a -> IntMap a Source #
\(O(n \log n)\).
is the map obtained by applying mapKeysWith
c f sf
to each key of s
.
The size of the result may be smaller if f
maps two or more distinct
keys to the same new key. In this case the associated values will be
combined using c
.
mapKeysWith (++) (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "cdab" mapKeysWith (++) (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "cdab"
Also see the performance note on fromListWith
.
mapKeysMonotonic :: (Key -> Key) -> IntMap a -> IntMap a Source #
\(O(n)\).
, but works only when mapKeysMonotonic
f s == mapKeys
f sf
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 slightly better performance than mapKeys
.
mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
Folds
foldrWithKey :: (Key -> a -> b -> b) -> b -> IntMap a -> b Source #
\(O(n)\). Fold the keys and values in the map using the given right-associative
binary operator, such that
.foldrWithKey
f z == foldr
(uncurry
f) z . toAscList
For example,
keys map = foldrWithKey (\k x ks -> k:ks) [] map
let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")" foldrWithKey f "Map: " (fromList [(5,"a"), (3,"b")]) == "Map: (5:a)(3:b)"
foldlWithKey :: (a -> Key -> b -> a) -> a -> IntMap b -> a Source #
\(O(n)\). Fold the keys and values in the map using the given left-associative
binary operator, such that
.foldlWithKey
f z == foldl
(\z' (kx, x) -> f z' kx x) z . toAscList
For example,
keys = reverse . foldlWithKey (\ks k x -> k:ks) []
let f result k a = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")" foldlWithKey f "Map: " (fromList [(5,"a"), (3,"b")]) == "Map: (3:b)(5:a)"
foldMapWithKey :: Monoid m => (Key -> a -> m) -> IntMap a -> m Source #
\(O(n)\). Fold the keys and values in the map using the given monoid, such that
foldMapWithKey
f =fold
.mapWithKey
f
This can be an asymptotically faster than foldrWithKey
or foldlWithKey
for some monoids.
Since: containers-0.5.4
Strict folds
foldr' :: (a -> b -> b) -> b -> IntMap a -> b Source #
\(O(n)\). A strict version of foldr
. Each application of the operator is
evaluated before using the result in the next application. This
function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> IntMap b -> a Source #
\(O(n)\). A strict version of foldl
. Each application of the operator is
evaluated before using the result in the next application. This
function is strict in the starting value.
foldrWithKey' :: (Key -> a -> b -> b) -> b -> IntMap a -> b Source #
\(O(n)\). A strict version of foldrWithKey
. Each application of the operator is
evaluated before using the result in the next application. This
function is strict in the starting value.
foldlWithKey' :: (a -> Key -> b -> a) -> a -> IntMap b -> a Source #
\(O(n)\). A strict version of foldlWithKey
. Each application of the operator is
evaluated before using the result in the next application. This
function is strict in the starting value.
Conversion
elems :: IntMap a -> [a] Source #
\(O(n)\). Return all elements of the map in the ascending order of their keys. Subject to list fusion.
elems (fromList [(5,"a"), (3,"b")]) == ["b","a"] elems empty == []
keys :: IntMap a -> [Key] Source #
\(O(n)\). Return all keys of the map in ascending order. Subject to list fusion.
keys (fromList [(5,"a"), (3,"b")]) == [3,5] keys empty == []
assocs :: IntMap a -> [(Key, a)] Source #
\(O(n)\). An alias for toAscList
. Returns all key/value pairs in the
map in ascending key order. Subject to list fusion.
assocs (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] assocs empty == []
keysSet :: IntMap a -> IntSet Source #
\(O(n)\). The set of all keys of the map.
keysSet (fromList [(5,"a"), (3,"b")]) == Data.IntSet.fromList [3,5] keysSet empty == Data.IntSet.empty
Lists
toList :: IntMap a -> [(Key, a)] Source #
\(O(n)\). Convert the map to a list of key/value pairs. Subject to list fusion.
toList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] toList empty == []
Ordered lists
toAscList :: IntMap a -> [(Key, a)] Source #
\(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")]
toDescList :: IntMap a -> [(Key, a)] Source #
\(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")]
Filter
filter :: (a -> Bool) -> IntMap a -> IntMap a Source #
\(O(n)\). Filter all values that satisfy some predicate.
filter (> "a") (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" filter (> "x") (fromList [(5,"a"), (3,"b")]) == empty filter (< "a") (fromList [(5,"a"), (3,"b")]) == empty
filterWithKey :: (Key -> a -> Bool) -> IntMap a -> IntMap a Source #
\(O(n)\). Filter all keys/values that satisfy some predicate.
filterWithKey (\k _ -> k > 4) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
restrictKeys :: IntMap a -> IntSet -> IntMap a Source #
\(O(n+m)\). The restriction of a map to the keys in a set.
m `restrictKeys` s =filterWithKey
(\k _ -> k`member`
s) m
Since: containers-0.5.8
withoutKeys :: IntMap a -> IntSet -> IntMap a Source #
\(O(n+m)\). Remove all the keys in a given set from a map.
m `withoutKeys` s =filterWithKey
(\k _ -> k`notMember`
s) m
Since: containers-0.5.8
partition :: (a -> Bool) -> IntMap a -> (IntMap a, IntMap a) Source #
\(O(n)\). Partition the map according to some predicate. The first
map contains all elements that satisfy the predicate, the second all
elements that fail the predicate. See also split
.
partition (> "a") (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a") partition (< "x") (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty) partition (> "x") (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")])
partitionWithKey :: (Key -> a -> Bool) -> IntMap a -> (IntMap a, IntMap a) Source #
\(O(n)\). Partition the map according to some predicate. The first
map contains all elements that satisfy the predicate, the second all
elements that fail the predicate. See also split
.
partitionWithKey (\ k _ -> k > 3) (fromList [(5,"a"), (3,"b")]) == (singleton 5 "a", singleton 3 "b") partitionWithKey (\ k _ -> k < 7) (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty) partitionWithKey (\ k _ -> k > 7) (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")])
takeWhileAntitone :: (Key -> Bool) -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Take while a predicate on the keys holds.
The user is responsible for ensuring that for all Int
s, j < k ==> p j >= p k
.
See note at spanAntitone
.
takeWhileAntitone p =fromDistinctAscList
.takeWhile
(p . fst) .toList
takeWhileAntitone p =filterWithKey
(\k _ -> p k)
Since: containers-0.6.7
dropWhileAntitone :: (Key -> Bool) -> IntMap a -> IntMap a Source #
\(O(\min(n,W))\). Drop while a predicate on the keys holds.
The user is responsible for ensuring that for all Int
s, j < k ==> p j >= p k
.
See note at spanAntitone
.
dropWhileAntitone p =fromDistinctAscList
.dropWhile
(p . fst) .toList
dropWhileAntitone p =filterWithKey
(\k _ -> not (p k))
Since: containers-0.6.7
spanAntitone :: (Key -> Bool) -> IntMap a -> (IntMap a, IntMap a) Source #
\(O(\min(n,W))\). Divide a map at the point where a predicate on the keys stops holding.
The user is responsible for ensuring that for all Int
s, j < k ==> p j >= p k
.
spanAntitone p xs = (takeWhileAntitone
p xs,dropWhileAntitone
p xs) spanAntitone p xs =partitionWithKey
(\k _ -> p k) xs
Note: if p
is not actually antitone, then spanAntitone
will split the map
at some unspecified point.
Since: containers-0.6.7
mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b Source #
\(O(n)\). Map values and collect the Just
results.
let f x = if x == "a" then Just "new a" else Nothing mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a"
mapMaybeWithKey :: (Key -> a -> Maybe b) -> IntMap a -> IntMap b Source #
\(O(n)\). Map keys/values and collect the Just
results.
let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3"
mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) Source #
\(O(n)\). Map values and separate the Left
and Right
results.
let f a = if a < "c" then Left a else Right a mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) == (fromList [(3,"b"), (5,"a")], fromList [(1,"x"), (7,"z")]) mapEither (\ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) == (empty, fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
mapEitherWithKey :: (Key -> a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) Source #
\(O(n)\). Map keys/values and separate the Left
and Right
results.
let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) == (fromList [(1,2), (3,6)], fromList [(5,"aa"), (7,"zz")]) mapEitherWithKey (\_ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) == (empty, fromList [(1,"x"), (3,"b"), (5,"a"), (7,"z")])
split :: Key -> IntMap a -> (IntMap a, IntMap a) Source #
\(O(\min(n,W))\). The expression (
) is a pair split
k map(map1,map2)
where all keys in map1
are lower than k
and all keys in
map2
larger than k
. Any key equal to k
is found in neither map1
nor map2
.
split 2 (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3,"b"), (5,"a")]) split 3 (fromList [(5,"a"), (3,"b")]) == (empty, singleton 5 "a") split 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a") split 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", empty) split 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], empty)
splitLookup :: Key -> IntMap a -> (IntMap a, Maybe a, IntMap a) Source #
\(O(\min(n,W))\). Performs a split
but also returns whether the pivot
key was found in the original map.
splitLookup 2 (fromList [(5,"a"), (3,"b")]) == (empty, Nothing, fromList [(3,"b"), (5,"a")]) splitLookup 3 (fromList [(5,"a"), (3,"b")]) == (empty, Just "b", singleton 5 "a") splitLookup 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Nothing, singleton 5 "a") splitLookup 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Just "a", empty) splitLookup 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], Nothing, empty)
splitRoot :: IntMap a -> [IntMap a] Source #
\(O(1)\). Decompose a map into pieces based on the structure of the underlying tree. This function is useful for consuming a map in parallel.
No guarantee is made as to the sizes of the pieces; an internal, but deterministic process determines this. However, it is guaranteed that the pieces returned will be in ascending order (all elements in the first submap less than all elements in the second, and so on).
Examples:
splitRoot (fromList (zip [1..6::Int] ['a'..])) == [fromList [(1,'a'),(2,'b'),(3,'c')],fromList [(4,'d'),(5,'e'),(6,'f')]]
splitRoot empty == []
Note that the current implementation does not return more than two submaps, but you should not depend on this behaviour because it can change in the future without notice.
Submap
isSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool Source #
\(O(n+m)\). Is this a submap?
Defined as (
).isSubmapOf
= isSubmapOfBy
(==)
isSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool Source #
\(O(n+m)\).
The expression (
) returns isSubmapOfBy
f m1 m2True
if
all keys in m1
are in m2
, and when f
returns True
when
applied to their respective values. For example, the following
expressions are all True
:
isSubmapOfBy (==) (fromList [(1,1)]) (fromList [(1,1),(2,2)]) isSubmapOfBy (<=) (fromList [(1,1)]) (fromList [(1,1),(2,2)]) isSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
But the following are all False
:
isSubmapOfBy (==) (fromList [(1,2)]) (fromList [(1,1),(2,2)]) isSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)]) isSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
isProperSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool Source #
\(O(n+m)\). Is this a proper submap? (ie. a submap but not equal).
Defined as (
).isProperSubmapOf
= isProperSubmapOfBy
(==)
isProperSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool Source #
\(O(n+m)\). Is this a proper submap? (ie. a submap but not equal).
The expression (
) returns isProperSubmapOfBy
f m1 m2True
when
keys m1
and keys m2
are not equal,
all keys in m1
are in m2
, and when f
returns True
when
applied to their respective values. For example, the following
expressions are all True
:
isProperSubmapOfBy (==) (fromList [(1,1)]) (fromList [(1,1),(2,2)]) isProperSubmapOfBy (<=) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
But the following are all False
:
isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)]) isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)]) isProperSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
Min/Max
lookupMin :: IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). The minimal key of the map. Returns Nothing
if the map is empty.
lookupMax :: IntMap a -> Maybe (Key, a) Source #
\(O(\min(n,W))\). The maximal key of the map. Returns Nothing
if the map is empty.
findMin :: IntMap a -> (Key, a) Source #
\(O(\min(n,W))\). The minimal key of the map. Calls error
if the map is empty.
Use minViewWithKey
if the map may be empty.
findMax :: IntMap a -> (Key, a) Source #
\(O(\min(n,W))\). The maximal key of the map. Calls error
if the map is empty.
Use maxViewWithKey
if the map may be empty.
deleteFindMin :: IntMap a -> ((Key, a), IntMap a) Source #
\(O(\min(n,W))\). Delete and find the minimal element.
This function throws an error if the map is empty. Use minViewWithKey
if the map may be empty.
deleteFindMax :: IntMap a -> ((Key, a), IntMap a) Source #
\(O(\min(n,W))\). Delete and find the maximal element.
This function throws an error if the map is empty. Use maxViewWithKey
if the map may be empty.
updateMin :: (a -> Maybe a) -> IntMap a -> IntMap a Source #
\(O(\log n)\). Update the value at the minimal key.
updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
updateMax :: (a -> Maybe a) -> IntMap a -> IntMap a Source #
\(O(\log n)\). Update the value at the maximal key.
updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
updateMinWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a Source #
\(O(\log n)\). Update the value at the minimal key.
updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
updateMaxWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a Source #
\(O(\log n)\). Update the value at the maximal key.
updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
minView :: IntMap a -> Maybe (a, IntMap a) Source #
\(O(\min(n,W))\). Retrieves the minimal key of the map, and the map
stripped of that element, or Nothing
if passed an empty map.
maxView :: IntMap a -> Maybe (a, IntMap a) Source #
\(O(\min(n,W))\). Retrieves the maximal key of the map, and the map
stripped of that element, or Nothing
if passed an empty map.
minViewWithKey :: IntMap a -> Maybe ((Key, a), IntMap a) Source #
\(O(\min(n,W))\). Retrieves the minimal (key,value) pair of the map, and
the map stripped of that element, or Nothing
if passed an empty map.
minViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((3,"b"), singleton 5 "a") minViewWithKey empty == Nothing
maxViewWithKey :: IntMap a -> Maybe ((Key, a), IntMap a) Source #
\(O(\min(n,W))\). Retrieves the maximal (key,value) pair of the map, and
the map stripped of that element, or Nothing
if passed an empty map.
maxViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((5,"a"), singleton 3 "b") maxViewWithKey empty == Nothing
Debugging
showTree :: Whoops "Data.IntMap.showTree has moved to Data.IntMap.Internal.Debug.showTree" => IntMap a -> String Source #
showTreeWith :: Whoops "Data.IntMap.showTreeWith has moved to Data.IntMap.Internal.Debug.showTreeWith" => Bool -> Bool -> IntMap a -> String Source #
showTreeWith
has moved to showTreeWith