78ccb1472a52d9bd6b23517b010be3efac5ad742
[packages/containers.git] / Data / IntMap / Strict.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE BangPatterns #-}
3 #if !defined(TESTING) && defined(__GLASGOW_HASKELL__)
4 {-# LANGUAGE Trustworthy #-}
5 #endif
6
7 #include "containers.h"
8
9 -----------------------------------------------------------------------------
10 -- |
11 -- Module : Data.IntMap.Strict
12 -- Copyright : (c) Daan Leijen 2002
13 -- (c) Andriy Palamarchuk 2008
14 -- License : BSD-style
15 -- Maintainer : libraries@haskell.org
16 -- Portability : portable
17 --
18 --
19 -- = Finite Int Maps (strict interface)
20 --
21 -- The @'IntMap' v@ type represents a finite map (sometimes called a dictionary)
22 -- from key of type @Int@ to values of type @v@.
23 --
24 -- Each function in this module is careful to force values before installing
25 -- them in an 'IntMap'. This is usually more efficient when laziness is not
26 -- necessary. When laziness /is/ required, use the functions in
27 -- "Data.IntMap.Lazy".
28 --
29 -- In particular, the functions in this module obey the following law:
30 --
31 -- - If all values stored in all maps in the arguments are in WHNF, then all
32 -- values stored in all maps in the results will be in WHNF once those maps
33 -- are evaluated.
34 --
35 -- For a walkthrough of the most commonly used functions see the
36 -- <https://haskell-containers.readthedocs.io/en/latest/map.html maps introduction>.
37 --
38 -- This module is intended to be imported qualified, to avoid name clashes with
39 -- Prelude functions:
40 --
41 -- > import Data.IntMap.Strict (IntMap)
42 -- > import qualified Data.IntMap.Strict as IntMap
43 --
44 -- Note that the implementation is generally /left-biased/. Functions that take
45 -- two maps as arguments and combine them, such as `union` and `intersection`,
46 -- prefer the values in the first argument to those in the second.
47 --
48 --
49 -- == Detailed performance information
50 --
51 -- The amortized running time is given for each operation, with /n/ referring to
52 -- the number of entries in the map and /W/ referring to the number of bits in
53 -- an 'Int' (32 or 64).
54 --
55 -- Benchmarks comparing "Data.IntMap.Strict" with other dictionary
56 -- implementations can be found at https://github.com/haskell-perf/dictionaries.
57 --
58 --
59 -- == Warning
60 --
61 -- The 'IntMap' type is shared between the lazy and strict modules, meaning that
62 -- the same 'IntMap' value can be passed to functions in both modules. This
63 -- means that the 'Functor', 'Traversable' and 'Data.Data.Data' instances are
64 -- the same as for the "Data.IntMap.Lazy" module, so if they are used the
65 -- resulting map may contain suspended values (thunks).
66 --
67 --
68 -- == Implementation
69 --
70 -- The implementation is based on /big-endian patricia trees/. This data
71 -- structure performs especially well on binary operations like 'union' and
72 -- 'intersection'. Additionally, benchmarks show that it is also (much) faster
73 -- on insertions and deletions when compared to a generic size-balanced map
74 -- implementation (see "Data.Map").
75 --
76 -- * Chris Okasaki and Andy Gill, \"/Fast Mergeable Integer Maps/\",
77 -- Workshop on ML, September 1998, pages 77-86,
78 -- <http://citeseer.ist.psu.edu/okasaki98fast.html>
79 --
80 -- * D.R. Morrison, \"/PATRICIA -- Practical Algorithm To Retrieve
81 -- Information Coded In Alphanumeric/\", Journal of the ACM, 15(4),
82 -- October 1968, pages 514-534.
83 --
84 -----------------------------------------------------------------------------
85
86 -- See the notes at the beginning of Data.IntMap.Internal.
87
88 module Data.IntMap.Strict (
89 -- * Map type
90 #if !defined(TESTING)
91 IntMap, Key -- instance Eq,Show
92 #else
93 IntMap(..), Key -- instance Eq,Show
94 #endif
95
96 -- * Construction
97 , empty
98 , singleton
99 , fromSet
100
101 -- ** From Unordered Lists
102 , fromList
103 , fromListWith
104 , fromListWithKey
105
106 -- ** From Ascending Lists
107 , fromAscList
108 , fromAscListWith
109 , fromAscListWithKey
110 , fromDistinctAscList
111
112 -- * Insertion
113 , insert
114 , insertWith
115 , insertWithKey
116 , insertLookupWithKey
117
118 -- * Deletion\/Update
119 , delete
120 , adjust
121 , adjustWithKey
122 , update
123 , updateWithKey
124 , updateLookupWithKey
125 , alter
126 , alterF
127
128 -- * Query
129 -- ** Lookup
130 , lookup
131 , (!?)
132 , (!)
133 , findWithDefault
134 , member
135 , notMember
136 , lookupLT
137 , lookupGT
138 , lookupLE
139 , lookupGE
140
141 -- ** Size
142 , null
143 , size
144
145 -- * Combine
146
147 -- ** Union
148 , union
149 , unionWith
150 , unionWithKey
151 , unions
152 , unionsWith
153
154 -- ** Difference
155 , difference
156 , (\\)
157 , differenceWith
158 , differenceWithKey
159
160 -- ** Intersection
161 , intersection
162 , intersectionWith
163 , intersectionWithKey
164
165 -- ** Universal combining function
166 , mergeWithKey
167
168 -- * Traversal
169 -- ** Map
170 , map
171 , mapWithKey
172 , traverseWithKey
173 , mapAccum
174 , mapAccumWithKey
175 , mapAccumRWithKey
176 , mapKeys
177 , mapKeysWith
178 , mapKeysMonotonic
179
180 -- * Folds
181 , foldr
182 , foldl
183 , foldrWithKey
184 , foldlWithKey
185 , foldMapWithKey
186
187 -- ** Strict folds
188 , foldr'
189 , foldl'
190 , foldrWithKey'
191 , foldlWithKey'
192
193 -- * Conversion
194 , elems
195 , keys
196 , assocs
197 , keysSet
198
199 -- ** Lists
200 , toList
201
202 -- ** Ordered lists
203 , toAscList
204 , toDescList
205
206 -- * Filter
207 , filter
208 , filterWithKey
209 , restrictKeys
210 , withoutKeys
211 , partition
212 , partitionWithKey
213
214 , mapMaybe
215 , mapMaybeWithKey
216 , mapEither
217 , mapEitherWithKey
218
219 , split
220 , splitLookup
221 , splitRoot
222
223 -- * Submap
224 , isSubmapOf, isSubmapOfBy
225 , isProperSubmapOf, isProperSubmapOfBy
226
227 -- * Min\/Max
228 , lookupMin
229 , lookupMax
230 , findMin
231 , findMax
232 , deleteMin
233 , deleteMax
234 , deleteFindMin
235 , deleteFindMax
236 , updateMin
237 , updateMax
238 , updateMinWithKey
239 , updateMaxWithKey
240 , minView
241 , maxView
242 , minViewWithKey
243 , maxViewWithKey
244
245 #ifdef __GLASGOW_HASKELL__
246 -- * Debugging
247 , showTree
248 , showTreeWith
249 #endif
250 ) where
251
252 import Prelude hiding (lookup,map,filter,foldr,foldl,null)
253
254 import Data.Bits
255 import qualified Data.IntMap.Internal as L
256 import Data.IntMap.Internal
257 ( IntMap (..)
258 , Key
259 , Prefix
260 , Mask
261 , mask
262 , branchMask
263 , shorter
264 , nomatch
265 , zero
266 , natFromInt
267 , intFromNat
268 , bin
269 , binCheckLeft
270 , binCheckRight
271 , link
272
273 , (\\)
274 , (!)
275 , (!?)
276 , empty
277 , assocs
278 , filter
279 , filterWithKey
280 , findMin
281 , findMax
282 , foldMapWithKey
283 , foldr
284 , foldl
285 , foldr'
286 , foldl'
287 , foldlWithKey
288 , foldrWithKey
289 , foldlWithKey'
290 , foldrWithKey'
291 , keysSet
292 , mergeWithKey'
293 , delete
294 , deleteMin
295 , deleteMax
296 , deleteFindMax
297 , deleteFindMin
298 , difference
299 , elems
300 , intersection
301 , isProperSubmapOf
302 , isProperSubmapOfBy
303 , isSubmapOf
304 , isSubmapOfBy
305 , lookup
306 , lookupLE
307 , lookupGE
308 , lookupLT
309 , lookupGT
310 , lookupMin
311 , lookupMax
312 , minView
313 , maxView
314 , minViewWithKey
315 , maxViewWithKey
316 , keys
317 , mapKeys
318 , mapKeysMonotonic
319 , member
320 , notMember
321 , null
322 , partition
323 , partitionWithKey
324 , restrictKeys
325 , size
326 , split
327 , splitLookup
328 , splitRoot
329 , toAscList
330 , toDescList
331 , toList
332 , union
333 , unions
334 , withoutKeys
335 )
336 #ifdef __GLASGOW_HASKELL__
337 import Data.IntMap.Internal.DeprecatedDebug (showTree, showTreeWith)
338 #endif
339 import qualified Data.IntSet.Internal as IntSet
340 import Utils.Containers.Internal.BitUtil
341 import Utils.Containers.Internal.StrictPair
342 #if !MIN_VERSION_base(4,8,0)
343 import Data.Functor((<$>))
344 #endif
345 import Control.Applicative (Applicative (..), liftA2)
346 import qualified Data.Foldable as Foldable
347 #if !MIN_VERSION_base(4,8,0)
348 import Data.Foldable (Foldable())
349 #endif
350
351 {--------------------------------------------------------------------
352 Query
353 --------------------------------------------------------------------}
354
355 -- | /O(min(n,W))/. The expression @('findWithDefault' def k map)@
356 -- returns the value at key @k@ or returns @def@ when the key is not an
357 -- element of the map.
358 --
359 -- > findWithDefault 'x' 1 (fromList [(5,'a'), (3,'b')]) == 'x'
360 -- > findWithDefault 'x' 5 (fromList [(5,'a'), (3,'b')]) == 'a'
361
362 -- See IntMap.Internal.Note: Local 'go' functions and capturing]
363 findWithDefault :: a -> Key -> IntMap a -> a
364 findWithDefault def !k = go
365 where
366 go (Bin p m l r) | nomatch k p m = def
367 | zero k m = go l
368 | otherwise = go r
369 go (Tip kx x) | k == kx = x
370 | otherwise = def
371 go Nil = def
372
373 {--------------------------------------------------------------------
374 Construction
375 --------------------------------------------------------------------}
376 -- | /O(1)/. A map of one element.
377 --
378 -- > singleton 1 'a' == fromList [(1, 'a')]
379 -- > size (singleton 1 'a') == 1
380
381 singleton :: Key -> a -> IntMap a
382 singleton k !x
383 = Tip k x
384 {-# INLINE singleton #-}
385
386 {--------------------------------------------------------------------
387 Insert
388 --------------------------------------------------------------------}
389 -- | /O(min(n,W))/. Insert a new key\/value pair in the map.
390 -- If the key is already present in the map, the associated value is
391 -- replaced with the supplied value, i.e. 'insert' is equivalent to
392 -- @'insertWith' 'const'@.
393 --
394 -- > insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')]
395 -- > insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')]
396 -- > insert 5 'x' empty == singleton 5 'x'
397
398 insert :: Key -> a -> IntMap a -> IntMap a
399 insert !k !x t =
400 case t of
401 Bin p m l r
402 | nomatch k p m -> link k (Tip k x) p t
403 | zero k m -> Bin p m (insert k x l) r
404 | otherwise -> Bin p m l (insert k x r)
405 Tip ky _
406 | k==ky -> Tip k x
407 | otherwise -> link k (Tip k x) ky t
408 Nil -> Tip k x
409
410 -- right-biased insertion, used by 'union'
411 -- | /O(min(n,W))/. Insert with a combining function.
412 -- @'insertWith' f key value mp@
413 -- will insert the pair (key, value) into @mp@ if key does
414 -- not exist in the map. If the key does exist, the function will
415 -- insert @f new_value old_value@.
416 --
417 -- > insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")]
418 -- > insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
419 -- > insertWith (++) 5 "xxx" empty == singleton 5 "xxx"
420
421 insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
422 insertWith f k x t
423 = insertWithKey (\_ x' y' -> f x' y') k x t
424
425 -- | /O(min(n,W))/. Insert with a combining function.
426 -- @'insertWithKey' f key value mp@
427 -- will insert the pair (key, value) into @mp@ if key does
428 -- not exist in the map. If the key does exist, the function will
429 -- insert @f key new_value old_value@.
430 --
431 -- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
432 -- > insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")]
433 -- > insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
434 -- > insertWithKey f 5 "xxx" empty == singleton 5 "xxx"
435 --
436 -- If the key exists in the map, this function is lazy in @value@ but strict
437 -- in the result of @f@.
438
439 insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
440 insertWithKey f !k x t =
441 case t of
442 Bin p m l r
443 | nomatch k p m -> link k (singleton k x) p t
444 | zero k m -> Bin p m (insertWithKey f k x l) r
445 | otherwise -> Bin p m l (insertWithKey f k x r)
446 Tip ky y
447 | k==ky -> Tip k $! f k x y
448 | otherwise -> link k (singleton k x) ky t
449 Nil -> singleton k x
450
451 -- | /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@)
452 -- is a pair where the first element is equal to (@'lookup' k map@)
453 -- and the second element equal to (@'insertWithKey' f k x map@).
454 --
455 -- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
456 -- > insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")])
457 -- > insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "xxx")])
458 -- > insertLookupWithKey f 5 "xxx" empty == (Nothing, singleton 5 "xxx")
459 --
460 -- This is how to define @insertLookup@ using @insertLookupWithKey@:
461 --
462 -- > let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t
463 -- > insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")])
464 -- > insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "x")])
465
466 insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> (Maybe a, IntMap a)
467 insertLookupWithKey f0 !k0 x0 t0 = toPair $ go f0 k0 x0 t0
468 where
469 go f k x t =
470 case t of
471 Bin p m l r
472 | nomatch k p m -> Nothing :*: link k (singleton k x) p t
473 | zero k m -> let (found :*: l') = go f k x l in (found :*: Bin p m l' r)
474 | otherwise -> let (found :*: r') = go f k x r in (found :*: Bin p m l r')
475 Tip ky y
476 | k==ky -> (Just y :*: (Tip k $! f k x y))
477 | otherwise -> (Nothing :*: link k (singleton k x) ky t)
478 Nil -> Nothing :*: (singleton k x)
479
480
481 {--------------------------------------------------------------------
482 Deletion
483 --------------------------------------------------------------------}
484 -- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not
485 -- a member of the map, the original map is returned.
486 --
487 -- > adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")]
488 -- > adjust ("new " ++) 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
489 -- > adjust ("new " ++) 7 empty == empty
490
491 adjust :: (a -> a) -> Key -> IntMap a -> IntMap a
492 adjust f k m
493 = adjustWithKey (\_ x -> f x) k m
494
495 -- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not
496 -- a member of the map, the original map is returned.
497 --
498 -- > let f key x = (show key) ++ ":new " ++ x
499 -- > adjustWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")]
500 -- > adjustWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
501 -- > adjustWithKey f 7 empty == empty
502
503 adjustWithKey :: (Key -> a -> a) -> Key -> IntMap a -> IntMap a
504 adjustWithKey f !k t =
505 case t of
506 Bin p m l r
507 | nomatch k p m -> t
508 | zero k m -> Bin p m (adjustWithKey f k l) r
509 | otherwise -> Bin p m l (adjustWithKey f k r)
510 Tip ky y
511 | k==ky -> Tip ky $! f k y
512 | otherwise -> t
513 Nil -> Nil
514
515 -- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
516 -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is
517 -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
518 --
519 -- > let f x = if x == "a" then Just "new a" else Nothing
520 -- > update f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")]
521 -- > update f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
522 -- > update f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
523
524 update :: (a -> Maybe a) -> Key -> IntMap a -> IntMap a
525 update f
526 = updateWithKey (\_ x -> f x)
527
528 -- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
529 -- at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is
530 -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
531 --
532 -- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
533 -- > updateWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")]
534 -- > updateWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
535 -- > updateWithKey f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
536
537 updateWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> IntMap a
538 updateWithKey f !k t =
539 case t of
540 Bin p m l r
541 | nomatch k p m -> t
542 | zero k m -> binCheckLeft p m (updateWithKey f k l) r
543 | otherwise -> binCheckRight p m l (updateWithKey f k r)
544 Tip ky y
545 | k==ky -> case f k y of
546 Just !y' -> Tip ky y'
547 Nothing -> Nil
548 | otherwise -> t
549 Nil -> Nil
550
551 -- | /O(min(n,W))/. Lookup and update.
552 -- The function returns original value, if it is updated.
553 -- This is different behavior than 'Data.Map.updateLookupWithKey'.
554 -- Returns the original key value if the map entry is deleted.
555 --
556 -- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
557 -- > updateLookupWithKey f 5 (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:new a")])
558 -- > updateLookupWithKey f 7 (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a")])
559 -- > updateLookupWithKey f 3 (fromList [(5,"a"), (3,"b")]) == (Just "b", singleton 5 "a")
560
561 updateLookupWithKey :: (Key -> a -> Maybe a) -> Key -> IntMap a -> (Maybe a,IntMap a)
562 updateLookupWithKey f0 !k0 t0 = toPair $ go f0 k0 t0
563 where
564 go f k t =
565 case t of
566 Bin p m l r
567 | nomatch k p m -> (Nothing :*: t)
568 | zero k m -> let (found :*: l') = go f k l in (found :*: binCheckLeft p m l' r)
569 | otherwise -> let (found :*: r') = go f k r in (found :*: binCheckRight p m l r')
570 Tip ky y
571 | k==ky -> case f k y of
572 Just !y' -> (Just y :*: Tip ky y')
573 Nothing -> (Just y :*: Nil)
574 | otherwise -> (Nothing :*: t)
575 Nil -> (Nothing :*: Nil)
576
577
578
579 -- | /O(min(n,W))/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
580 -- 'alter' can be used to insert, delete, or update a value in an 'IntMap'.
581 -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@.
582 alter :: (Maybe a -> Maybe a) -> Key -> IntMap a -> IntMap a
583 alter f !k t =
584 case t of
585 Bin p m l r
586 | nomatch k p m -> case f Nothing of
587 Nothing -> t
588 Just !x -> link k (Tip k x) p t
589 | zero k m -> binCheckLeft p m (alter f k l) r
590 | otherwise -> binCheckRight p m l (alter f k r)
591 Tip ky y
592 | k==ky -> case f (Just y) of
593 Just !x -> Tip ky x
594 Nothing -> Nil
595 | otherwise -> case f Nothing of
596 Just !x -> link k (Tip k x) ky t
597 Nothing -> t
598 Nil -> case f Nothing of
599 Just !x -> Tip k x
600 Nothing -> Nil
601
602 -- | /O(log n)/. The expression (@'alterF' f k map@) alters the value @x@ at
603 -- @k@, or absence thereof. 'alterF' can be used to inspect, insert, delete,
604 -- or update a value in an 'IntMap'. In short : @'lookup' k <$> 'alterF' f k m = f
605 -- ('lookup' k m)@.
606 --
607 -- Example:
608 --
609 -- @
610 -- interactiveAlter :: Int -> IntMap String -> IO (IntMap String)
611 -- interactiveAlter k m = alterF f k m where
612 -- f Nothing = do
613 -- putStrLn $ show k ++
614 -- " was not found in the map. Would you like to add it?"
615 -- getUserResponse1 :: IO (Maybe String)
616 -- f (Just old) = do
617 -- putStrLn $ "The key is currently bound to " ++ show old ++
618 -- ". Would you like to change or delete it?"
619 -- getUserResponse2 :: IO (Maybe String)
620 -- @
621 --
622 -- 'alterF' is the most general operation for working with an individual
623 -- key that may or may not be in a given map.
624
625 -- Note: 'alterF' is a flipped version of the 'at' combinator from
626 -- 'Control.Lens.At'.
627 --
628 -- @since 0.5.8
629
630 alterF :: Functor f
631 => (Maybe a -> f (Maybe a)) -> Key -> IntMap a -> f (IntMap a)
632 -- This implementation was modified from 'Control.Lens.At'.
633 alterF f k m = (<$> f mv) $ \fres ->
634 case fres of
635 Nothing -> maybe m (const (delete k m)) mv
636 Just !v' -> insert k v' m
637 where mv = lookup k m
638
639
640 {--------------------------------------------------------------------
641 Union
642 --------------------------------------------------------------------}
643 -- | The union of a list of maps, with a combining operation.
644 --
645 -- > unionsWith (++) [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])]
646 -- > == fromList [(3, "bB3"), (5, "aAA3"), (7, "C")]
647
648 unionsWith :: Foldable f => (a->a->a) -> f (IntMap a) -> IntMap a
649 unionsWith f ts
650 = Foldable.foldl' (unionWith f) empty ts
651
652 -- | /O(n+m)/. The union with a combining function.
653 --
654 -- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")]
655
656 unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
657 unionWith f m1 m2
658 = unionWithKey (\_ x y -> f x y) m1 m2
659
660 -- | /O(n+m)/. The union with a combining function.
661 --
662 -- > let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value
663 -- > unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")]
664
665 unionWithKey :: (Key -> a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
666 unionWithKey f m1 m2
667 = mergeWithKey' Bin (\(Tip k1 x1) (Tip _k2 x2) -> Tip k1 $! f k1 x1 x2) id id m1 m2
668
669 {--------------------------------------------------------------------
670 Difference
671 --------------------------------------------------------------------}
672
673 -- | /O(n+m)/. Difference with a combining function.
674 --
675 -- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
676 -- > differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")])
677 -- > == singleton 3 "b:B"
678
679 differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
680 differenceWith f m1 m2
681 = differenceWithKey (\_ x y -> f x y) m1 m2
682
683 -- | /O(n+m)/. Difference with a combining function. When two equal keys are
684 -- encountered, the combining function is applied to the key and both values.
685 -- If it returns 'Nothing', the element is discarded (proper set difference).
686 -- If it returns (@'Just' y@), the element is updated with a new value @y@.
687 --
688 -- > let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing
689 -- > differenceWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (10, "C")])
690 -- > == singleton 3 "3:b|B"
691
692 differenceWithKey :: (Key -> a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
693 differenceWithKey f m1 m2
694 = mergeWithKey f id (const Nil) m1 m2
695
696 {--------------------------------------------------------------------
697 Intersection
698 --------------------------------------------------------------------}
699
700 -- | /O(n+m)/. The intersection with a combining function.
701 --
702 -- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA"
703
704 intersectionWith :: (a -> b -> c) -> IntMap a -> IntMap b -> IntMap c
705 intersectionWith f m1 m2
706 = intersectionWithKey (\_ x y -> f x y) m1 m2
707
708 -- | /O(n+m)/. The intersection with a combining function.
709 --
710 -- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar
711 -- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A"
712
713 intersectionWithKey :: (Key -> a -> b -> c) -> IntMap a -> IntMap b -> IntMap c
714 intersectionWithKey f m1 m2
715 = mergeWithKey' bin (\(Tip k1 x1) (Tip _k2 x2) -> Tip k1 $! f k1 x1 x2) (const Nil) (const Nil) m1 m2
716
717 {--------------------------------------------------------------------
718 MergeWithKey
719 --------------------------------------------------------------------}
720
721 -- | /O(n+m)/. A high-performance universal combining function. Using
722 -- 'mergeWithKey', all combining functions can be defined without any loss of
723 -- efficiency (with exception of 'union', 'difference' and 'intersection',
724 -- where sharing of some nodes is lost with 'mergeWithKey').
725 --
726 -- Please make sure you know what is going on when using 'mergeWithKey',
727 -- otherwise you can be surprised by unexpected code growth or even
728 -- corruption of the data structure.
729 --
730 -- When 'mergeWithKey' is given three arguments, it is inlined to the call
731 -- site. You should therefore use 'mergeWithKey' only to define your custom
732 -- combining functions. For example, you could define 'unionWithKey',
733 -- 'differenceWithKey' and 'intersectionWithKey' as
734 --
735 -- > myUnionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -> Just (f k x1 x2)) id id m1 m2
736 -- > myDifferenceWithKey f m1 m2 = mergeWithKey f id (const empty) m1 m2
737 -- > myIntersectionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -> Just (f k x1 x2)) (const empty) (const empty) m1 m2
738 --
739 -- When calling @'mergeWithKey' combine only1 only2@, a function combining two
740 -- 'IntMap's is created, such that
741 --
742 -- * if a key is present in both maps, it is passed with both corresponding
743 -- values to the @combine@ function. Depending on the result, the key is either
744 -- present in the result with specified value, or is left out;
745 --
746 -- * a nonempty subtree present only in the first map is passed to @only1@ and
747 -- the output is added to the result;
748 --
749 -- * a nonempty subtree present only in the second map is passed to @only2@ and
750 -- the output is added to the result.
751 --
752 -- The @only1@ and @only2@ methods /must return a map with a subset (possibly empty) of the keys of the given map/.
753 -- The values can be modified arbitrarily. Most common variants of @only1@ and
754 -- @only2@ are 'id' and @'const' 'empty'@, but for example @'map' f@ or
755 -- @'filterWithKey' f@ could be used for any @f@.
756
757 mergeWithKey :: (Key -> a -> b -> Maybe c) -> (IntMap a -> IntMap c) -> (IntMap b -> IntMap c)
758 -> IntMap a -> IntMap b -> IntMap c
759 mergeWithKey f g1 g2 = mergeWithKey' bin combine g1 g2
760 where -- We use the lambda form to avoid non-exhaustive pattern matches warning.
761 combine = \(Tip k1 x1) (Tip _k2 x2) -> case f k1 x1 x2 of Nothing -> Nil
762 Just !x -> Tip k1 x
763 {-# INLINE combine #-}
764 {-# INLINE mergeWithKey #-}
765
766 {--------------------------------------------------------------------
767 Min\/Max
768 --------------------------------------------------------------------}
769
770 -- | /O(log n)/. Update the value at the minimal key.
771 --
772 -- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")]
773 -- > updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
774
775 updateMinWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a
776 updateMinWithKey f t =
777 case t of Bin p m l r | m < 0 -> binCheckRight p m l (go f r)
778 _ -> go f t
779 where
780 go f' (Bin p m l r) = binCheckLeft p m (go f' l) r
781 go f' (Tip k y) = case f' k y of
782 Just !y' -> Tip k y'
783 Nothing -> Nil
784 go _ Nil = error "updateMinWithKey Nil"
785
786 -- | /O(log n)/. Update the value at the maximal key.
787 --
788 -- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")]
789 -- > updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
790
791 updateMaxWithKey :: (Key -> a -> Maybe a) -> IntMap a -> IntMap a
792 updateMaxWithKey f t =
793 case t of Bin p m l r | m < 0 -> binCheckLeft p m (go f l) r
794 _ -> go f t
795 where
796 go f' (Bin p m l r) = binCheckRight p m l (go f' r)
797 go f' (Tip k y) = case f' k y of
798 Just !y' -> Tip k y'
799 Nothing -> Nil
800 go _ Nil = error "updateMaxWithKey Nil"
801
802 -- | /O(log n)/. Update the value at the maximal key.
803 --
804 -- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")]
805 -- > updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
806
807 updateMax :: (a -> Maybe a) -> IntMap a -> IntMap a
808 updateMax f = updateMaxWithKey (const f)
809
810 -- | /O(log n)/. Update the value at the minimal key.
811 --
812 -- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")]
813 -- > updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
814
815 updateMin :: (a -> Maybe a) -> IntMap a -> IntMap a
816 updateMin f = updateMinWithKey (const f)
817
818
819 {--------------------------------------------------------------------
820 Mapping
821 --------------------------------------------------------------------}
822 -- | /O(n)/. Map a function over all values in the map.
823 --
824 -- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")]
825
826 map :: (a -> b) -> IntMap a -> IntMap b
827 map f = go
828 where
829 go (Bin p m l r) = Bin p m (go l) (go r)
830 go (Tip k x) = Tip k $! f x
831 go Nil = Nil
832
833 #ifdef __GLASGOW_HASKELL__
834 {-# NOINLINE [1] map #-}
835 {-# RULES
836 "map/map" forall f g xs . map f (map g xs) = map (\x -> f $! g x) xs
837 "map/mapL" forall f g xs . map f (L.map g xs) = map (\x -> f (g x)) xs
838 #-}
839 #endif
840
841 -- | /O(n)/. Map a function over all values in the map.
842 --
843 -- > let f key x = (show key) ++ ":" ++ x
844 -- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")]
845
846 mapWithKey :: (Key -> a -> b) -> IntMap a -> IntMap b
847 mapWithKey f t
848 = case t of
849 Bin p m l r -> Bin p m (mapWithKey f l) (mapWithKey f r)
850 Tip k x -> Tip k $! f k x
851 Nil -> Nil
852
853 #ifdef __GLASGOW_HASKELL__
854 -- Pay close attention to strictness here. We need to force the
855 -- intermediate result for map f . map g, and we need to refrain
856 -- from forcing it for map f . L.map g, etc.
857 --
858 -- TODO Consider moving map and mapWithKey to IntMap.Internal so we can write
859 -- non-orphan RULES for things like L.map f (map g xs). We'd need a new function
860 -- for this, and we'd have to pay attention to simplifier phases. Something like
861 --
862 -- lsmap :: (b -> c) -> (a -> b) -> IntMap a -> IntMap c
863 -- lsmap _ _ Nil = Nil
864 -- lsmap f g (Tip k x) = let !gx = g x in Tip k (f gx)
865 -- lsmap f g (Bin p m l r) = Bin p m (lsmap f g l) (lsmap f g r)
866 {-# NOINLINE [1] mapWithKey #-}
867 {-# RULES
868 "mapWithKey/mapWithKey" forall f g xs . mapWithKey f (mapWithKey g xs) =
869 mapWithKey (\k a -> f k $! g k a) xs
870 "mapWithKey/mapWithKeyL" forall f g xs . mapWithKey f (L.mapWithKey g xs) =
871 mapWithKey (\k a -> f k (g k a)) xs
872 "mapWithKey/map" forall f g xs . mapWithKey f (map g xs) =
873 mapWithKey (\k a -> f k $! g a) xs
874 "mapWithKey/mapL" forall f g xs . mapWithKey f (L.map g xs) =
875 mapWithKey (\k a -> f k (g a)) xs
876 "map/mapWithKey" forall f g xs . map f (mapWithKey g xs) =
877 mapWithKey (\k a -> f $! g k a) xs
878 "map/mapWithKeyL" forall f g xs . map f (L.mapWithKey g xs) =
879 mapWithKey (\k a -> f (g k a)) xs
880 #-}
881 #endif
882
883 -- | /O(n)/.
884 -- @'traverseWithKey' f s == 'fromList' <$> 'traverse' (\(k, v) -> (,) k <$> f k v) ('toList' m)@
885 -- That is, behaves exactly like a regular 'traverse' except that the traversing
886 -- function also has access to the key associated with a value.
887 --
888 -- > traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(1, 'a'), (5, 'e')]) == Just (fromList [(1, 'b'), (5, 'f')])
889 -- > traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(2, 'c')]) == Nothing
890 traverseWithKey :: Applicative t => (Key -> a -> t b) -> IntMap a -> t (IntMap b)
891 traverseWithKey f = go
892 where
893 go Nil = pure Nil
894 go (Tip k v) = (\ !v' -> Tip k v') <$> f k v
895 go (Bin p m l r) = liftA2 (Bin p m) (go l) (go r)
896 {-# INLINE traverseWithKey #-}
897
898 -- | /O(n)/. The function @'mapAccum'@ threads an accumulating
899 -- argument through the map in ascending order of keys.
900 --
901 -- > let f a b = (a ++ b, b ++ "X")
902 -- > mapAccum f "Everything: " (fromList [(5,"a"), (3,"b")]) == ("Everything: ba", fromList [(3, "bX"), (5, "aX")])
903
904 mapAccum :: (a -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
905 mapAccum f = mapAccumWithKey (\a' _ x -> f a' x)
906
907 -- | /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating
908 -- argument through the map in ascending order of keys.
909 --
910 -- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
911 -- > mapAccumWithKey f "Everything:" (fromList [(5,"a"), (3,"b")]) == ("Everything: 3-b 5-a", fromList [(3, "bX"), (5, "aX")])
912
913 mapAccumWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
914 mapAccumWithKey f a t
915 = mapAccumL f a t
916
917 -- | /O(n)/. The function @'mapAccumL'@ threads an accumulating
918 -- argument through the map in ascending order of keys. Strict in
919 -- the accumulating argument and the both elements of the
920 -- result of the function.
921 mapAccumL :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
922 mapAccumL f0 a0 t0 = toPair $ go f0 a0 t0
923 where
924 go f a t
925 = case t of
926 Bin p m l r -> let (a1 :*: l') = go f a l
927 (a2 :*: r') = go f a1 r
928 in (a2 :*: Bin p m l' r')
929 Tip k x -> let !(a',!x') = f a k x in (a' :*: Tip k x')
930 Nil -> (a :*: Nil)
931
932 -- | /O(n)/. The function @'mapAccumR'@ threads an accumulating
933 -- argument through the map in descending order of keys.
934 mapAccumRWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
935 mapAccumRWithKey f0 a0 t0 = toPair $ go f0 a0 t0
936 where
937 go f a t
938 = case t of
939 Bin p m l r -> let (a1 :*: r') = go f a r
940 (a2 :*: l') = go f a1 l
941 in (a2 :*: Bin p m l' r')
942 Tip k x -> let !(a',!x') = f a k x in (a' :*: Tip k x')
943 Nil -> (a :*: Nil)
944
945 -- | /O(n*log n)/.
946 -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@.
947 --
948 -- The size of the result may be smaller if @f@ maps two or more distinct
949 -- keys to the same new key. In this case the associated values will be
950 -- combined using @c@.
951 --
952 -- > mapKeysWith (++) (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "cdab"
953 -- > mapKeysWith (++) (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "cdab"
954
955 mapKeysWith :: (a -> a -> a) -> (Key->Key) -> IntMap a -> IntMap a
956 mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) []
957
958 {--------------------------------------------------------------------
959 Filter
960 --------------------------------------------------------------------}
961 -- | /O(n)/. Map values and collect the 'Just' results.
962 --
963 -- > let f x = if x == "a" then Just "new a" else Nothing
964 -- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a"
965
966 mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b
967 mapMaybe f = mapMaybeWithKey (\_ x -> f x)
968
969 -- | /O(n)/. Map keys\/values and collect the 'Just' results.
970 --
971 -- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing
972 -- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3"
973
974 mapMaybeWithKey :: (Key -> a -> Maybe b) -> IntMap a -> IntMap b
975 mapMaybeWithKey f (Bin p m l r)
976 = bin p m (mapMaybeWithKey f l) (mapMaybeWithKey f r)
977 mapMaybeWithKey f (Tip k x) = case f k x of
978 Just !y -> Tip k y
979 Nothing -> Nil
980 mapMaybeWithKey _ Nil = Nil
981
982 -- | /O(n)/. Map values and separate the 'Left' and 'Right' results.
983 --
984 -- > let f a = if a < "c" then Left a else Right a
985 -- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
986 -- > == (fromList [(3,"b"), (5,"a")], fromList [(1,"x"), (7,"z")])
987 -- >
988 -- > mapEither (\ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
989 -- > == (empty, fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
990
991 mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
992 mapEither f m
993 = mapEitherWithKey (\_ x -> f x) m
994
995 -- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results.
996 --
997 -- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a)
998 -- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
999 -- > == (fromList [(1,2), (3,6)], fromList [(5,"aa"), (7,"zz")])
1000 -- >
1001 -- > mapEitherWithKey (\_ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
1002 -- > == (empty, fromList [(1,"x"), (3,"b"), (5,"a"), (7,"z")])
1003
1004 mapEitherWithKey :: (Key -> a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
1005 mapEitherWithKey f0 t0 = toPair $ go f0 t0
1006 where
1007 go f (Bin p m l r)
1008 = bin p m l1 r1 :*: bin p m l2 r2
1009 where
1010 (l1 :*: l2) = go f l
1011 (r1 :*: r2) = go f r
1012 go f (Tip k x) = case f k x of
1013 Left !y -> (Tip k y :*: Nil)
1014 Right !z -> (Nil :*: Tip k z)
1015 go _ Nil = (Nil :*: Nil)
1016
1017 {--------------------------------------------------------------------
1018 Conversions
1019 --------------------------------------------------------------------}
1020
1021 -- | /O(n)/. Build a map from a set of keys and a function which for each key
1022 -- computes its value.
1023 --
1024 -- > fromSet (\k -> replicate k 'a') (Data.IntSet.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")]
1025 -- > fromSet undefined Data.IntSet.empty == empty
1026
1027 fromSet :: (Key -> a) -> IntSet.IntSet -> IntMap a
1028 fromSet _ IntSet.Nil = Nil
1029 fromSet f (IntSet.Bin p m l r) = Bin p m (fromSet f l) (fromSet f r)
1030 fromSet f (IntSet.Tip kx bm) = buildTree f kx bm (IntSet.suffixBitMask + 1)
1031 where -- This is slightly complicated, as we to convert the dense
1032 -- representation of IntSet into tree representation of IntMap.
1033 --
1034 -- We are given a nonzero bit mask 'bmask' of 'bits' bits with prefix 'prefix'.
1035 -- We split bmask into halves corresponding to left and right subtree.
1036 -- If they are both nonempty, we create a Bin node, otherwise exactly
1037 -- one of them is nonempty and we construct the IntMap from that half.
1038 buildTree g !prefix !bmask bits = case bits of
1039 0 -> Tip prefix $! g prefix
1040 _ -> case intFromNat ((natFromInt bits) `shiftRL` 1) of
1041 bits2 | bmask .&. ((1 `shiftLL` bits2) - 1) == 0 ->
1042 buildTree g (prefix + bits2) (bmask `shiftRL` bits2) bits2
1043 | (bmask `shiftRL` bits2) .&. ((1 `shiftLL` bits2) - 1) == 0 ->
1044 buildTree g prefix bmask bits2
1045 | otherwise ->
1046 Bin prefix bits2 (buildTree g prefix bmask bits2) (buildTree g (prefix + bits2) (bmask `shiftRL` bits2) bits2)
1047
1048 {--------------------------------------------------------------------
1049 Lists
1050 --------------------------------------------------------------------}
1051 -- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs.
1052 --
1053 -- > fromList [] == empty
1054 -- > fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")]
1055 -- > fromList [(5,"c"), (3,"b"), (5, "a")] == fromList [(5,"a"), (3,"b")]
1056
1057 fromList :: [(Key,a)] -> IntMap a
1058 fromList xs
1059 = Foldable.foldl' ins empty xs
1060 where
1061 ins t (k,x) = insert k x t
1062
1063 -- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
1064 --
1065 -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")]
1066 -- > fromListWith (++) [] == empty
1067
1068 fromListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a
1069 fromListWith f xs
1070 = fromListWithKey (\_ x y -> f x y) xs
1071
1072 -- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'.
1073 --
1074 -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")]
1075 -- > fromListWith (++) [] == empty
1076
1077 fromListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a
1078 fromListWithKey f xs
1079 = Foldable.foldl' ins empty xs
1080 where
1081 ins t (k,x) = insertWithKey f k x t
1082
1083 -- | /O(n)/. Build a map from a list of key\/value pairs where
1084 -- the keys are in ascending order.
1085 --
1086 -- > fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
1087 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
1088
1089 fromAscList :: [(Key,a)] -> IntMap a
1090 fromAscList xs
1091 = fromAscListWithKey (\_ x _ -> x) xs
1092
1093 -- | /O(n)/. Build a map from a list of key\/value pairs where
1094 -- the keys are in ascending order, with a combining function on equal keys.
1095 -- /The precondition (input list is ascending) is not checked./
1096 --
1097 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
1098
1099 fromAscListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a
1100 fromAscListWith f xs
1101 = fromAscListWithKey (\_ x y -> f x y) xs
1102
1103 -- | /O(n)/. Build a map from a list of key\/value pairs where
1104 -- the keys are in ascending order, with a combining function on equal keys.
1105 -- /The precondition (input list is ascending) is not checked./
1106 --
1107 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
1108
1109 fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a
1110 fromAscListWithKey _ [] = Nil
1111 fromAscListWithKey f (x0 : xs0) = fromDistinctAscList (combineEq x0 xs0)
1112 where
1113 -- [combineEq f xs] combines equal elements with function [f] in an ordered list [xs]
1114 combineEq z [] = [z]
1115 combineEq z@(kz,zz) (x@(kx,xx):xs)
1116 | kx==kz = let !yy = f kx xx zz in combineEq (kx,yy) xs
1117 | otherwise = z:combineEq x xs
1118
1119 -- | /O(n)/. Build a map from a list of key\/value pairs where
1120 -- the keys are in ascending order and all distinct.
1121 -- /The precondition (input list is strictly ascending) is not checked./
1122 --
1123 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
1124
1125 fromDistinctAscList :: [(Key,a)] -> IntMap a
1126 fromDistinctAscList [] = Nil
1127 fromDistinctAscList (z0 : zs0) = work z0 zs0 Nada
1128 where
1129 work (kx,!vx) [] stk = finish kx (Tip kx vx) stk
1130 work (kx,!vx) (z@(kz,_):zs) stk = reduce z zs (branchMask kx kz) kx (Tip kx vx) stk
1131
1132 reduce :: (Key,a) -> [(Key,a)] -> Mask -> Prefix -> IntMap a -> Stack a -> IntMap a
1133 reduce z zs _ px tx Nada = work z zs (Push px tx Nada)
1134 reduce z zs m px tx stk@(Push py ty stk') =
1135 let mxy = branchMask px py
1136 pxy = mask px mxy
1137 in if shorter m mxy
1138 then reduce z zs m pxy (Bin pxy mxy ty tx) stk'
1139 else work z zs (Push px tx stk)
1140
1141 finish _ t Nada = t
1142 finish px tx (Push py ty stk) = finish p (link py ty px tx) stk
1143 where m = branchMask px py
1144 p = mask px m
1145
1146 data Stack a = Push {-# UNPACK #-} !Prefix !(IntMap a) !(Stack a) | Nada