Update changelog.md
[packages/containers.git] / Data / Set / Base.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE BangPatterns #-}
3 #if __GLASGOW_HASKELL__
4 {-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
5 #endif
6 #if !defined(TESTING) && __GLASGOW_HASKELL__ >= 703
7 {-# LANGUAGE Trustworthy #-}
8 #endif
9 #if __GLASGOW_HASKELL__ >= 708
10 {-# LANGUAGE RoleAnnotations #-}
11 {-# LANGUAGE TypeFamilies #-}
12 #endif
13
14 #include "containers.h"
15
16 {-# OPTIONS_HADDOCK hide #-}
17
18 -----------------------------------------------------------------------------
19 -- |
20 -- Module : Data.Set.Base
21 -- Copyright : (c) Daan Leijen 2002
22 -- License : BSD-style
23 -- Maintainer : libraries@haskell.org
24 -- Stability : provisional
25 -- Portability : portable
26 --
27 -- An efficient implementation of sets.
28 --
29 -- These modules are intended to be imported qualified, to avoid name
30 -- clashes with Prelude functions, e.g.
31 --
32 -- > import Data.Set (Set)
33 -- > import qualified Data.Set as Set
34 --
35 -- The implementation of 'Set' is based on /size balanced/ binary trees (or
36 -- trees of /bounded balance/) as described by:
37 --
38 -- * Stephen Adams, \"/Efficient sets: a balancing act/\",
39 -- Journal of Functional Programming 3(4):553-562, October 1993,
40 -- <http://www.swiss.ai.mit.edu/~adams/BB/>.
41 -- * J. Nievergelt and E.M. Reingold,
42 -- \"/Binary search trees of bounded balance/\",
43 -- SIAM journal of computing 2(1), March 1973.
44 --
45 -- Bounds for 'union', 'intersection', and 'difference' are as given
46 -- by
47 --
48 -- * Guy Blelloch, Daniel Ferizovic, and Yihan Sun,
49 -- \"/Just Join for Parallel Ordered Sets/\",
50 -- <https://arxiv.org/abs/1602.02120v3>.
51 --
52 -- Note that the implementation is /left-biased/ -- the elements of a
53 -- first argument are always preferred to the second, for example in
54 -- 'union' or 'insert'. Of course, left-biasing can only be observed
55 -- when equality is an equivalence relation instead of structural
56 -- equality.
57 --
58 -- /Warning/: The size of the set must not exceed @maxBound::Int@. Violation of
59 -- this condition is not detected and if the size limit is exceeded, the
60 -- behavior of the set is completely undefined.
61 -----------------------------------------------------------------------------
62
63 -- [Note: Using INLINABLE]
64 -- ~~~~~~~~~~~~~~~~~~~~~~~
65 -- It is crucial to the performance that the functions specialize on the Ord
66 -- type when possible. GHC 7.0 and higher does this by itself when it sees th
67 -- unfolding of a function -- that is why all public functions are marked
68 -- INLINABLE (that exposes the unfolding).
69
70
71 -- [Note: Using INLINE]
72 -- ~~~~~~~~~~~~~~~~~~~~
73 -- For other compilers and GHC pre 7.0, we mark some of the functions INLINE.
74 -- We mark the functions that just navigate down the tree (lookup, insert,
75 -- delete and similar). That navigation code gets inlined and thus specialized
76 -- when possible. There is a price to pay -- code growth. The code INLINED is
77 -- therefore only the tree navigation, all the real work (rebalancing) is not
78 -- INLINED by using a NOINLINE.
79 --
80 -- All methods marked INLINE have to be nonrecursive -- a 'go' function doing
81 -- the real work is provided.
82
83
84 -- [Note: Type of local 'go' function]
85 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86 -- If the local 'go' function uses an Ord class, it sometimes heap-allocates
87 -- the Ord dictionary when the 'go' function does not have explicit type.
88 -- In that case we give 'go' explicit type. But this slightly decrease
89 -- performance, as the resulting 'go' function can float out to top level.
90
91
92 -- [Note: Local 'go' functions and capturing]
93 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94 -- As opposed to IntSet, when 'go' function captures an argument, increased
95 -- heap-allocation can occur: sometimes in a polymorphic function, the 'go'
96 -- floats out of its enclosing function and then it heap-allocates the
97 -- dictionary and the argument. Maybe it floats out too late and strictness
98 -- analyzer cannot see that these could be passed on stack.
99
100 -- [Note: Order of constructors]
101 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 -- The order of constructors of Set matters when considering performance.
103 -- Currently in GHC 7.0, when type has 2 constructors, a forward conditional
104 -- jump is made when successfully matching second constructor. Successful match
105 -- of first constructor results in the forward jump not taken.
106 -- On GHC 7.0, reordering constructors from Tip | Bin to Bin | Tip
107 -- improves the benchmark by up to 10% on x86.
108
109 module Data.Set.Base (
110 -- * Set type
111 Set(..) -- instance Eq,Ord,Show,Read,Data,Typeable
112
113 -- * Operators
114 , (\\)
115
116 -- * Query
117 , null
118 , size
119 , member
120 , notMember
121 , lookupLT
122 , lookupGT
123 , lookupLE
124 , lookupGE
125 , isSubsetOf
126 , isProperSubsetOf
127
128 -- * Construction
129 , empty
130 , singleton
131 , insert
132 , delete
133
134 -- * Combine
135 , union
136 , unions
137 , difference
138 , intersection
139
140 -- * Filter
141 , filter
142 , takeWhileAntitone
143 , dropWhileAntitone
144 , spanAntitone
145 , partition
146 , split
147 , splitMember
148 , splitRoot
149
150 -- * Indexed
151 , lookupIndex
152 , findIndex
153 , elemAt
154 , deleteAt
155 , take
156 , drop
157 , splitAt
158
159 -- * Map
160 , map
161 , mapMonotonic
162
163 -- * Folds
164 , foldr
165 , foldl
166 -- ** Strict folds
167 , foldr'
168 , foldl'
169 -- ** Legacy folds
170 , fold
171
172 -- * Min\/Max
173 , findMin
174 , findMax
175 , deleteMin
176 , deleteMax
177 , deleteFindMin
178 , deleteFindMax
179 , maxView
180 , minView
181
182 -- * Conversion
183
184 -- ** List
185 , elems
186 , toList
187 , fromList
188
189 -- ** Ordered list
190 , toAscList
191 , toDescList
192 , fromAscList
193 , fromDistinctAscList
194 , fromDescList
195 , fromDistinctDescList
196
197 -- * Debugging
198 , showTree
199 , showTreeWith
200 , valid
201
202 -- Internals (for testing)
203 , bin
204 , balanced
205 , link
206 , merge
207 ) where
208
209 import Prelude hiding (filter,foldl,foldr,null,map,take,drop,splitAt)
210 import qualified Data.List as List
211 import Data.Bits (shiftL, shiftR)
212 #if !MIN_VERSION_base(4,8,0)
213 import Data.Monoid (Monoid(..))
214 #endif
215 #if MIN_VERSION_base(4,9,0)
216 import Data.Semigroup (Semigroup((<>), stimes), stimesIdempotentMonoid)
217 #endif
218 import qualified Data.Foldable as Foldable
219 import Data.Typeable
220 import Control.DeepSeq (NFData(rnf))
221
222 import Data.Utils.StrictFold
223 import Data.Utils.StrictPair
224 import Data.Utils.PtrEquality
225
226 #if __GLASGOW_HASKELL__
227 import GHC.Exts ( build )
228 #if __GLASGOW_HASKELL__ >= 708
229 import qualified GHC.Exts as GHCExts
230 #endif
231 import Text.Read
232 import Data.Data
233 #endif
234
235
236 {--------------------------------------------------------------------
237 Operators
238 --------------------------------------------------------------------}
239 infixl 9 \\ --
240
241 -- | /O(m*log(n\/m+1)), m <= n/. See 'difference'.
242 (\\) :: Ord a => Set a -> Set a -> Set a
243 m1 \\ m2 = difference m1 m2
244 #if __GLASGOW_HASKELL__
245 {-# INLINABLE (\\) #-}
246 #endif
247
248 {--------------------------------------------------------------------
249 Sets are size balanced trees
250 --------------------------------------------------------------------}
251 -- | A set of values @a@.
252
253 -- See Note: Order of constructors
254 data Set a = Bin {-# UNPACK #-} !Size !a !(Set a) !(Set a)
255 | Tip
256
257 type Size = Int
258
259 #if __GLASGOW_HASKELL__ >= 708
260 type role Set nominal
261 #endif
262
263 instance Ord a => Monoid (Set a) where
264 mempty = empty
265 mconcat = unions
266 #if !(MIN_VERSION_base(4,9,0))
267 mappend = union
268 #else
269 mappend = (<>)
270
271 instance Ord a => Semigroup (Set a) where
272 (<>) = union
273 stimes = stimesIdempotentMonoid
274 #endif
275
276
277 instance Foldable.Foldable Set where
278 fold = go
279 where go Tip = mempty
280 go (Bin 1 k _ _) = k
281 go (Bin _ k l r) = go l `mappend` (k `mappend` go r)
282 {-# INLINABLE fold #-}
283 foldr = foldr
284 {-# INLINE foldr #-}
285 foldl = foldl
286 {-# INLINE foldl #-}
287 foldMap f t = go t
288 where go Tip = mempty
289 go (Bin 1 k _ _) = f k
290 go (Bin _ k l r) = go l `mappend` (f k `mappend` go r)
291 {-# INLINE foldMap #-}
292
293 #if MIN_VERSION_base(4,6,0)
294 foldl' = foldl'
295 {-# INLINE foldl' #-}
296 foldr' = foldr'
297 {-# INLINE foldr' #-}
298 #endif
299 #if MIN_VERSION_base(4,8,0)
300 length = size
301 {-# INLINE length #-}
302 null = null
303 {-# INLINE null #-}
304 toList = toList
305 {-# INLINE toList #-}
306 elem = go
307 where go !_ Tip = False
308 go x (Bin _ y l r) = x == y || go x l || go x r
309 {-# INLINABLE elem #-}
310 minimum = findMin
311 {-# INLINE minimum #-}
312 maximum = findMax
313 {-# INLINE maximum #-}
314 sum = foldl' (+) 0
315 {-# INLINABLE sum #-}
316 product = foldl' (*) 1
317 {-# INLINABLE product #-}
318 #endif
319
320
321 #if __GLASGOW_HASKELL__
322
323 {--------------------------------------------------------------------
324 A Data instance
325 --------------------------------------------------------------------}
326
327 -- This instance preserves data abstraction at the cost of inefficiency.
328 -- We provide limited reflection services for the sake of data abstraction.
329
330 instance (Data a, Ord a) => Data (Set a) where
331 gfoldl f z set = z fromList `f` (toList set)
332 toConstr _ = fromListConstr
333 gunfold k z c = case constrIndex c of
334 1 -> k (z fromList)
335 _ -> error "gunfold"
336 dataTypeOf _ = setDataType
337 dataCast1 f = gcast1 f
338
339 fromListConstr :: Constr
340 fromListConstr = mkConstr setDataType "fromList" [] Prefix
341
342 setDataType :: DataType
343 setDataType = mkDataType "Data.Set.Base.Set" [fromListConstr]
344
345 #endif
346
347 {--------------------------------------------------------------------
348 Query
349 --------------------------------------------------------------------}
350 -- | /O(1)/. Is this the empty set?
351 null :: Set a -> Bool
352 null Tip = True
353 null (Bin {}) = False
354 {-# INLINE null #-}
355
356 -- | /O(1)/. The number of elements in the set.
357 size :: Set a -> Int
358 size Tip = 0
359 size (Bin sz _ _ _) = sz
360 {-# INLINE size #-}
361
362 -- | /O(log n)/. Is the element in the set?
363 member :: Ord a => a -> Set a -> Bool
364 member = go
365 where
366 go !_ Tip = False
367 go x (Bin _ y l r) = case compare x y of
368 LT -> go x l
369 GT -> go x r
370 EQ -> True
371 #if __GLASGOW_HASKELL__
372 {-# INLINABLE member #-}
373 #else
374 {-# INLINE member #-}
375 #endif
376
377 -- | /O(log n)/. Is the element not in the set?
378 notMember :: Ord a => a -> Set a -> Bool
379 notMember a t = not $ member a t
380 #if __GLASGOW_HASKELL__
381 {-# INLINABLE notMember #-}
382 #else
383 {-# INLINE notMember #-}
384 #endif
385
386 -- | /O(log n)/. Find largest element smaller than the given one.
387 --
388 -- > lookupLT 3 (fromList [3, 5]) == Nothing
389 -- > lookupLT 5 (fromList [3, 5]) == Just 3
390 lookupLT :: Ord a => a -> Set a -> Maybe a
391 lookupLT = goNothing
392 where
393 goNothing !_ Tip = Nothing
394 goNothing x (Bin _ y l r) | x <= y = goNothing x l
395 | otherwise = goJust x y r
396
397 goJust !_ best Tip = Just best
398 goJust x best (Bin _ y l r) | x <= y = goJust x best l
399 | otherwise = goJust x y r
400 #if __GLASGOW_HASKELL__
401 {-# INLINABLE lookupLT #-}
402 #else
403 {-# INLINE lookupLT #-}
404 #endif
405
406 -- | /O(log n)/. Find smallest element greater than the given one.
407 --
408 -- > lookupGT 4 (fromList [3, 5]) == Just 5
409 -- > lookupGT 5 (fromList [3, 5]) == Nothing
410 lookupGT :: Ord a => a -> Set a -> Maybe a
411 lookupGT = goNothing
412 where
413 goNothing !_ Tip = Nothing
414 goNothing x (Bin _ y l r) | x < y = goJust x y l
415 | otherwise = goNothing x r
416
417 goJust !_ best Tip = Just best
418 goJust x best (Bin _ y l r) | x < y = goJust x y l
419 | otherwise = goJust x best r
420 #if __GLASGOW_HASKELL__
421 {-# INLINABLE lookupGT #-}
422 #else
423 {-# INLINE lookupGT #-}
424 #endif
425
426 -- | /O(log n)/. Find largest element smaller or equal to the given one.
427 --
428 -- > lookupLE 2 (fromList [3, 5]) == Nothing
429 -- > lookupLE 4 (fromList [3, 5]) == Just 3
430 -- > lookupLE 5 (fromList [3, 5]) == Just 5
431 lookupLE :: Ord a => a -> Set a -> Maybe a
432 lookupLE = goNothing
433 where
434 goNothing !_ Tip = Nothing
435 goNothing x (Bin _ y l r) = case compare x y of LT -> goNothing x l
436 EQ -> Just y
437 GT -> goJust x y r
438
439 goJust !_ best Tip = Just best
440 goJust x best (Bin _ y l r) = case compare x y of LT -> goJust x best l
441 EQ -> Just y
442 GT -> goJust x y r
443 #if __GLASGOW_HASKELL__
444 {-# INLINABLE lookupLE #-}
445 #else
446 {-# INLINE lookupLE #-}
447 #endif
448
449 -- | /O(log n)/. Find smallest element greater or equal to the given one.
450 --
451 -- > lookupGE 3 (fromList [3, 5]) == Just 3
452 -- > lookupGE 4 (fromList [3, 5]) == Just 5
453 -- > lookupGE 6 (fromList [3, 5]) == Nothing
454 lookupGE :: Ord a => a -> Set a -> Maybe a
455 lookupGE = goNothing
456 where
457 goNothing !_ Tip = Nothing
458 goNothing x (Bin _ y l r) = case compare x y of LT -> goJust x y l
459 EQ -> Just y
460 GT -> goNothing x r
461
462 goJust !_ best Tip = Just best
463 goJust x best (Bin _ y l r) = case compare x y of LT -> goJust x y l
464 EQ -> Just y
465 GT -> goJust x best r
466 #if __GLASGOW_HASKELL__
467 {-# INLINABLE lookupGE #-}
468 #else
469 {-# INLINE lookupGE #-}
470 #endif
471
472 {--------------------------------------------------------------------
473 Construction
474 --------------------------------------------------------------------}
475 -- | /O(1)/. The empty set.
476 empty :: Set a
477 empty = Tip
478 {-# INLINE empty #-}
479
480 -- | /O(1)/. Create a singleton set.
481 singleton :: a -> Set a
482 singleton x = Bin 1 x Tip Tip
483 {-# INLINE singleton #-}
484
485 {--------------------------------------------------------------------
486 Insertion, Deletion
487 --------------------------------------------------------------------}
488 -- | /O(log n)/. Insert an element in a set.
489 -- If the set already contains an element equal to the given value,
490 -- it is replaced with the new value.
491
492 -- See Note: Type of local 'go' function
493 insert :: Ord a => a -> Set a -> Set a
494 insert = go
495 where
496 go :: Ord a => a -> Set a -> Set a
497 go !x Tip = singleton x
498 go !x t@(Bin sz y l r) = case compare x y of
499 LT | l' `ptrEq` l -> t
500 | otherwise -> balanceL y l' r
501 where !l' = go x l
502 GT | r' `ptrEq` r -> t
503 | otherwise -> balanceR y l r'
504 where !r' = go x r
505 EQ | x `ptrEq` y -> t
506 | otherwise -> Bin sz x l r
507 #if __GLASGOW_HASKELL__
508 {-# INLINABLE insert #-}
509 #else
510 {-# INLINE insert #-}
511 #endif
512
513 -- Insert an element to the set only if it is not in the set.
514 -- Used by `union`.
515
516 -- See Note: Type of local 'go' function
517 insertR :: Ord a => a -> Set a -> Set a
518 insertR = go
519 where
520 go :: Ord a => a -> Set a -> Set a
521 go !x Tip = singleton x
522 go !x t@(Bin _ y l r) = case compare x y of
523 LT | l' `ptrEq` l -> t
524 | otherwise -> balanceL y l' r
525 where !l' = go x l
526 GT | r' `ptrEq` r -> t
527 | otherwise -> balanceR y l r'
528 where !r' = go x r
529 EQ -> t
530 #if __GLASGOW_HASKELL__
531 {-# INLINABLE insertR #-}
532 #else
533 {-# INLINE insertR #-}
534 #endif
535
536 -- | /O(log n)/. Delete an element from a set.
537
538 -- See Note: Type of local 'go' function
539 delete :: Ord a => a -> Set a -> Set a
540 delete = go
541 where
542 go :: Ord a => a -> Set a -> Set a
543 go !_ Tip = Tip
544 go x t@(Bin _ y l r) = case compare x y of
545 LT | l' `ptrEq` l -> t
546 | otherwise -> balanceR y l' r
547 where !l' = go x l
548 GT | r' `ptrEq` r -> t
549 | otherwise -> balanceL y l r'
550 where !r' = go x r
551 EQ -> glue l r
552 #if __GLASGOW_HASKELL__
553 {-# INLINABLE delete #-}
554 #else
555 {-# INLINE delete #-}
556 #endif
557
558 {--------------------------------------------------------------------
559 Subset
560 --------------------------------------------------------------------}
561 -- | /O(n+m)/. Is this a proper subset? (ie. a subset but not equal).
562 isProperSubsetOf :: Ord a => Set a -> Set a -> Bool
563 isProperSubsetOf s1 s2
564 = (size s1 < size s2) && (isSubsetOf s1 s2)
565 #if __GLASGOW_HASKELL__
566 {-# INLINABLE isProperSubsetOf #-}
567 #endif
568
569
570 -- | /O(n+m)/. Is this a subset?
571 -- @(s1 `isSubsetOf` s2)@ tells whether @s1@ is a subset of @s2@.
572 isSubsetOf :: Ord a => Set a -> Set a -> Bool
573 isSubsetOf t1 t2
574 = (size t1 <= size t2) && (isSubsetOfX t1 t2)
575 #if __GLASGOW_HASKELL__
576 {-# INLINABLE isSubsetOf #-}
577 #endif
578
579 isSubsetOfX :: Ord a => Set a -> Set a -> Bool
580 isSubsetOfX Tip _ = True
581 isSubsetOfX _ Tip = False
582 isSubsetOfX (Bin _ x l r) t
583 = found && isSubsetOfX l lt && isSubsetOfX r gt
584 where
585 (lt,found,gt) = splitMember x t
586 #if __GLASGOW_HASKELL__
587 {-# INLINABLE isSubsetOfX #-}
588 #endif
589
590
591 {--------------------------------------------------------------------
592 Minimal, Maximal
593 --------------------------------------------------------------------}
594 -- | /O(log n)/. The minimal element of a set.
595 findMin :: Set a -> a
596 findMin (Bin _ x Tip _) = x
597 findMin (Bin _ _ l _) = findMin l
598 findMin Tip = error "Set.findMin: empty set has no minimal element"
599
600 -- | /O(log n)/. The maximal element of a set.
601 findMax :: Set a -> a
602 findMax (Bin _ x _ Tip) = x
603 findMax (Bin _ _ _ r) = findMax r
604 findMax Tip = error "Set.findMax: empty set has no maximal element"
605
606 -- | /O(log n)/. Delete the minimal element. Returns an empty set if the set is empty.
607 deleteMin :: Set a -> Set a
608 deleteMin (Bin _ _ Tip r) = r
609 deleteMin (Bin _ x l r) = balanceR x (deleteMin l) r
610 deleteMin Tip = Tip
611
612 -- | /O(log n)/. Delete the maximal element. Returns an empty set if the set is empty.
613 deleteMax :: Set a -> Set a
614 deleteMax (Bin _ _ l Tip) = l
615 deleteMax (Bin _ x l r) = balanceL x l (deleteMax r)
616 deleteMax Tip = Tip
617
618 {--------------------------------------------------------------------
619 Union.
620 --------------------------------------------------------------------}
621 -- | The union of a list of sets: (@'unions' == 'foldl' 'union' 'empty'@).
622 unions :: Ord a => [Set a] -> Set a
623 unions = foldlStrict union empty
624 #if __GLASGOW_HASKELL__
625 {-# INLINABLE unions #-}
626 #endif
627
628 -- | /O(m*log(n/m + 1)), m <= n/. The union of two sets, preferring the first set when
629 -- equal elements are encountered.
630 union :: Ord a => Set a -> Set a -> Set a
631 union t1 Tip = t1
632 union t1 (Bin _ x Tip Tip) = insertR x t1
633 union (Bin _ x Tip Tip) t2 = insert x t2
634 union Tip t2 = t2
635 union t1@(Bin _ x l1 r1) t2 = case splitS x t2 of
636 (l2 :*: r2)
637 | l1l2 `ptrEq` l1 && r1r2 `ptrEq` r1 -> t1
638 | otherwise -> link x l1l2 r1r2
639 where !l1l2 = union l1 l2
640 !r1r2 = union r1 r2
641 #if __GLASGOW_HASKELL__
642 {-# INLINABLE union #-}
643 #endif
644
645 {--------------------------------------------------------------------
646 Difference
647 --------------------------------------------------------------------}
648 -- | /O(m*log(n/m + 1)), m <= n/. Difference of two sets.
649 difference :: Ord a => Set a -> Set a -> Set a
650 difference Tip _ = Tip
651 difference t1 Tip = t1
652 difference t1 (Bin _ x l2 r2) = case split x t1 of
653 (l1, r1)
654 | size l1l2 + size r1r2 == size t1 -> t1
655 | otherwise -> merge l1l2 r1r2
656 where !l1l2 = difference l1 l2
657 !r1r2 = difference r1 r2
658 #if __GLASGOW_HASKELL__
659 {-# INLINABLE difference #-}
660 #endif
661
662 {--------------------------------------------------------------------
663 Intersection
664 --------------------------------------------------------------------}
665 -- | /O(m*log(n/m + 1)), m <= n/. The intersection of two sets.
666 -- Elements of the result come from the first set, so for example
667 --
668 -- > import qualified Data.Set as S
669 -- > data AB = A | B deriving Show
670 -- > instance Ord AB where compare _ _ = EQ
671 -- > instance Eq AB where _ == _ = True
672 -- > main = print (S.singleton A `S.intersection` S.singleton B,
673 -- > S.singleton B `S.intersection` S.singleton A)
674 --
675 -- prints @(fromList [A],fromList [B])@.
676 intersection :: Ord a => Set a -> Set a -> Set a
677 intersection Tip _ = Tip
678 intersection _ Tip = Tip
679 intersection t1@(Bin _ x l1 r1) t2
680 | b = if l1l2 `ptrEq` l1 && r1r2 `ptrEq` r1
681 then t1
682 else link x l1l2 r1r2
683 | otherwise = merge l1l2 r1r2
684 where
685 !(l2, b, r2) = splitMember x t2
686 !l1l2 = intersection l1 l2
687 !r1r2 = intersection r1 r2
688 #if __GLASGOW_HASKELL__
689 {-# INLINABLE intersection #-}
690 #endif
691
692 {--------------------------------------------------------------------
693 Filter and partition
694 --------------------------------------------------------------------}
695 -- | /O(n)/. Filter all elements that satisfy the predicate.
696 filter :: (a -> Bool) -> Set a -> Set a
697 filter _ Tip = Tip
698 filter p t@(Bin _ x l r)
699 | p x = if l `ptrEq` l' && r `ptrEq` r'
700 then t
701 else link x l' r'
702 | otherwise = merge l' r'
703 where
704 !l' = filter p l
705 !r' = filter p r
706
707 -- | /O(n)/. Partition the set into two sets, one with all elements that satisfy
708 -- the predicate and one with all elements that don't satisfy the predicate.
709 -- See also 'split'.
710 partition :: (a -> Bool) -> Set a -> (Set a,Set a)
711 partition p0 t0 = toPair $ go p0 t0
712 where
713 go _ Tip = (Tip :*: Tip)
714 go p t@(Bin _ x l r) = case (go p l, go p r) of
715 ((l1 :*: l2), (r1 :*: r2))
716 | p x -> (if l1 `ptrEq` l && r1 `ptrEq` r
717 then t
718 else link x l1 r1) :*: merge l2 r2
719 | otherwise -> merge l1 r1 :*:
720 (if l2 `ptrEq` l && r2 `ptrEq` r
721 then t
722 else link x l2 r2)
723
724 {----------------------------------------------------------------------
725 Map
726 ----------------------------------------------------------------------}
727
728 -- | /O(n*log n)/.
729 -- @'map' f s@ is the set obtained by applying @f@ to each element of @s@.
730 --
731 -- It's worth noting that the size of the result may be smaller if,
732 -- for some @(x,y)@, @x \/= y && f x == f y@
733
734 map :: Ord b => (a->b) -> Set a -> Set b
735 map f = fromList . List.map f . toList
736 #if __GLASGOW_HASKELL__
737 {-# INLINABLE map #-}
738 #endif
739
740 -- | /O(n)/. The
741 --
742 -- @'mapMonotonic' f s == 'map' f s@, but works only when @f@ is strictly increasing.
743 -- /The precondition is not checked./
744 -- Semi-formally, we have:
745 --
746 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
747 -- > ==> mapMonotonic f s == map f s
748 -- > where ls = toList s
749
750 mapMonotonic :: (a->b) -> Set a -> Set b
751 mapMonotonic _ Tip = Tip
752 mapMonotonic f (Bin sz x l r) = Bin sz (f x) (mapMonotonic f l) (mapMonotonic f r)
753
754 {--------------------------------------------------------------------
755 Fold
756 --------------------------------------------------------------------}
757 -- | /O(n)/. Fold the elements in the set using the given right-associative
758 -- binary operator. This function is an equivalent of 'foldr' and is present
759 -- for compatibility only.
760 --
761 -- /Please note that fold will be deprecated in the future and removed./
762 fold :: (a -> b -> b) -> b -> Set a -> b
763 fold = foldr
764 {-# INLINE fold #-}
765
766 -- | /O(n)/. Fold the elements in the set using the given right-associative
767 -- binary operator, such that @'foldr' f z == 'Prelude.foldr' f z . 'toAscList'@.
768 --
769 -- For example,
770 --
771 -- > toAscList set = foldr (:) [] set
772 foldr :: (a -> b -> b) -> b -> Set a -> b
773 foldr f z = go z
774 where
775 go z' Tip = z'
776 go z' (Bin _ x l r) = go (f x (go z' r)) l
777 {-# INLINE foldr #-}
778
779 -- | /O(n)/. A strict version of 'foldr'. Each application of the operator is
780 -- evaluated before using the result in the next application. This
781 -- function is strict in the starting value.
782 foldr' :: (a -> b -> b) -> b -> Set a -> b
783 foldr' f z = go z
784 where
785 go !z' Tip = z'
786 go z' (Bin _ x l r) = go (f x (go z' r)) l
787 {-# INLINE foldr' #-}
788
789 -- | /O(n)/. Fold the elements in the set using the given left-associative
790 -- binary operator, such that @'foldl' f z == 'Prelude.foldl' f z . 'toAscList'@.
791 --
792 -- For example,
793 --
794 -- > toDescList set = foldl (flip (:)) [] set
795 foldl :: (a -> b -> a) -> a -> Set b -> a
796 foldl f z = go z
797 where
798 go z' Tip = z'
799 go z' (Bin _ x l r) = go (f (go z' l) x) r
800 {-# INLINE foldl #-}
801
802 -- | /O(n)/. A strict version of 'foldl'. Each application of the operator is
803 -- evaluated before using the result in the next application. This
804 -- function is strict in the starting value.
805 foldl' :: (a -> b -> a) -> a -> Set b -> a
806 foldl' f z = go z
807 where
808 go !z' Tip = z'
809 go z' (Bin _ x l r) = go (f (go z' l) x) r
810 {-# INLINE foldl' #-}
811
812 {--------------------------------------------------------------------
813 List variations
814 --------------------------------------------------------------------}
815 -- | /O(n)/. An alias of 'toAscList'. The elements of a set in ascending order.
816 -- Subject to list fusion.
817 elems :: Set a -> [a]
818 elems = toAscList
819
820 {--------------------------------------------------------------------
821 Lists
822 --------------------------------------------------------------------}
823 #if __GLASGOW_HASKELL__ >= 708
824 instance (Ord a) => GHCExts.IsList (Set a) where
825 type Item (Set a) = a
826 fromList = fromList
827 toList = toList
828 #endif
829
830 -- | /O(n)/. Convert the set to a list of elements. Subject to list fusion.
831 toList :: Set a -> [a]
832 toList = toAscList
833
834 -- | /O(n)/. Convert the set to an ascending list of elements. Subject to list fusion.
835 toAscList :: Set a -> [a]
836 toAscList = foldr (:) []
837
838 -- | /O(n)/. Convert the set to a descending list of elements. Subject to list
839 -- fusion.
840 toDescList :: Set a -> [a]
841 toDescList = foldl (flip (:)) []
842
843 -- List fusion for the list generating functions.
844 #if __GLASGOW_HASKELL__
845 -- The foldrFB and foldlFB are foldr and foldl equivalents, used for list fusion.
846 -- They are important to convert unfused to{Asc,Desc}List back, see mapFB in prelude.
847 foldrFB :: (a -> b -> b) -> b -> Set a -> b
848 foldrFB = foldr
849 {-# INLINE[0] foldrFB #-}
850 foldlFB :: (a -> b -> a) -> a -> Set b -> a
851 foldlFB = foldl
852 {-# INLINE[0] foldlFB #-}
853
854 -- Inline elems and toList, so that we need to fuse only toAscList.
855 {-# INLINE elems #-}
856 {-# INLINE toList #-}
857
858 -- The fusion is enabled up to phase 2 included. If it does not succeed,
859 -- convert in phase 1 the expanded to{Asc,Desc}List calls back to
860 -- to{Asc,Desc}List. In phase 0, we inline fold{lr}FB (which were used in
861 -- a list fusion, otherwise it would go away in phase 1), and let compiler do
862 -- whatever it wants with to{Asc,Desc}List -- it was forbidden to inline it
863 -- before phase 0, otherwise the fusion rules would not fire at all.
864 {-# NOINLINE[0] toAscList #-}
865 {-# NOINLINE[0] toDescList #-}
866 {-# RULES "Set.toAscList" [~1] forall s . toAscList s = build (\c n -> foldrFB c n s) #-}
867 {-# RULES "Set.toAscListBack" [1] foldrFB (:) [] = toAscList #-}
868 {-# RULES "Set.toDescList" [~1] forall s . toDescList s = build (\c n -> foldlFB (\xs x -> c x xs) n s) #-}
869 {-# RULES "Set.toDescListBack" [1] foldlFB (\xs x -> x : xs) [] = toDescList #-}
870 #endif
871
872 -- | /O(n*log n)/. Create a set from a list of elements.
873 --
874 -- If the elements are ordered, a linear-time implementation is used,
875 -- with the performance equal to 'fromDistinctAscList'.
876
877 -- For some reason, when 'singleton' is used in fromList or in
878 -- create, it is not inlined, so we inline it manually.
879 fromList :: Ord a => [a] -> Set a
880 fromList [] = Tip
881 fromList [x] = Bin 1 x Tip Tip
882 fromList (x0 : xs0) | not_ordered x0 xs0 = fromList' (Bin 1 x0 Tip Tip) xs0
883 | otherwise = go (1::Int) (Bin 1 x0 Tip Tip) xs0
884 where
885 not_ordered _ [] = False
886 not_ordered x (y : _) = x >= y
887 {-# INLINE not_ordered #-}
888
889 fromList' t0 xs = foldlStrict ins t0 xs
890 where ins t x = insert x t
891
892 go !_ t [] = t
893 go _ t [x] = insertMax x t
894 go s l xs@(x : xss) | not_ordered x xss = fromList' l xs
895 | otherwise = case create s xss of
896 (r, ys, []) -> go (s `shiftL` 1) (link x l r) ys
897 (r, _, ys) -> fromList' (link x l r) ys
898
899 -- The create is returning a triple (tree, xs, ys). Both xs and ys
900 -- represent not yet processed elements and only one of them can be nonempty.
901 -- If ys is nonempty, the keys in ys are not ordered with respect to tree
902 -- and must be inserted using fromList'. Otherwise the keys have been
903 -- ordered so far.
904 create !_ [] = (Tip, [], [])
905 create s xs@(x : xss)
906 | s == 1 = if not_ordered x xss then (Bin 1 x Tip Tip, [], xss)
907 else (Bin 1 x Tip Tip, xss, [])
908 | otherwise = case create (s `shiftR` 1) xs of
909 res@(_, [], _) -> res
910 (l, [y], zs) -> (insertMax y l, [], zs)
911 (l, ys@(y:yss), _) | not_ordered y yss -> (l, [], ys)
912 | otherwise -> case create (s `shiftR` 1) yss of
913 (r, zs, ws) -> (link y l r, zs, ws)
914 #if __GLASGOW_HASKELL__
915 {-# INLINABLE fromList #-}
916 #endif
917
918 {--------------------------------------------------------------------
919 Building trees from ascending/descending lists can be done in linear time.
920
921 Note that if [xs] is ascending that:
922 fromAscList xs == fromList xs
923 --------------------------------------------------------------------}
924 -- | /O(n)/. Build a set from an ascending list in linear time.
925 -- /The precondition (input list is ascending) is not checked./
926 fromAscList :: Eq a => [a] -> Set a
927 fromAscList xs = fromDistinctAscList (combineEq xs)
928 #if __GLASGOW_HASKELL__
929 {-# INLINABLE fromAscList #-}
930 #endif
931
932 -- | /O(n)/. Build a set from a descending list in linear time.
933 -- /The precondition (input list is descending) is not checked./
934 fromDescList :: Eq a => [a] -> Set a
935 fromDescList xs = fromDistinctDescList (combineEq xs)
936 #if __GLASGOW_HASKELL__
937 {-# INLINABLE fromDescList #-}
938 #endif
939
940 -- [combineEq xs] combines equal elements with [const] in an ordered list [xs]
941 --
942 -- TODO: combineEq allocates an intermediate list. It *should* be better to
943 -- make fromAscListBy and fromDescListBy the fundamental operations, and to
944 -- implement the rest using those.
945 combineEq :: Eq a => [a] -> [a]
946 combineEq [] = []
947 combineEq (x : xs) = combineEq' x xs
948 where
949 combineEq' z [] = [z]
950 combineEq' z (y:ys)
951 | z == y = combineEq' z ys
952 | otherwise = z : combineEq' y ys
953
954 -- | /O(n)/. Build a set from an ascending list of distinct elements in linear time.
955 -- /The precondition (input list is strictly ascending) is not checked./
956
957 -- For some reason, when 'singleton' is used in fromDistinctAscList or in
958 -- create, it is not inlined, so we inline it manually.
959 fromDistinctAscList :: [a] -> Set a
960 fromDistinctAscList [] = Tip
961 fromDistinctAscList (x0 : xs0) = go (1::Int) (Bin 1 x0 Tip Tip) xs0
962 where
963 go !_ t [] = t
964 go s l (x : xs) = case create s xs of
965 (r :*: ys) -> go (s `shiftL` 1) (link x l r) ys
966
967 create !_ [] = (Tip :*: [])
968 create s xs@(x : xs')
969 | s == 1 = (Bin 1 x Tip Tip :*: xs')
970 | otherwise = case create (s `shiftR` 1) xs of
971 res@(_ :*: []) -> res
972 (l :*: (y:ys)) -> case create (s `shiftR` 1) ys of
973 (r :*: zs) -> (link y l r :*: zs)
974
975 -- | /O(n)/. Build a set from a descending list of distinct elements in linear time.
976 -- /The precondition (input list is strictly descending) is not checked./
977
978 -- For some reason, when 'singleton' is used in fromDistinctDescList or in
979 -- create, it is not inlined, so we inline it manually.
980 fromDistinctDescList :: [a] -> Set a
981 fromDistinctDescList [] = Tip
982 fromDistinctDescList (x0 : xs0) = go (1::Int) (Bin 1 x0 Tip Tip) xs0
983 where
984 go !_ t [] = t
985 go s r (x : xs) = case create s xs of
986 (l :*: ys) -> go (s `shiftL` 1) (link x l r) ys
987
988 create !_ [] = (Tip :*: [])
989 create s xs@(x : xs')
990 | s == 1 = (Bin 1 x Tip Tip :*: xs')
991 | otherwise = case create (s `shiftR` 1) xs of
992 res@(_ :*: []) -> res
993 (r :*: (y:ys)) -> case create (s `shiftR` 1) ys of
994 (l :*: zs) -> (link y l r :*: zs)
995
996 {--------------------------------------------------------------------
997 Eq converts the set to a list. In a lazy setting, this
998 actually seems one of the faster methods to compare two trees
999 and it is certainly the simplest :-)
1000 --------------------------------------------------------------------}
1001 instance Eq a => Eq (Set a) where
1002 t1 == t2 = (size t1 == size t2) && (toAscList t1 == toAscList t2)
1003
1004 {--------------------------------------------------------------------
1005 Ord
1006 --------------------------------------------------------------------}
1007
1008 instance Ord a => Ord (Set a) where
1009 compare s1 s2 = compare (toAscList s1) (toAscList s2)
1010
1011 {--------------------------------------------------------------------
1012 Show
1013 --------------------------------------------------------------------}
1014 instance Show a => Show (Set a) where
1015 showsPrec p xs = showParen (p > 10) $
1016 showString "fromList " . shows (toList xs)
1017
1018 {--------------------------------------------------------------------
1019 Read
1020 --------------------------------------------------------------------}
1021 instance (Read a, Ord a) => Read (Set a) where
1022 #ifdef __GLASGOW_HASKELL__
1023 readPrec = parens $ prec 10 $ do
1024 Ident "fromList" <- lexP
1025 xs <- readPrec
1026 return (fromList xs)
1027
1028 readListPrec = readListPrecDefault
1029 #else
1030 readsPrec p = readParen (p > 10) $ \ r -> do
1031 ("fromList",s) <- lex r
1032 (xs,t) <- reads s
1033 return (fromList xs,t)
1034 #endif
1035
1036 {--------------------------------------------------------------------
1037 Typeable/Data
1038 --------------------------------------------------------------------}
1039
1040 INSTANCE_TYPEABLE1(Set)
1041
1042 {--------------------------------------------------------------------
1043 NFData
1044 --------------------------------------------------------------------}
1045
1046 instance NFData a => NFData (Set a) where
1047 rnf Tip = ()
1048 rnf (Bin _ y l r) = rnf y `seq` rnf l `seq` rnf r
1049
1050 {--------------------------------------------------------------------
1051 Split
1052 --------------------------------------------------------------------}
1053 -- | /O(log n)/. The expression (@'split' x set@) is a pair @(set1,set2)@
1054 -- where @set1@ comprises the elements of @set@ less than @x@ and @set2@
1055 -- comprises the elements of @set@ greater than @x@.
1056 split :: Ord a => a -> Set a -> (Set a,Set a)
1057 split x t = toPair $ splitS x t
1058 {-# INLINABLE split #-}
1059
1060 splitS :: Ord a => a -> Set a -> StrictPair (Set a) (Set a)
1061 splitS _ Tip = (Tip :*: Tip)
1062 splitS x (Bin _ y l r)
1063 = case compare x y of
1064 LT -> let (lt :*: gt) = splitS x l in (lt :*: link y gt r)
1065 GT -> let (lt :*: gt) = splitS x r in (link y l lt :*: gt)
1066 EQ -> (l :*: r)
1067 {-# INLINABLE splitS #-}
1068
1069 -- | /O(log n)/. Performs a 'split' but also returns whether the pivot
1070 -- element was found in the original set.
1071 splitMember :: Ord a => a -> Set a -> (Set a,Bool,Set a)
1072 splitMember _ Tip = (Tip, False, Tip)
1073 splitMember x (Bin _ y l r)
1074 = case compare x y of
1075 LT -> let (lt, found, gt) = splitMember x l
1076 !gt' = link y gt r
1077 in (lt, found, gt')
1078 GT -> let (lt, found, gt) = splitMember x r
1079 !lt' = link y l lt
1080 in (lt', found, gt)
1081 EQ -> (l, True, r)
1082 #if __GLASGOW_HASKELL__
1083 {-# INLINABLE splitMember #-}
1084 #endif
1085
1086 {--------------------------------------------------------------------
1087 Indexing
1088 --------------------------------------------------------------------}
1089
1090 -- | /O(log n)/. Return the /index/ of an element, which is its zero-based
1091 -- index in the sorted sequence of elements. The index is a number from /0/ up
1092 -- to, but not including, the 'size' of the set. Calls 'error' when the element
1093 -- is not a 'member' of the set.
1094 --
1095 -- > findIndex 2 (fromList [5,3]) Error: element is not in the set
1096 -- > findIndex 3 (fromList [5,3]) == 0
1097 -- > findIndex 5 (fromList [5,3]) == 1
1098 -- > findIndex 6 (fromList [5,3]) Error: element is not in the set
1099
1100 -- See Note: Type of local 'go' function
1101 findIndex :: Ord a => a -> Set a -> Int
1102 findIndex = go 0
1103 where
1104 go :: Ord a => Int -> a -> Set a -> Int
1105 go !_ !_ Tip = error "Set.findIndex: element is not in the set"
1106 go idx x (Bin _ kx l r) = case compare x kx of
1107 LT -> go idx x l
1108 GT -> go (idx + size l + 1) x r
1109 EQ -> idx + size l
1110 #if __GLASGOW_HASKELL__
1111 {-# INLINABLE findIndex #-}
1112 #endif
1113
1114 -- | /O(log n)/. Lookup the /index/ of an element, which is its zero-based index in
1115 -- the sorted sequence of elements. The index is a number from /0/ up to, but not
1116 -- including, the 'size' of the set.
1117 --
1118 -- > isJust (lookupIndex 2 (fromList [5,3])) == False
1119 -- > fromJust (lookupIndex 3 (fromList [5,3])) == 0
1120 -- > fromJust (lookupIndex 5 (fromList [5,3])) == 1
1121 -- > isJust (lookupIndex 6 (fromList [5,3])) == False
1122
1123 -- See Note: Type of local 'go' function
1124 lookupIndex :: Ord a => a -> Set a -> Maybe Int
1125 lookupIndex = go 0
1126 where
1127 go :: Ord a => Int -> a -> Set a -> Maybe Int
1128 go !_ !_ Tip = Nothing
1129 go idx x (Bin _ kx l r) = case compare x kx of
1130 LT -> go idx x l
1131 GT -> go (idx + size l + 1) x r
1132 EQ -> Just $! idx + size l
1133 #if __GLASGOW_HASKELL__
1134 {-# INLINABLE lookupIndex #-}
1135 #endif
1136
1137 -- | /O(log n)/. Retrieve an element by its /index/, i.e. by its zero-based
1138 -- index in the sorted sequence of elements. If the /index/ is out of range (less
1139 -- than zero, greater or equal to 'size' of the set), 'error' is called.
1140 --
1141 -- > elemAt 0 (fromList [5,3]) == 3
1142 -- > elemAt 1 (fromList [5,3]) == 5
1143 -- > elemAt 2 (fromList [5,3]) Error: index out of range
1144
1145 elemAt :: Int -> Set a -> a
1146 elemAt !_ Tip = error "Set.elemAt: index out of range"
1147 elemAt i (Bin _ x l r)
1148 = case compare i sizeL of
1149 LT -> elemAt i l
1150 GT -> elemAt (i-sizeL-1) r
1151 EQ -> x
1152 where
1153 sizeL = size l
1154
1155 -- | /O(log n)/. Delete the element at /index/, i.e. by its zero-based index in
1156 -- the sorted sequence of elements. If the /index/ is out of range (less than zero,
1157 -- greater or equal to 'size' of the set), 'error' is called.
1158 --
1159 -- > deleteAt 0 (fromList [5,3]) == singleton 5
1160 -- > deleteAt 1 (fromList [5,3]) == singleton 3
1161 -- > deleteAt 2 (fromList [5,3]) Error: index out of range
1162 -- > deleteAt (-1) (fromList [5,3]) Error: index out of range
1163
1164 deleteAt :: Int -> Set a -> Set a
1165 deleteAt !i t =
1166 case t of
1167 Tip -> error "Set.deleteAt: index out of range"
1168 Bin _ x l r -> case compare i sizeL of
1169 LT -> balanceR x (deleteAt i l) r
1170 GT -> balanceL x l (deleteAt (i-sizeL-1) r)
1171 EQ -> glue l r
1172 where
1173 sizeL = size l
1174
1175 -- | Take a given number of elements in order, beginning
1176 -- with the smallest ones.
1177 --
1178 -- @
1179 -- take n = 'fromDistinctAscList' . 'Prelude.take' n . 'toAscList'
1180 -- @
1181 take :: Int -> Set a -> Set a
1182 take i m | i >= size m = m
1183 take i0 m0 = go i0 m0
1184 where
1185 go i !_ | i <= 0 = Tip
1186 go !_ Tip = Tip
1187 go i (Bin _ x l r) =
1188 case compare i sizeL of
1189 LT -> go i l
1190 GT -> link x l (go (i - sizeL - 1) r)
1191 EQ -> l
1192 where sizeL = size l
1193
1194 -- | Drop a given number of elements in order, beginning
1195 -- with the smallest ones.
1196 --
1197 -- @
1198 -- drop n = 'fromDistinctAscList' . 'Prelude.drop' n . 'toAscList'
1199 -- @
1200 drop :: Int -> Set a -> Set a
1201 drop i m | i >= size m = Tip
1202 drop i0 m0 = go i0 m0
1203 where
1204 go i m | i <= 0 = m
1205 go !_ Tip = Tip
1206 go i (Bin _ x l r) =
1207 case compare i sizeL of
1208 LT -> link x (go i l) r
1209 GT -> go (i - sizeL - 1) r
1210 EQ -> insertMin x r
1211 where sizeL = size l
1212
1213 -- | /O(log n)/. Split a set at a particular index.
1214 --
1215 -- @
1216 -- splitAt !n !xs = ('take' n xs, 'drop' n xs)
1217 -- @
1218 splitAt :: Int -> Set a -> (Set a, Set a)
1219 splitAt i0 m0
1220 | i0 >= size m0 = (m0, Tip)
1221 | otherwise = toPair $ go i0 m0
1222 where
1223 go i m | i <= 0 = Tip :*: m
1224 go !_ Tip = Tip :*: Tip
1225 go i (Bin _ x l r)
1226 = case compare i sizeL of
1227 LT -> case go i l of
1228 ll :*: lr -> ll :*: link x lr r
1229 GT -> case go (i - sizeL - 1) r of
1230 rl :*: rr -> link x l rl :*: rr
1231 EQ -> l :*: insertMin x r
1232 where sizeL = size l
1233
1234 -- | /O(log n)/. Take while a predicate on the elements holds.
1235 -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set,
1236 -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'.
1237 --
1238 -- @
1239 -- takeWhileAntitone p = 'fromDistinctAscList' . 'Data.List.takeWhile' p . 'toList'
1240 -- takeWhileAntitone p = 'filter' p
1241 -- @
1242
1243 takeWhileAntitone :: (a -> Bool) -> Set a -> Set a
1244 takeWhileAntitone _ Tip = Tip
1245 takeWhileAntitone p (Bin _ x l r)
1246 | p x = link x l (takeWhileAntitone p r)
1247 | otherwise = takeWhileAntitone p l
1248
1249 -- | /O(log n)/. Drop while a predicate on the elements holds.
1250 -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set,
1251 -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'.
1252 --
1253 -- @
1254 -- dropWhileAntitone p = 'fromDistinctAscList' . 'Data.List.dropWhile' p . 'toList'
1255 -- dropWhileAntitone p = 'filter' (not . p)
1256 -- @
1257
1258 dropWhileAntitone :: (a -> Bool) -> Set a -> Set a
1259 dropWhileAntitone _ Tip = Tip
1260 dropWhileAntitone p (Bin _ x l r)
1261 | p x = dropWhileAntitone p r
1262 | otherwise = link x (dropWhileAntitone p l) r
1263
1264 -- | /O(log n)/. Divide a set at the point where a predicate on the elements stops holding.
1265 -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set,
1266 -- @j \< k ==\> p j \>= p k@.
1267 --
1268 -- @
1269 -- spanAntitone p xs = ('takeWhileAntitone' p xs, 'dropWhileAntitone' p xs)
1270 -- spanAntitone p xs = partition p xs
1271 -- @
1272 --
1273 -- Note: if @p@ is not actually antitone, then @spanAntitone@ will split the set
1274 -- at some /unspecified/ point where the predicate switches from holding to not
1275 -- holding (where the predicate is seen to hold before the first element and to fail
1276 -- after the last element).
1277
1278 spanAntitone :: (a -> Bool) -> Set a -> (Set a, Set a)
1279 spanAntitone p0 m = toPair (go p0 m)
1280 where
1281 go _ Tip = Tip :*: Tip
1282 go p (Bin _ x l r)
1283 | p x = let u :*: v = go p r in link x l u :*: v
1284 | otherwise = let u :*: v = go p l in u :*: link x v r
1285
1286
1287 {--------------------------------------------------------------------
1288 Utility functions that maintain the balance properties of the tree.
1289 All constructors assume that all values in [l] < [x] and all values
1290 in [r] > [x], and that [l] and [r] are valid trees.
1291
1292 In order of sophistication:
1293 [Bin sz x l r] The type constructor.
1294 [bin x l r] Maintains the correct size, assumes that both [l]
1295 and [r] are balanced with respect to each other.
1296 [balance x l r] Restores the balance and size.
1297 Assumes that the original tree was balanced and
1298 that [l] or [r] has changed by at most one element.
1299 [link x l r] Restores balance and size.
1300
1301 Furthermore, we can construct a new tree from two trees. Both operations
1302 assume that all values in [l] < all values in [r] and that [l] and [r]
1303 are valid:
1304 [glue l r] Glues [l] and [r] together. Assumes that [l] and
1305 [r] are already balanced with respect to each other.
1306 [merge l r] Merges two trees and restores balance.
1307 --------------------------------------------------------------------}
1308
1309 {--------------------------------------------------------------------
1310 Link
1311 --------------------------------------------------------------------}
1312 link :: a -> Set a -> Set a -> Set a
1313 link x Tip r = insertMin x r
1314 link x l Tip = insertMax x l
1315 link x l@(Bin sizeL y ly ry) r@(Bin sizeR z lz rz)
1316 | delta*sizeL < sizeR = balanceL z (link x l lz) rz
1317 | delta*sizeR < sizeL = balanceR y ly (link x ry r)
1318 | otherwise = bin x l r
1319
1320
1321 -- insertMin and insertMax don't perform potentially expensive comparisons.
1322 insertMax,insertMin :: a -> Set a -> Set a
1323 insertMax x t
1324 = case t of
1325 Tip -> singleton x
1326 Bin _ y l r
1327 -> balanceR y l (insertMax x r)
1328
1329 insertMin x t
1330 = case t of
1331 Tip -> singleton x
1332 Bin _ y l r
1333 -> balanceL y (insertMin x l) r
1334
1335 {--------------------------------------------------------------------
1336 [merge l r]: merges two trees.
1337 --------------------------------------------------------------------}
1338 merge :: Set a -> Set a -> Set a
1339 merge Tip r = r
1340 merge l Tip = l
1341 merge l@(Bin sizeL x lx rx) r@(Bin sizeR y ly ry)
1342 | delta*sizeL < sizeR = balanceL y (merge l ly) ry
1343 | delta*sizeR < sizeL = balanceR x lx (merge rx r)
1344 | otherwise = glue l r
1345
1346 {--------------------------------------------------------------------
1347 [glue l r]: glues two trees together.
1348 Assumes that [l] and [r] are already balanced with respect to each other.
1349 --------------------------------------------------------------------}
1350 glue :: Set a -> Set a -> Set a
1351 glue Tip r = r
1352 glue l Tip = l
1353 glue l r
1354 | size l > size r = let (m,l') = deleteFindMax l in balanceR m l' r
1355 | otherwise = let (m,r') = deleteFindMin r in balanceL m l r'
1356
1357 -- | /O(log n)/. Delete and find the minimal element.
1358 --
1359 -- > deleteFindMin set = (findMin set, deleteMin set)
1360
1361 deleteFindMin :: Set a -> (a,Set a)
1362 deleteFindMin t
1363 = case t of
1364 Bin _ x Tip r -> (x,r)
1365 Bin _ x l r -> let (xm,l') = deleteFindMin l in (xm,balanceR x l' r)
1366 Tip -> (error "Set.deleteFindMin: can not return the minimal element of an empty set", Tip)
1367
1368 -- | /O(log n)/. Delete and find the maximal element.
1369 --
1370 -- > deleteFindMax set = (findMax set, deleteMax set)
1371 deleteFindMax :: Set a -> (a,Set a)
1372 deleteFindMax t
1373 = case t of
1374 Bin _ x l Tip -> (x,l)
1375 Bin _ x l r -> let (xm,r') = deleteFindMax r in (xm,balanceL x l r')
1376 Tip -> (error "Set.deleteFindMax: can not return the maximal element of an empty set", Tip)
1377
1378 -- | /O(log n)/. Retrieves the minimal key of the set, and the set
1379 -- stripped of that element, or 'Nothing' if passed an empty set.
1380 minView :: Set a -> Maybe (a, Set a)
1381 minView Tip = Nothing
1382 minView x = Just (deleteFindMin x)
1383
1384 -- | /O(log n)/. Retrieves the maximal key of the set, and the set
1385 -- stripped of that element, or 'Nothing' if passed an empty set.
1386 maxView :: Set a -> Maybe (a, Set a)
1387 maxView Tip = Nothing
1388 maxView x = Just (deleteFindMax x)
1389
1390 {--------------------------------------------------------------------
1391 [balance x l r] balances two trees with value x.
1392 The sizes of the trees should balance after decreasing the
1393 size of one of them. (a rotation).
1394
1395 [delta] is the maximal relative difference between the sizes of
1396 two trees, it corresponds with the [w] in Adams' paper.
1397 [ratio] is the ratio between an outer and inner sibling of the
1398 heavier subtree in an unbalanced setting. It determines
1399 whether a double or single rotation should be performed
1400 to restore balance. It is correspondes with the inverse
1401 of $\alpha$ in Adam's article.
1402
1403 Note that according to the Adam's paper:
1404 - [delta] should be larger than 4.646 with a [ratio] of 2.
1405 - [delta] should be larger than 3.745 with a [ratio] of 1.534.
1406
1407 But the Adam's paper is errorneous:
1408 - it can be proved that for delta=2 and delta>=5 there does
1409 not exist any ratio that would work
1410 - delta=4.5 and ratio=2 does not work
1411
1412 That leaves two reasonable variants, delta=3 and delta=4,
1413 both with ratio=2.
1414
1415 - A lower [delta] leads to a more 'perfectly' balanced tree.
1416 - A higher [delta] performs less rebalancing.
1417
1418 In the benchmarks, delta=3 is faster on insert operations,
1419 and delta=4 has slightly better deletes. As the insert speedup
1420 is larger, we currently use delta=3.
1421
1422 --------------------------------------------------------------------}
1423 delta,ratio :: Int
1424 delta = 3
1425 ratio = 2
1426
1427 -- The balance function is equivalent to the following:
1428 --
1429 -- balance :: a -> Set a -> Set a -> Set a
1430 -- balance x l r
1431 -- | sizeL + sizeR <= 1 = Bin sizeX x l r
1432 -- | sizeR > delta*sizeL = rotateL x l r
1433 -- | sizeL > delta*sizeR = rotateR x l r
1434 -- | otherwise = Bin sizeX x l r
1435 -- where
1436 -- sizeL = size l
1437 -- sizeR = size r
1438 -- sizeX = sizeL + sizeR + 1
1439 --
1440 -- rotateL :: a -> Set a -> Set a -> Set a
1441 -- rotateL x l r@(Bin _ _ ly ry) | size ly < ratio*size ry = singleL x l r
1442 -- | otherwise = doubleL x l r
1443 -- rotateR :: a -> Set a -> Set a -> Set a
1444 -- rotateR x l@(Bin _ _ ly ry) r | size ry < ratio*size ly = singleR x l r
1445 -- | otherwise = doubleR x l r
1446 --
1447 -- singleL, singleR :: a -> Set a -> Set a -> Set a
1448 -- singleL x1 t1 (Bin _ x2 t2 t3) = bin x2 (bin x1 t1 t2) t3
1449 -- singleR x1 (Bin _ x2 t1 t2) t3 = bin x2 t1 (bin x1 t2 t3)
1450 --
1451 -- doubleL, doubleR :: a -> Set a -> Set a -> Set a
1452 -- doubleL x1 t1 (Bin _ x2 (Bin _ x3 t2 t3) t4) = bin x3 (bin x1 t1 t2) (bin x2 t3 t4)
1453 -- doubleR x1 (Bin _ x2 t1 (Bin _ x3 t2 t3)) t4 = bin x3 (bin x2 t1 t2) (bin x1 t3 t4)
1454 --
1455 -- It is only written in such a way that every node is pattern-matched only once.
1456 --
1457 -- Only balanceL and balanceR are needed at the moment, so balance is not here anymore.
1458 -- In case it is needed, it can be found in Data.Map.
1459
1460 -- Functions balanceL and balanceR are specialised versions of balance.
1461 -- balanceL only checks whether the left subtree is too big,
1462 -- balanceR only checks whether the right subtree is too big.
1463
1464 -- balanceL is called when left subtree might have been inserted to or when
1465 -- right subtree might have been deleted from.
1466 balanceL :: a -> Set a -> Set a -> Set a
1467 balanceL x l r = case r of
1468 Tip -> case l of
1469 Tip -> Bin 1 x Tip Tip
1470 (Bin _ _ Tip Tip) -> Bin 2 x l Tip
1471 (Bin _ lx Tip (Bin _ lrx _ _)) -> Bin 3 lrx (Bin 1 lx Tip Tip) (Bin 1 x Tip Tip)
1472 (Bin _ lx ll@(Bin _ _ _ _) Tip) -> Bin 3 lx ll (Bin 1 x Tip Tip)
1473 (Bin ls lx ll@(Bin lls _ _ _) lr@(Bin lrs lrx lrl lrr))
1474 | lrs < ratio*lls -> Bin (1+ls) lx ll (Bin (1+lrs) x lr Tip)
1475 | otherwise -> Bin (1+ls) lrx (Bin (1+lls+size lrl) lx ll lrl) (Bin (1+size lrr) x lrr Tip)
1476
1477 (Bin rs _ _ _) -> case l of
1478 Tip -> Bin (1+rs) x Tip r
1479
1480 (Bin ls lx ll lr)
1481 | ls > delta*rs -> case (ll, lr) of
1482 (Bin lls _ _ _, Bin lrs lrx lrl lrr)
1483 | lrs < ratio*lls -> Bin (1+ls+rs) lx ll (Bin (1+rs+lrs) x lr r)
1484 | otherwise -> Bin (1+ls+rs) lrx (Bin (1+lls+size lrl) lx ll lrl) (Bin (1+rs+size lrr) x lrr r)
1485 (_, _) -> error "Failure in Data.Map.balanceL"
1486 | otherwise -> Bin (1+ls+rs) x l r
1487 {-# NOINLINE balanceL #-}
1488
1489 -- balanceR is called when right subtree might have been inserted to or when
1490 -- left subtree might have been deleted from.
1491 balanceR :: a -> Set a -> Set a -> Set a
1492 balanceR x l r = case l of
1493 Tip -> case r of
1494 Tip -> Bin 1 x Tip Tip
1495 (Bin _ _ Tip Tip) -> Bin 2 x Tip r
1496 (Bin _ rx Tip rr@(Bin _ _ _ _)) -> Bin 3 rx (Bin 1 x Tip Tip) rr
1497 (Bin _ rx (Bin _ rlx _ _) Tip) -> Bin 3 rlx (Bin 1 x Tip Tip) (Bin 1 rx Tip Tip)
1498 (Bin rs rx rl@(Bin rls rlx rll rlr) rr@(Bin rrs _ _ _))
1499 | rls < ratio*rrs -> Bin (1+rs) rx (Bin (1+rls) x Tip rl) rr
1500 | otherwise -> Bin (1+rs) rlx (Bin (1+size rll) x Tip rll) (Bin (1+rrs+size rlr) rx rlr rr)
1501
1502 (Bin ls _ _ _) -> case r of
1503 Tip -> Bin (1+ls) x l Tip
1504
1505 (Bin rs rx rl rr)
1506 | rs > delta*ls -> case (rl, rr) of
1507 (Bin rls rlx rll rlr, Bin rrs _ _ _)
1508 | rls < ratio*rrs -> Bin (1+ls+rs) rx (Bin (1+ls+rls) x l rl) rr
1509 | otherwise -> Bin (1+ls+rs) rlx (Bin (1+ls+size rll) x l rll) (Bin (1+rrs+size rlr) rx rlr rr)
1510 (_, _) -> error "Failure in Data.Map.balanceR"
1511 | otherwise -> Bin (1+ls+rs) x l r
1512 {-# NOINLINE balanceR #-}
1513
1514 {--------------------------------------------------------------------
1515 The bin constructor maintains the size of the tree
1516 --------------------------------------------------------------------}
1517 bin :: a -> Set a -> Set a -> Set a
1518 bin x l r
1519 = Bin (size l + size r + 1) x l r
1520 {-# INLINE bin #-}
1521
1522
1523 {--------------------------------------------------------------------
1524 Utilities
1525 --------------------------------------------------------------------}
1526
1527 -- | /O(1)/. Decompose a set into pieces based on the structure of the underlying
1528 -- tree. This function is useful for consuming a set in parallel.
1529 --
1530 -- No guarantee is made as to the sizes of the pieces; an internal, but
1531 -- deterministic process determines this. However, it is guaranteed that the pieces
1532 -- returned will be in ascending order (all elements in the first subset less than all
1533 -- elements in the second, and so on).
1534 --
1535 -- Examples:
1536 --
1537 -- > splitRoot (fromList [1..6]) ==
1538 -- > [fromList [1,2,3],fromList [4],fromList [5,6]]
1539 --
1540 -- > splitRoot empty == []
1541 --
1542 -- Note that the current implementation does not return more than three subsets,
1543 -- but you should not depend on this behaviour because it can change in the
1544 -- future without notice.
1545 splitRoot :: Set a -> [Set a]
1546 splitRoot orig =
1547 case orig of
1548 Tip -> []
1549 Bin _ v l r -> [l, singleton v, r]
1550 {-# INLINE splitRoot #-}
1551
1552
1553 {--------------------------------------------------------------------
1554 Debugging
1555 --------------------------------------------------------------------}
1556 -- | /O(n)/. Show the tree that implements the set. The tree is shown
1557 -- in a compressed, hanging format.
1558 showTree :: Show a => Set a -> String
1559 showTree s
1560 = showTreeWith True False s
1561
1562
1563 {- | /O(n)/. The expression (@showTreeWith hang wide map@) shows
1564 the tree that implements the set. If @hang@ is
1565 @True@, a /hanging/ tree is shown otherwise a rotated tree is shown. If
1566 @wide@ is 'True', an extra wide version is shown.
1567
1568 > Set> putStrLn $ showTreeWith True False $ fromDistinctAscList [1..5]
1569 > 4
1570 > +--2
1571 > | +--1
1572 > | +--3
1573 > +--5
1574 >
1575 > Set> putStrLn $ showTreeWith True True $ fromDistinctAscList [1..5]
1576 > 4
1577 > |
1578 > +--2
1579 > | |
1580 > | +--1
1581 > | |
1582 > | +--3
1583 > |
1584 > +--5
1585 >
1586 > Set> putStrLn $ showTreeWith False True $ fromDistinctAscList [1..5]
1587 > +--5
1588 > |
1589 > 4
1590 > |
1591 > | +--3
1592 > | |
1593 > +--2
1594 > |
1595 > +--1
1596
1597 -}
1598 showTreeWith :: Show a => Bool -> Bool -> Set a -> String
1599 showTreeWith hang wide t
1600 | hang = (showsTreeHang wide [] t) ""
1601 | otherwise = (showsTree wide [] [] t) ""
1602
1603 showsTree :: Show a => Bool -> [String] -> [String] -> Set a -> ShowS
1604 showsTree wide lbars rbars t
1605 = case t of
1606 Tip -> showsBars lbars . showString "|\n"
1607 Bin _ x Tip Tip
1608 -> showsBars lbars . shows x . showString "\n"
1609 Bin _ x l r
1610 -> showsTree wide (withBar rbars) (withEmpty rbars) r .
1611 showWide wide rbars .
1612 showsBars lbars . shows x . showString "\n" .
1613 showWide wide lbars .
1614 showsTree wide (withEmpty lbars) (withBar lbars) l
1615
1616 showsTreeHang :: Show a => Bool -> [String] -> Set a -> ShowS
1617 showsTreeHang wide bars t
1618 = case t of
1619 Tip -> showsBars bars . showString "|\n"
1620 Bin _ x Tip Tip
1621 -> showsBars bars . shows x . showString "\n"
1622 Bin _ x l r
1623 -> showsBars bars . shows x . showString "\n" .
1624 showWide wide bars .
1625 showsTreeHang wide (withBar bars) l .
1626 showWide wide bars .
1627 showsTreeHang wide (withEmpty bars) r
1628
1629 showWide :: Bool -> [String] -> String -> String
1630 showWide wide bars
1631 | wide = showString (concat (reverse bars)) . showString "|\n"
1632 | otherwise = id
1633
1634 showsBars :: [String] -> ShowS
1635 showsBars bars
1636 = case bars of
1637 [] -> id
1638 _ -> showString (concat (reverse (tail bars))) . showString node
1639
1640 node :: String
1641 node = "+--"
1642
1643 withBar, withEmpty :: [String] -> [String]
1644 withBar bars = "| ":bars
1645 withEmpty bars = " ":bars
1646
1647 {--------------------------------------------------------------------
1648 Assertions
1649 --------------------------------------------------------------------}
1650 -- | /O(n)/. Test if the internal set structure is valid.
1651 valid :: Ord a => Set a -> Bool
1652 valid t
1653 = balanced t && ordered t && validsize t
1654
1655 ordered :: Ord a => Set a -> Bool
1656 ordered t
1657 = bounded (const True) (const True) t
1658 where
1659 bounded lo hi t'
1660 = case t' of
1661 Tip -> True
1662 Bin _ x l r -> (lo x) && (hi x) && bounded lo (<x) l && bounded (>x) hi r
1663
1664 balanced :: Set a -> Bool
1665 balanced t
1666 = case t of
1667 Tip -> True
1668 Bin _ _ l r -> (size l + size r <= 1 || (size l <= delta*size r && size r <= delta*size l)) &&
1669 balanced l && balanced r
1670
1671 validsize :: Set a -> Bool
1672 validsize t
1673 = (realsize t == Just (size t))
1674 where
1675 realsize t'
1676 = case t' of
1677 Tip -> Just 0
1678 Bin sz _ l r -> case (realsize l,realsize r) of
1679 (Just n,Just m) | n+m+1 == sz -> Just sz
1680 _ -> Nothing