-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Set and bag operations on ordered lists
--   
--   This module provides set and multiset operations on ordered lists.
@package data-ordlist
@version 0.4.7.0


-- | This module implements bag and set operations on ordered lists. For
--   the purposes of this module, a "bag" (or "multiset") is a
--   non-decreasing list, whereas a "set" is a strictly ascending list.
--   Bags are sorted lists that may contain duplicates, whereas sets are
--   sorted lists that do not contain duplicates.
--   
--   Except for the <a>nub</a>, <a>sort</a>, <a>nubSort</a>, and
--   <a>isSorted</a> families of functions, every function assumes that any
--   list arguments are sorted lists. Assuming this precondition is met,
--   every resulting list is also sorted.
--   
--   Because <a>isect</a> handles multisets correctly, it does not return
--   results comparable to <tt>Data.List.<a>intersect</a></tt> on them.
--   Thus <tt>isect</tt> is more than just a more efficient
--   <tt>intersect</tt> on ordered lists. Similar statements apply to other
--   associations between functions this module and functions in
--   <tt>Data.List</tt>, such as <a>union</a> and
--   <tt>Data.List.<a>union</a></tt>.
--   
--   All functions in this module are left biased. Elements that appear in
--   earlier arguments have priority over equal elements that appear in
--   later arguments, and elements that appear earlier in a single list
--   have priority over equal elements that appear later in that list.
module Data.List.Ordered

-- | The <a>member</a> function returns <a>True</a> if the element appears
--   in the ordered list.
member :: Ord a => a -> [a] -> Bool

-- | The <a>memberBy</a> function is the non-overloaded version of
--   <a>member</a>.
memberBy :: (a -> a -> Ordering) -> a -> [a] -> Bool

-- | The <a>has</a> function returns <a>True</a> if the element appears in
--   the list; it is equivalent to <a>member</a> except the order of the
--   arguments is reversed, making it a function from an ordered list to
--   its characteristic function.
has :: Ord a => [a] -> a -> Bool

-- | The <a>hasBy</a> function is the non-overloaded version of <a>has</a>.
hasBy :: (a -> a -> Ordering) -> [a] -> a -> Bool

-- | The <a>subset</a> function returns true if the first list is a
--   sub-list of the second.
subset :: Ord a => [a] -> [a] -> Bool

-- | The <a>subsetBy</a> function is the non-overloaded version of
--   <a>subset</a>.
subsetBy :: (a -> a -> Ordering) -> [a] -> [a] -> Bool

-- | The <a>isSorted</a> predicate returns <a>True</a> if the elements of a
--   list occur in non-descending order, equivalent to
--   <tt><a>isSortedBy</a> (<a>&lt;=</a>)</tt>.
isSorted :: Ord a => [a] -> Bool

-- | The <a>isSortedBy</a> function returns <a>True</a> iff the predicate
--   returns true for all adjacent pairs of elements in the list.
isSortedBy :: (a -> a -> Bool) -> [a] -> Bool

-- | The <a>insertBag</a> function inserts an element into a list. If the
--   element is already there, then another copy of the element is
--   inserted.
insertBag :: Ord a => a -> [a] -> [a]

-- | The <a>insertBagBy</a> function is the non-overloaded version of
--   <a>insertBag</a>.
insertBagBy :: (a -> a -> Ordering) -> a -> [a] -> [a]

-- | The <a>insertSet</a> function inserts an element into an ordered list.
--   If the element is already there, then the element replaces the
--   existing element.
insertSet :: Ord a => a -> [a] -> [a]

-- | The <a>insertSetBy</a> function is the non-overloaded version of
--   <a>insertSet</a>.
insertSetBy :: (a -> a -> Ordering) -> a -> [a] -> [a]

-- | The <a>isect</a> function computes the intersection of two ordered
--   lists. An element occurs in the output as many times as the minimum
--   number of occurrences in either input. If either input is a set, then
--   the output is a set.
--   
--   <pre>
--   isect [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 3,4 ]
--   isect [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == [ 1, 2,2 ]
--   </pre>
isect :: Ord a => [a] -> [a] -> [a]

-- | The <a>isectBy</a> function is the non-overloaded version of
--   <a>isect</a>.
isectBy :: (a -> b -> Ordering) -> [a] -> [b] -> [a]

-- | The <a>union</a> function computes the union of two ordered lists. An
--   element occurs in the output as many times as the maximum number of
--   occurrences in either input. The output is a set if and only if both
--   inputs are sets.
--   
--   <pre>
--   union [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 1,2, 3,4, 5,6 ]
--   union [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == [ 1,1,1, 2,2,2 ]
--   </pre>
union :: Ord a => [a] -> [a] -> [a]

-- | The <a>unionBy</a> function is the non-overloaded version of
--   <a>union</a>.
unionBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

-- | The <a>minus</a> function computes the difference of two ordered
--   lists. An element occurs in the output as many times as it occurs in
--   the first input, minus the number of occurrences in the second input.
--   If the first input is a set, then the output is a set.
--   
--   <pre>
--   minus [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 1,2 ]
--   minus [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == [ 2 ]
--   </pre>
minus :: Ord a => [a] -> [a] -> [a]

-- | The <a>minusBy</a> function is the non-overloaded version of
--   <a>minus</a>.
minusBy :: (a -> b -> Ordering) -> [a] -> [b] -> [a]

-- | The <a>minus'</a> function computes the difference of two ordered
--   lists. The result consists of elements from the first list that do not
--   appear in the second list. If the first input is a set, then the
--   output is a set.
--   
--   <pre>
--   minus' [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 1,2 ]
--   minus' [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == []
--   minus' [ 1,1, 2,2 ] [ 2 ]          == [ 1,1 ]
--   </pre>
minus' :: Ord a => [a] -> [a] -> [a]

-- | The <a>minusBy'</a> function is the non-overloaded version of
--   <a>minus'</a>.
minusBy' :: (a -> b -> Ordering) -> [a] -> [b] -> [a]

-- | The <a>xunion</a> function computes the exclusive union of two ordered
--   lists. An element occurs in the output as many times as the absolute
--   difference between the number of occurrences in the inputs. If both
--   inputs are sets, then the output is a set.
--   
--   <pre>
--   xunion [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 1,2, 5,6 ]
--   xunion [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == [ 1,1, 2 ]
--   </pre>
xunion :: Ord a => [a] -> [a] -> [a]

-- | The <a>xunionBy</a> function is the non-overloaded version of
--   <a>xunion</a>.
xunionBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

-- | The <a>merge</a> function combines all elements of two ordered lists.
--   An element occurs in the output as many times as the sum of the
--   occurrences in both lists. The output is a set if and only if the
--   inputs are disjoint sets.
--   
--   <pre>
--   merge [ 1,2, 3,4 ] [ 3,4, 5,6 ]   == [ 1,2,  3,3,4,4,  5,6 ]
--   merge [ 1, 2,2,2 ] [ 1,1,1, 2,2 ] == [ 1,1,1,1,  2,2,2,2,2 ]
--   </pre>
merge :: Ord a => [a] -> [a] -> [a]

-- | The <a>mergeBy</a> function is the non-overloaded version of
--   <a>merge</a>.
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

-- | The <a>mergeAll</a> function merges a (potentially) infinite number of
--   ordered lists, under the assumption that the heads of the inner lists
--   are sorted. An element is duplicated in the result as many times as
--   the total number of occurrences in all inner lists.
--   
--   The <a>mergeAll</a> function is closely related to <tt><a>foldr</a>
--   <a>merge</a> []</tt>. The former does not assume that the outer list
--   is finite, whereas the latter does not assume that the heads of the
--   inner lists are sorted. When both sets of assumptions are met, these
--   two functions are equivalent.
--   
--   This implementation of <a>mergeAll</a> uses a tree of comparisons, and
--   is based on input from Dave Bayer, Heinrich Apfelmus, Omar Antolin
--   Camarena, and Will Ness. See <tt>CHANGES</tt> for details.
mergeAll :: Ord a => [[a]] -> [a]

-- | The <a>mergeAllBy</a> function is the non-overloaded variant of the
--   <a>mergeAll</a> function.
mergeAllBy :: (a -> a -> Ordering) -> [[a]] -> [a]

-- | The <a>unionAll</a> computes the union of a (potentially) infinite
--   number of lists, under the assumption that the heads of the inner
--   lists are sorted. The result will duplicate an element as many times
--   as the maximum number of occurrences in any single list. Thus, the
--   result is a set if and only if every inner list is a set.
--   
--   The <a>unionAll</a> function is closely related to <tt><a>foldr</a>
--   <a>union</a> []</tt>. The former does not assume that the outer list
--   is finite, whereas the latter does not assume that the heads of the
--   inner lists are sorted. When both sets of assumptions are met, these
--   two functions are equivalent.
--   
--   Note that there is no simple way to express <a>unionAll</a> in terms
--   of <a>mergeAll</a> or vice versa on arbitrary valid inputs. They are
--   related via <a>nub</a> however, as <tt><a>nub</a> . <a>mergeAll</a> ==
--   <a>unionAll</a> . <a>map</a> <a>nub</a></tt>. If every list is a set,
--   then <tt>map nub == id</tt>, and in this special case (and only in
--   this special case) does <tt>nub . mergeAll == unionAll</tt>.
--   
--   This implementation of <a>unionAll</a> uses a tree of comparisons, and
--   is based on input from Dave Bayer, Heinrich Apfelmus, Omar Antolin
--   Camarena, and Will Ness. See <tt>CHANGES</tt> for details.
unionAll :: Ord a => [[a]] -> [a]

-- | The <a>unionAllBy</a> function is the non-overloaded variant of the
--   <a>unionAll</a> function.
unionAllBy :: (a -> a -> Ordering) -> [[a]] -> [a]

-- | On ordered lists, <a>nub</a> is equivalent to <a>nub</a>, except that
--   it runs in linear time instead of quadratic. On unordered lists it
--   also removes elements that are smaller than any preceding element.
--   
--   <pre>
--   nub [1,1,1,2,2] == [1,2]
--   nub [2,0,1,3,3] == [2,3]
--   nub = nubBy (&lt;)
--   </pre>
nub :: Ord a => [a] -> [a]

-- | The <a>nubBy</a> function is the greedy algorithm that returns a
--   sublist of its input such that:
--   
--   <pre>
--   isSortedBy pred (nubBy pred xs) == True
--   </pre>
--   
--   This is true for all lists, not just ordered lists, and all binary
--   predicates, not just total orders. On infinite lists, this statement
--   is true in a certain mathematical sense, but not a computational one.
nubBy :: (a -> a -> Bool) -> [a] -> [a]

-- | The <a>sort</a> function implements a stable sorting algorithm. It is
--   a special case of <a>sortBy</a>, which allows the programmer to supply
--   their own comparison function.
sort :: Ord a => [a] -> [a]

-- | The <a>sortBy</a> function is the non-overloaded version of
--   <a>sort</a>.
sortBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | Sort a list by comparing the results of a key function applied to each
--   element. <tt>sortOn f</tt> is equivalent to <tt>sortBy (comparing
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list. This is called the
--   decorate-sort-undecorate paradigm, or Schwartzian transform.
sortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | This variant of <a>sortOn</a> recomputes the sorting key every
--   comparison. This can be better for functions that are cheap to
--   compute. This is definitely better for projections, as the
--   decorate-sort-undecorate saves nothing and adds two traversals of the
--   list and extra memory allocation.
sortOn' :: Ord b => (a -> b) -> [a] -> [a]

-- | The <a>nubSort</a> function is equivalent to <tt><a>nub</a> <a>.</a>
--   <a>sort</a></tt>, except that duplicates are removed as it sorts. It
--   is essentially the same implementation as <tt>Data.List.sort</tt>,
--   with <a>merge</a> replaced by <a>union</a>. Thus the performance of
--   <a>nubSort</a> should better than or nearly equal to <a>sort</a>
--   alone. It is faster than both <a>sort</a> and <tt><a>nub</a> <a>.</a>
--   <a>sort</a></tt> when the input contains significant quantities of
--   duplicated elements.
nubSort :: Ord a => [a] -> [a]

-- | The <a>nubSortBy</a> function is the non-overloaded version of
--   <a>nubSort</a>.
nubSortBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | The <a>nubSortOn</a> function provides decorate-sort-undecorate for
--   <a>nubSort</a>.
nubSortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | This variant of <a>nubSortOn</a> recomputes the sorting key for each
--   comparison
nubSortOn' :: Ord b => (a -> b) -> [a] -> [a]

-- | The function <tt><a>foldt</a> plus zero</tt> computes the sum of a
--   list using a sequence of balanced trees of operations. Given an
--   appropriate <tt>plus</tt> operator, this function can be productive on
--   an infinite list, hence it is lazier than <a>foldt'</a>. <a>foldt</a>
--   is used in the implementation of <a>mergeAll</a> and <a>unionAll</a>.
foldt :: (a -> a -> a) -> a -> [a] -> a

-- | The function <tt><a>foldt'</a> plus zero</tt> computes the sum of a
--   list using a balanced tree of operations. <a>foldt'</a> necessarily
--   diverges on infinite lists, hence it is a stricter variant of
--   <a>foldt</a>. <a>foldt'</a> is used in the implementation of
--   <a>sort</a> and <a>nubSort</a>.
foldt' :: (a -> a -> a) -> a -> [a] -> a
