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


-- | An algebraic data type similar to Prelude Ordering.
--   
--   Typically this is used as the return type of a combining comparison,
--   which combines two values if they are deemed equal in some sense.
--   Currently combining comparisons are used extensively by the AVL tree
--   package (AvlTree). This package is no longer actively maintained and
--   will be tagged as such as soon as Hackage has this feature.
@package COrdering
@version 2.2


-- | This module defines a useful variant of the <a>Prelude</a>
--   <a>Ordering</a> data type.
--   
--   Typically this data type is used as the result of a "combining
--   comparison" which combines values that are deemed to be equal
--   (somehow). Note that the functions defined here adhere to the same
--   ordering convention as the overloaded <a>compare</a> (from the
--   <a>Ord</a> class). That is..
--   
--   <pre>
--   a `compare` b -&gt; LT (or Lt) implies a &lt; b
--   a `compare` b -&gt; GT (or Gt) implies a &gt; b
--   </pre>
--   
--   The combinators exported from this module have a "CC" suffix if they
--   return a combining comparison (most of them) and a "C" suffix if they
--   return an ordinary comparison. All the combinators defined here are
--   INLINEd, in the hope that the compiler can avoid the overhead of using
--   HOFs for frequently used comparisons (dunno if this does any good
--   though :-)
module Data.COrdering

-- | Result of a combining comparison.
data COrdering a
Lt :: COrdering a
Eq :: a -> COrdering a
Gt :: COrdering a

-- | A combining comparison for an instance of <a>Ord</a> which returns
--   unit () where appropriate.
unitCC :: (Ord a) => (a -> a -> COrdering ())

-- | Create a combining comparison from an ordinary comparison by returning
--   unit () where appropriate.
unitByCC :: (a -> b -> Ordering) -> (a -> b -> COrdering ())

-- | A combining comparison for an instance of <a>Ord</a> which keeps the
--   first argument if they are deemed equal. The second argument is
--   discarded in this case.
fstCC :: (Ord a) => (a -> a -> COrdering a)

-- | Create a combining comparison from an ordinary comparison by keeping
--   the first argument if they are deemed equal. The second argument is
--   discarded in this case.
fstByCC :: (a -> b -> Ordering) -> (a -> b -> COrdering a)

-- | A combining comparison for an instance of <a>Ord</a> which keeps the
--   second argument if they are deemed equal. The first argument is
--   discarded in this case.
sndCC :: (Ord a) => (a -> a -> COrdering a)

-- | Create a combining comparison from an ordinary comparison by keeping
--   the second argument if they are deemed equal. The first argument is
--   discarded in this case.
sndByCC :: (a -> b -> Ordering) -> (a -> b -> COrdering b)

-- | Converts a comparison to one which takes arguments in flipped order,
--   but preserves the ordering that would be given by the "unflipped"
--   version (disregarding type issues). So it's not the same as using the
--   prelude <a>flip</a> (which would reverse the ordering too).
flipC :: (a -> b -> Ordering) -> (b -> a -> Ordering)

-- | Converts a combining comparison to one which takes arguments in
--   flipped order, but preserves the ordering that would be given by the
--   "unflipped" version (disregarding type issues). So it's not the same
--   as using the prelude <a>flip</a> (which would reverse the ordering
--   too).
flipCC :: (a -> b -> COrdering c) -> (b -> a -> COrdering c)

-- | Create a combining comparison using the supplied combining function,
--   which is applied if <a>compare</a> returns <a>EQ</a>. See
--   <a>withCC'</a> for a stricter version of this function.
withCC :: (Ord a) => (a -> a -> b) -> (a -> a -> COrdering b)

-- | Same as <a>withCC</a>, except the combining function is applied
--   strictly.
withCC' :: (Ord a) => (a -> a -> b) -> (a -> a -> COrdering b)

-- | Create a combining comparison using the supplied comparison and
--   combining function, which is applied if the comparison returns
--   <a>EQ</a>. See <a>withByCC'</a> for a stricter version of this
--   function.
withByCC :: (a -> b -> Ordering) -> (a -> b -> c) -> (a -> b -> COrdering c)

-- | Same as <a>withByCC</a>, except the combining function is applied
--   strictly.
withByCC' :: (a -> b -> Ordering) -> (a -> b -> c) -> (a -> b -> COrdering c)
instance (Eq a) => Eq (COrdering a)
instance (Ord a) => Ord (COrdering a)
instance (Read a) => Read (COrdering a)
instance (Show a) => Show (COrdering a)
instance Typeable1 COrdering