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