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


-- | filterable traversable
--   
--   A stronger variant of <a>traverse</a> which can remove elements and
--   generalised mapMaybe, catMaybes, filter
@package witherable
@version 0.3


module Data.Witherable

-- | Like <a>Functor</a>, but it include <a>Maybe</a> effects.
--   
--   Formally, the class <a>Filterable</a> represents a functor from
--   <tt>Kleisli Maybe</tt> to <tt>Hask</tt>.
--   
--   A definition of <a>mapMaybe</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>identity</i></i> <tt><a>mapMaybe</a> Just ≡ id</tt></li>
--   <li><i><i>conservation</i></i> <tt><a>mapMaybe</a> (Just . f) ≡
--   <a>fmap</a> f</tt></li>
--   <li><i><i>composition</i></i> <tt><a>mapMaybe</a> f . <a>mapMaybe</a>
--   g ≡ <a>mapMaybe</a> (f &lt;=&lt; g)</tt></li>
--   </ul>
class Functor f => Filterable f

-- | Like <a>mapMaybe</a>.
mapMaybe :: Filterable f => (a -> Maybe b) -> f a -> f b

-- | <pre>
--   <a>catMaybes</a> ≡ <a>mapMaybe</a> <a>id</a>
--   </pre>
catMaybes :: Filterable f => f (Maybe a) -> f a

-- | <pre>
--   <a>Filterable</a> f . <a>Filterable</a> g ≡ filter (<a>liftA2</a> (<a>&amp;&amp;</a>) f g)
--   </pre>
filter :: Filterable f => (a -> Bool) -> f a -> f a

-- | Like <a>Traversable</a>, but you can remove elements instead of
--   updating them.
--   
--   A definition of <a>wither</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>identity</i></i> <tt><a>wither</a> (<a>pure</a> . Just) ≡
--   <a>pure</a></tt></li>
--   <li><i><i>conservation</i></i> <tt><a>wither</a> (<a>fmap</a>
--   <a>Just</a> . f) ≡ <a>traverse</a> f</tt></li>
--   <li><i><i>composition</i></i> <tt><a>Compose</a> . <a>fmap</a>
--   (<a>wither</a> f) . <a>wither</a> g ≡ <a>wither</a> (<a>Compose</a> .
--   <a>fmap</a> (<a>wither</a> f) . g)</tt></li>
--   </ul>
--   
--   Parametricity implies the naturality law:
--   
--   <pre>
--   t . <a>wither</a> f ≡ <a>wither</a> (t . f)
--   </pre>
class (Traversable t, Filterable t) => Witherable t

-- | <pre>
--   <a>traverse</a> f ≡ <a>wither</a> (<a>fmap</a> <a>Just</a> . f)
--   </pre>
wither :: (Witherable t, Applicative f) => (a -> f (Maybe b)) -> t a -> f (t b)

-- | <pre>
--   Monadic variant of <a>wither</a>. This may have more efficient implementation.
--   </pre>
witherM :: (Witherable t, Monad m) => (a -> m (Maybe b)) -> t a -> m (t b)

-- | <pre>
--   <a>Compose</a> . <a>fmap</a> (<a>filterA</a> f) . <a>filterA</a> g ≡ <a>filterA</a> (x -&gt; <a>Compose</a> $ <a>fmap</a> (b -&gt; (b&amp;&amp;) <a>$</a> f x) (g x)
--   </pre>
filterA :: (Witherable t, Applicative f) => (a -> f Bool) -> t a -> f (t a)

-- | Removes duplicate elements from a list, keeping only the first
--   occurrence. This is asymptotically faster than using <a>nub</a> from
--   <a>Data.List</a>.
ordNub :: (Witherable t, Ord a) => t a -> t a

-- | Removes duplicate elements from a list, keeping only the first
--   occurrence. This is usually faster than <a>ordNub</a>, especially for
--   things that have a slow comparison (like <a>String</a>).
hashNub :: (Witherable t, Eq a, Hashable a) => t a -> t a

-- | <pre>
--   <a>forMaybe</a> = <a>flip</a> <a>wither</a>
--   </pre>
forMaybe :: (Witherable t, Applicative f) => t a -> (a -> f (Maybe b)) -> f (t b)

-- | This type allows combinators to take a <a>Filter</a> specializing the
--   parameter <tt>f</tt>.
type FilterLike f s t a b = (a -> f (Maybe b)) -> s -> f t

-- | A <a>Filter</a> is like a <a>Traversal</a>, but you can also remove
--   targets.
type Filter s t a b = forall f. Applicative f => FilterLike f s t a b

-- | A simple <a>FilterLike</a>.
type FilterLike' f s a = FilterLike f s s a a

-- | A simple <a>Filter</a>.
type Filter' s a = forall f. Applicative f => FilterLike' f s a

-- | <a>witherOf</a> is actually <a>id</a>, but left for consistency.
witherOf :: FilterLike f s t a b -> (a -> f (Maybe b)) -> s -> f t

-- | <pre>
--   <a>forMaybeOf</a> ≡ <a>flip</a>
--   </pre>
forMaybeOf :: FilterLike f s t a b -> s -> (a -> f (Maybe b)) -> f t

-- | <a>mapMaybe</a> through a filter.
mapMaybeOf :: FilterLike Identity s t a b -> (a -> Maybe b) -> s -> t

-- | <a>catMaybes</a> through a filter.
catMaybesOf :: FilterLike Identity s t (Maybe a) a -> s -> t

-- | <a>filterA</a> through a filter.
filterAOf :: Functor f => FilterLike' f s a -> (a -> f Bool) -> s -> f s

-- | Filter each element of a structure targeted by a <a>Filter</a>.
filterOf :: FilterLike' Identity s a -> (a -> Bool) -> s -> s

-- | Remove the duplicate elements through a filter.
ordNubOf :: Ord a => FilterLike' (State (Set a)) s a -> s -> s

-- | Remove the duplicate elements through a filter. It is often faster
--   than <a>ordNubOf</a>, especially when the comparison is expensive.
hashNubOf :: (Eq a, Hashable a) => FilterLike' (State (HashSet a)) s a -> s -> s

-- | Reconstitute a <a>Filter</a> from its monomorphic form.
cloneFilter :: FilterLike (Peat a b) s t a b -> Filter s t a b

-- | This is used to characterize and clone a <a>Filter</a>. Since
--   <tt>FilterLike (Peat a b) s t a b</tt> is monomorphic, it can be used
--   to store a filter in a container.
newtype Peat a b t
Peat :: (forall f. Applicative f => (a -> f (Maybe b)) -> f t) -> Peat a b t
[runPeat] :: Peat a b t -> forall f. Applicative f => (a -> f (Maybe b)) -> f t
instance Data.Witherable.Witherable GHC.Maybe.Maybe
instance GHC.Base.Monoid e => Data.Witherable.Witherable (Data.Either.Either e)
instance Data.Witherable.Witherable []
instance Data.Witherable.Witherable Data.IntMap.Internal.IntMap
instance Data.Witherable.Witherable (Data.Map.Internal.Map k)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Witherable.Witherable (Data.HashMap.Base.HashMap k)
instance Data.Witherable.Witherable Data.Proxy.Proxy
instance Data.Witherable.Witherable (Data.Functor.Const.Const r)
instance Data.Witherable.Witherable Data.Vector.Vector
instance Data.Witherable.Witherable Data.Sequence.Internal.Seq
instance (Data.Traversable.Traversable f, Data.Witherable.Witherable g) => Data.Witherable.Witherable (Data.Functor.Compose.Compose f g)
instance (Data.Witherable.Witherable f, Data.Witherable.Witherable g) => Data.Witherable.Witherable (Data.Functor.Product.Product f g)
instance (Data.Witherable.Witherable f, Data.Witherable.Witherable g) => Data.Witherable.Witherable (Data.Functor.Sum.Sum f g)
instance Data.Witherable.Witherable f => Data.Witherable.Witherable (Control.Monad.Trans.Identity.IdentityT f)
instance Data.Traversable.Traversable t => Data.Witherable.Witherable (Control.Monad.Trans.Maybe.MaybeT t)
instance Data.Witherable.Filterable GHC.Maybe.Maybe
instance GHC.Base.Monoid e => Data.Witherable.Filterable (Data.Either.Either e)
instance Data.Witherable.Filterable []
instance Data.Witherable.Filterable Data.IntMap.Internal.IntMap
instance Data.Witherable.Filterable (Data.Map.Internal.Map k)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Witherable.Filterable (Data.HashMap.Base.HashMap k)
instance Data.Witherable.Filterable Data.Proxy.Proxy
instance Data.Witherable.Filterable (Data.Functor.Const.Const r)
instance Data.Witherable.Filterable Data.Vector.Vector
instance Data.Witherable.Filterable Data.Sequence.Internal.Seq
instance (GHC.Base.Functor f, Data.Witherable.Filterable g) => Data.Witherable.Filterable (Data.Functor.Compose.Compose f g)
instance (Data.Witherable.Filterable f, Data.Witherable.Filterable g) => Data.Witherable.Filterable (Data.Functor.Product.Product f g)
instance (Data.Witherable.Filterable f, Data.Witherable.Filterable g) => Data.Witherable.Filterable (Data.Functor.Sum.Sum f g)
instance Data.Witherable.Filterable f => Data.Witherable.Filterable (Control.Monad.Trans.Identity.IdentityT f)
instance GHC.Base.Functor f => Data.Witherable.Filterable (Control.Monad.Trans.Maybe.MaybeT f)
instance GHC.Base.Functor (Data.Witherable.Peat a b)
instance GHC.Base.Applicative (Data.Witherable.Peat a b)