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


-- | A Difference Monoid, to add subtraction to arbitrary monoids. Please
--   see the README on Github at
--   <a>https://github.com/oisdk/difference-monoid#readme</a>
@package difference-monoid
@version 0.1.0.0


module Data.Monoid.Odd

-- | A monoid over XOR.
newtype Odd
Odd :: Bool -> Odd
[getOdd] :: Odd -> Bool
instance Control.DeepSeq.NFData Data.Monoid.Odd.Odd
instance Foreign.Storable.Storable Data.Monoid.Odd.Odd
instance Data.Bits.Bits Data.Monoid.Odd.Odd
instance Data.Bits.FiniteBits Data.Monoid.Odd.Odd
instance GHC.Generics.Generic Data.Monoid.Odd.Odd
instance GHC.Arr.Ix Data.Monoid.Odd.Odd
instance GHC.Read.Read Data.Monoid.Odd.Odd
instance Data.Data.Data Data.Monoid.Odd.Odd
instance GHC.Enum.Enum Data.Monoid.Odd.Odd
instance GHC.Enum.Bounded Data.Monoid.Odd.Odd
instance GHC.Show.Show Data.Monoid.Odd.Odd
instance GHC.Classes.Ord Data.Monoid.Odd.Odd
instance GHC.Classes.Eq Data.Monoid.Odd.Odd
instance Data.Semigroup.Semigroup Data.Monoid.Odd.Odd
instance GHC.Base.Monoid Data.Monoid.Odd.Odd
instance Data.Group.Group Data.Monoid.Odd.Odd

module Data.Monoid.Diff.Internal

-- | The Difference Monoid.
data Diff a
(:-:) :: !a -> !a -> Diff a

-- | Lift a monoid into the difference monoid.
--   
--   <pre>
--   &gt;&gt;&gt; diff (Sum 1)
--   Sum {getSum = 1} :-: Sum {getSum = 0}
--   </pre>
diff :: Monoid a => a -> Diff a

-- | The inverse of <a>diff</a>.
--   
--   <pre>
--   <a>retract</a> <a>.</a> <a>diff</a> = <a>id</a>
--   </pre>
retract :: Group a => Diff a -> a

-- | A group homomorphism given a monoid homomorphism.
foldDiff :: Group b => (a -> b) -> Diff a -> b

-- | Given a "normalizing" function, try simplify the representation.
--   
--   For instance, one such normalizing function may be to take the numeric
--   difference of two types:
--   
--   <pre>
--   &gt;&gt;&gt; let sumNorm x y = if x &gt;= y then (x - y, 0) else (0, y - x)
--   
--   &gt;&gt;&gt; normalize sumNorm ((foldMap (diff.Sum) [1..10]) &lt;&gt; (invert (foldMap (diff.Sum) [1..5])))
--   Sum {getSum = 40} :-: Sum {getSum = 0}
--   </pre>
normalize :: (a -> a -> (a, a)) -> Diff a -> Diff a

-- | Interpret the difference using a subtraction function.
runDiff :: (a -> a -> b) -> Diff a -> b

-- | The <a>Parity</a> <a>Comonad</a>. It is left-adjunct to <a>Diff</a>.
newtype Parity a
Parity :: (Odd, a) -> Parity a
[runParity] :: Parity a -> (Odd, a)
instance Control.Comonad.Env.Class.ComonadEnv Data.Monoid.Odd.Odd Data.Monoid.Diff.Internal.Parity
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Monoid.Diff.Internal.Parity a)
instance Data.Semigroup.Semigroup a => Data.Semigroup.Semigroup (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Arr.Ix a => GHC.Arr.Ix (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Monoid.Diff.Internal.Parity a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Monoid.Diff.Internal.Parity a)
instance Control.Comonad.ComonadApply Data.Monoid.Diff.Internal.Parity
instance Control.Comonad.Comonad Data.Monoid.Diff.Internal.Parity
instance Data.Functor.Extend.Extend Data.Monoid.Diff.Internal.Parity
instance Data.Functor.Bind.Class.Bind Data.Monoid.Diff.Internal.Parity
instance Data.Functor.Bind.Class.Apply Data.Monoid.Diff.Internal.Parity
instance GHC.Base.Monad Data.Monoid.Diff.Internal.Parity
instance GHC.Base.Applicative Data.Monoid.Diff.Internal.Parity
instance Data.Semigroup.Foldable.Class.Foldable1 Data.Monoid.Diff.Internal.Parity
instance Data.Traversable.Traversable Data.Monoid.Diff.Internal.Parity
instance Data.Foldable.Foldable Data.Monoid.Diff.Internal.Parity
instance GHC.Base.Functor Data.Monoid.Diff.Internal.Parity
instance GHC.Generics.Generic1 Data.Monoid.Diff.Internal.Diff
instance GHC.Generics.Generic (Data.Monoid.Diff.Internal.Diff a)
instance Data.Data.Data a => Data.Data.Data (Data.Monoid.Diff.Internal.Diff a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Monoid.Diff.Internal.Diff a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Monoid.Diff.Internal.Diff a)
instance Data.Semigroup.Traversable.Class.Traversable1 Data.Monoid.Diff.Internal.Parity
instance Control.Monad.Fix.MonadFix Data.Monoid.Diff.Internal.Parity
instance Data.Functor.Adjunction.Adjunction Data.Monoid.Diff.Internal.Parity Data.Monoid.Diff.Internal.Diff
instance GHC.Base.Functor Data.Monoid.Diff.Internal.Diff
instance Data.Foldable.Foldable Data.Monoid.Diff.Internal.Diff
instance Data.Traversable.Traversable Data.Monoid.Diff.Internal.Diff
instance GHC.Base.Applicative Data.Monoid.Diff.Internal.Diff
instance GHC.Base.Monad Data.Monoid.Diff.Internal.Diff
instance Data.Functor.Bind.Class.Bind Data.Monoid.Diff.Internal.Diff
instance Data.Semigroup.Semigroup a => Data.Semigroup.Semigroup (Data.Monoid.Diff.Internal.Diff a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Monoid.Diff.Internal.Diff a)
instance GHC.Base.Monoid a => Data.Group.Group (Data.Monoid.Diff.Internal.Diff a)
instance (GHC.Classes.Eq a, Data.Semigroup.Semigroup a) => GHC.Classes.Eq (Data.Monoid.Diff.Internal.Diff a)
instance (GHC.Classes.Ord a, Data.Semigroup.Semigroup a) => GHC.Classes.Ord (Data.Monoid.Diff.Internal.Diff a)
instance Control.Monad.Fix.MonadFix Data.Monoid.Diff.Internal.Diff
instance Control.Monad.Zip.MonadZip Data.Monoid.Diff.Internal.Diff
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Diff.Internal.Diff a)
instance Data.Distributive.Distributive Data.Monoid.Diff.Internal.Diff
instance Data.Functor.Rep.Representable Data.Monoid.Diff.Internal.Diff
instance Data.Semigroup.Foldable.Class.Foldable1 Data.Monoid.Diff.Internal.Diff
instance Data.Semigroup.Traversable.Class.Traversable1 Data.Monoid.Diff.Internal.Diff
instance Data.Functor.Bind.Class.Apply Data.Monoid.Diff.Internal.Diff
instance Control.Comonad.Comonad Data.Monoid.Diff.Internal.Diff
instance Control.Comonad.ComonadApply Data.Monoid.Diff.Internal.Diff
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Monoid.Diff.Internal.Diff a)
instance Data.Functor.Classes.Show1 Data.Monoid.Diff.Internal.Diff
instance Data.Functor.Classes.Read1 Data.Monoid.Diff.Internal.Diff
instance Data.Functor.Extend.Extend Data.Monoid.Diff.Internal.Diff


-- | This module provides the Difference Monoid, which adds subtraction to
--   arbitrary monoids.
--   
--   This has a number of uses:
--   
--   <ul>
--   <li><tt><a>Diff</a> (<a>Product</a> a)</tt> will give you a type
--   similar to <a>Ratio</a>. Here, the "subtraction" operation is
--   division. For example:<pre>&gt;&gt;&gt; (1 :-: 2) &lt;&gt; (3 :-: 4)
--   :: Diff (Product Int) Product {getProduct = 3} :-: Product {getProduct
--   = 8} </pre></li>
--   <li>In a similar vein, <tt><a>Diff</a> (<a>Sum</a> a)</tt> will add
--   subtraction to a numeric type:<pre>&gt;&gt;&gt; runDiff (-) (diff 2
--   &lt;&gt; diff 3 &lt;&gt; invert (diff 4)) :: Sum Natural Sum {getSum =
--   1} </pre>This will let you work with nonnegative types, where you need
--   some form of subtraction (for, e.g., differences, hence the name), and
--   you only want to check for underflow once.</li>
--   <li>Using the above example, in particular, we get a monoid for
--   averages:<pre>&gt;&gt;&gt; import Data.Function (on) &gt;&gt;&gt; let
--   avg = runDiff ((%) `on` getProduct.getSum) . foldMap (fmap Sum . diff
--   . Product) &gt;&gt;&gt; avg [1,4,3,2,5] 3 % 1 </pre></li>
--   </ul>
--   
--   The <a>Monoid</a> and <a>Semigroup</a> laws hold in a pretty
--   straightforward way, provided the underlying type also follows those
--   laws.
--   
--   For the <a>Group</a> laws, the underlying type must be a cancellative
--   semigroup.
--   
--   A cancellative semigroup is one where
--   
--   <ul>
--   <li><tt>a <a>&lt;&gt;</a> b = a <a>&lt;&gt;</a> c</tt> implies <tt>b =
--   c</tt></li>
--   <li><tt>b <a>&lt;&gt;</a> a = c <a>&lt;&gt;</a> a</tt> implies <tt>b =
--   c</tt></li>
--   </ul>
--   
--   If this does not hold, than the equivalence only holds modulo the the
--   addition of some constant
--   
--   Most common semigroups are cancellative, however notable exceptions
--   include the cross product of vectors, matrix multiplication, and sets:
--   
--   <pre>
--   <a>fromList</a> [1] <a>&lt;&gt;</a> <a>fromList</a> [1,2] = <a>fromList</a> [1] <a>&lt;&gt;</a> <a>fromList</a> [2]
--   </pre>
--   
--   This type is known formally as the <a>Grothendieck group</a>.
module Data.Monoid.Diff

-- | The Difference Monoid.
data Diff a
(:-:) :: !a -> !a -> Diff a

-- | Lift a monoid into the difference monoid.
--   
--   <pre>
--   &gt;&gt;&gt; diff (Sum 1)
--   Sum {getSum = 1} :-: Sum {getSum = 0}
--   </pre>
diff :: Monoid a => a -> Diff a

-- | The inverse of <a>diff</a>.
--   
--   <pre>
--   <a>retract</a> <a>.</a> <a>diff</a> = <a>id</a>
--   </pre>
retract :: Group a => Diff a -> a

-- | A group homomorphism given a monoid homomorphism.
foldDiff :: Group b => (a -> b) -> Diff a -> b

-- | Interpret the difference using a subtraction function.
runDiff :: (a -> a -> b) -> Diff a -> b

-- | Given a "normalizing" function, try simplify the representation.
--   
--   For instance, one such normalizing function may be to take the numeric
--   difference of two types:
--   
--   <pre>
--   &gt;&gt;&gt; let sumNorm x y = if x &gt;= y then (x - y, 0) else (0, y - x)
--   
--   &gt;&gt;&gt; normalize sumNorm ((foldMap (diff.Sum) [1..10]) &lt;&gt; (invert (foldMap (diff.Sum) [1..5])))
--   Sum {getSum = 40} :-: Sum {getSum = 0}
--   </pre>
normalize :: (a -> a -> (a, a)) -> Diff a -> Diff a

-- | A <a>Group</a> is a <a>Monoid</a> plus a function, <a>invert</a>, such
--   that:
--   
--   <pre>
--   a &lt;&gt; invert a == mempty
--   </pre>
--   
--   <pre>
--   invert a &lt;&gt; a == mempty
--   </pre>
class Monoid m => Group m
invert :: Group m => m -> m

-- | <pre>
--   <a>pow</a> a n == a &lt;&gt; a &lt;&gt; ... &lt;&gt; a
--   </pre>
--   
--   <pre>
--   (n lots of a)
--   </pre>
--   
--   If n is negative, the result is inverted.
pow :: (Group m, Integral x) => m -> x -> m


module Control.Monad.Parity

-- | The <a>Parity</a> <a>Comonad</a>. It is left-adjunct to <a>Diff</a>.
newtype Parity a
Parity :: (Odd, a) -> Parity a
[runParity] :: Parity a -> (Odd, a)