-- 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.2


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>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 where mapMaybe f = catMaybes . fmap f catMaybes = mapMaybe id filter f = mapMaybe $ \ a -> if f a then Just a else Nothing

-- | 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>filter</a> f . <a>filter</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>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 where wither f = fmap catMaybes . traverse f filterA = filterAOf wither

-- | <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>
--   <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)

-- | A variant of <a>wither</a> that works on <a>MaybeT</a>.
witherM :: (Witherable t, Monad m) => (a -> MaybeT m b) -> t a -> m (t b)

-- | <a>blightM</a> is <a>witherM</a> with its arguments flipped.
blightM :: (Monad m, Witherable t) => t a -> (a -> MaybeT m b) -> m (t b)

-- | 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 comparion (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 GHC.Base.Functor (Data.Witherable.Peat a b)
instance GHC.Base.Applicative (Data.Witherable.Peat a b)
instance Data.Witherable.Filterable GHC.Base.Maybe
instance Data.Witherable.Witherable GHC.Base.Maybe
instance GHC.Base.Monoid e => Data.Witherable.Filterable (Data.Either.Either e)
instance GHC.Base.Monoid e => Data.Witherable.Witherable (Data.Either.Either e)
instance Data.Witherable.Filterable []
instance Data.Witherable.Witherable []
instance Data.Witherable.Filterable Data.IntMap.Base.IntMap
instance Data.Witherable.Witherable Data.IntMap.Base.IntMap
instance Data.Witherable.Filterable (Data.Map.Base.Map k)
instance Data.Witherable.Witherable (Data.Map.Base.Map k)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Witherable.Filterable (Data.HashMap.Base.HashMap k)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Witherable.Witherable (Data.HashMap.Base.HashMap k)
instance Data.Witherable.Filterable Data.Proxy.Proxy
instance Data.Witherable.Witherable Data.Proxy.Proxy
instance Data.Witherable.Filterable (Data.Functor.Const.Const r)
instance Data.Witherable.Witherable (Data.Functor.Const.Const r)
instance Data.Witherable.Filterable Data.Vector.Vector
instance Data.Witherable.Witherable Data.Vector.Vector
instance Data.Witherable.Filterable Data.Sequence.Seq
instance Data.Witherable.Witherable Data.Sequence.Seq
instance (GHC.Base.Functor f, Data.Witherable.Filterable g) => Data.Witherable.Filterable (Data.Functor.Compose.Compose f g)
instance (Data.Traversable.Traversable f, Data.Witherable.Witherable g) => Data.Witherable.Witherable (Data.Functor.Compose.Compose f g)
instance GHC.Base.Functor f => Data.Witherable.Filterable (Control.Monad.Trans.Maybe.MaybeT f)
instance Data.Traversable.Traversable t => Data.Witherable.Witherable (Control.Monad.Trans.Maybe.MaybeT t)