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


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


module Witherable

-- | Like <a>Functor</a>, but you can remove elements instead of updating
--   them.
--   
--   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>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 :: Type -> Type)

-- | 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>) g f)
--   </pre>
filter :: Filterable f => (a -> Bool) -> f a -> f a

-- | Empty a filterable.
--   
--   <pre>
--   <a>drain</a> ≡ <a>mapMaybe</a> (const Nothing)
--   </pre>
drain :: Filterable f => f a -> f b

-- | An infix alias for <a>mapMaybe</a>. The name of the operator alludes
--   to <a>&lt;$&gt;</a>, and has the same fixity.
(<$?>) :: Filterable f => (a -> Maybe b) -> f a -> f b
infixl 4 <$?>

-- | Flipped version of <a>&lt;$?&gt;</a>, the <a>Filterable</a> version of
--   <a>&lt;&amp;&gt;</a>. It has the same fixity as <a>&lt;&amp;&gt;</a>.
--   
--   <pre>
--   (<a>&lt;&amp;?&gt;</a>) = <a>flip</a> <a>mapMaybe</a>
--   </pre>
(<&?>) :: Filterable f => f a -> (a -> Maybe b) -> f b
infixl 1 <&?>

-- | An enhancement of <a>Traversable</a> with <a>Filterable</a>
--   
--   A definition of <a>wither</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>identity</i></i> <tt><a>wither</a> (<a>Identity</a> . Just)
--   ≡ <a>Identity</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:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>wither</a> f ≡ <a>wither</a>
--   (t . f)</tt>Where <tt>t</tt> is an /<i>applicative transformation</i>/
--   in the sense described in the <a>Traversable</a> documentation.</li>
--   </ul>
--   
--   In the relation to superclasses, these should satisfy too:
--   
--   <ul>
--   <li><i><i>conservation</i></i> <tt><a>wither</a> (<a>fmap</a> Just .
--   f) = <a>traverse</a> f</tt></li>
--   <li><i><i>pure filter</i></i> <tt><a>wither</a> (<a>Identity</a> . f)
--   = <a>Identity</a> . <a>mapMaybe</a> f</tt></li>
--   </ul>
--   
--   See the <tt>Properties.md</tt> and <tt>Laws.md</tt> files in the git
--   distribution for more in-depth explanation about properties of
--   <tt>Witherable</tt> containers.
--   
--   The laws and restrictions are enough to constrain
--   <tt><a>wither</a></tt> to be uniquely determined as the following
--   default implementation.
--   
--   <pre>
--   wither f = fmap <a>catMaybes</a> . <a>traverse</a> f
--   </pre>
--   
--   If not to provide better-performing implementation, it's not necessary
--   to implement any one method of <tt>Witherable</tt>. For example, if a
--   type constructor <tt>T</tt> already has instances of
--   <a>Traversable</a> and <a>Filterable</a>, the next one line is
--   sufficient to provide the <tt>Witherable T</tt> instance.
--   
--   <pre>
--   instance Witherable T
--   </pre>
class (Traversable t, Filterable t) => Witherable (t :: Type -> Type)

-- | Effectful <a>mapMaybe</a>.
--   
--   <pre>
--   <a>wither</a> (<a>pure</a> . f) ≡ <a>pure</a> . <a>mapMaybe</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)
filterA :: (Witherable t, Applicative f) => (a -> f Bool) -> t a -> f (t a)
witherMap :: (Witherable t, Applicative m) => (t b -> r) -> (a -> m (Maybe b)) -> t a -> m r

-- | 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>.
--   
--   <pre>
--   &gt;&gt;&gt; ordNub [3,2,1,3,2,1]
--   [3,2,1]
--   </pre>
ordNub :: (Witherable t, Ord a) => t a -> t a

-- | The <a>ordNubOn</a> function behaves just like <a>ordNub</a>, except
--   it uses a another type to determine equivalence classes.
--   
--   <pre>
--   &gt;&gt;&gt; ordNubOn fst [(True, 'x'), (False, 'y'), (True, 'z')]
--   [(True,'x'),(False,'y')]
--   </pre>
ordNubOn :: (Witherable t, Ord b) => (a -> b) -> 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>).
--   
--   <pre>
--   &gt;&gt;&gt; hashNub [3,2,1,3,2,1]
--   [3,2,1]
--   </pre>
hashNub :: (Witherable t, Eq a, Hashable a) => t a -> t a

-- | The <a>hashNubOn</a> function behaves just like <a>hashNub</a>, except
--   it uses a another type to determine equivalence classes.
--   
--   <pre>
--   &gt;&gt;&gt; hashNubOn fst [(True, 'x'), (False, 'y'), (True, 'z')]
--   [(True,'x'),(False,'y')]
--   </pre>
hashNubOn :: (Witherable t, Eq b, Hashable b) => (a -> b) -> 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)

-- | Indexed variant of <a>Filterable</a>.
class (FunctorWithIndex i t, Filterable t) => FilterableWithIndex i (t :: Type -> Type) | t -> i
imapMaybe :: FilterableWithIndex i t => (i -> a -> Maybe b) -> t a -> t b

-- | <pre>
--   <a>filter</a> f . <a>ifilter</a> g ≡ ifilter (i x -&gt; f x <a>&amp;&amp;</a> g i x)
--   </pre>
ifilter :: FilterableWithIndex i t => (i -> a -> Bool) -> t a -> t a

-- | Indexed variant of <a>Witherable</a>.
class (TraversableWithIndex i t, FilterableWithIndex i t, Witherable t) => WitherableWithIndex i (t :: Type -> Type) | t -> i

-- | Effectful <a>imapMaybe</a>.
--   
--   <pre>
--   <a>iwither</a> ( i -&gt; <a>pure</a> . f i) ≡ <a>pure</a> . <a>imapMaybe</a> f
--   </pre>
iwither :: (WitherableWithIndex i t, Applicative f) => (i -> a -> f (Maybe b)) -> t a -> f (t b)

-- | <pre>
--   Monadic variant of <a>wither</a>. This may have more efficient implementation.
--   </pre>
iwitherM :: (WitherableWithIndex i t, Monad m) => (i -> a -> m (Maybe b)) -> t a -> m (t b)
ifilterA :: (WitherableWithIndex i t, Applicative f) => (i -> a -> f Bool) -> t a -> f (t a)
newtype WrappedFoldable (f :: Type -> Type) a
WrapFilterable :: f a -> WrappedFoldable (f :: Type -> Type) a
[unwrapFoldable] :: WrappedFoldable (f :: Type -> Type) a -> f a
instance GHC.Internal.Base.Alternative f => GHC.Internal.Base.Alternative (Witherable.WrappedFoldable f)
instance GHC.Internal.Base.Applicative f => GHC.Internal.Base.Applicative (Witherable.WrappedFoldable f)
instance (Witherable.FilterableWithIndex i f, Witherable.FilterableWithIndex j g) => Witherable.FilterableWithIndex (GHC.Internal.Data.Either.Either i j) (Data.Functor.Product.Product f g)
instance (Witherable.FilterableWithIndex i f, Witherable.FilterableWithIndex j g) => Witherable.FilterableWithIndex (GHC.Internal.Data.Either.Either i j) (Data.Functor.Sum.Sum f g)
instance Witherable.FilterableWithIndex GHC.Types.Int Data.IntMap.Internal.IntMap
instance Witherable.FilterableWithIndex GHC.Types.Int []
instance Witherable.FilterableWithIndex GHC.Types.Int Data.Sequence.Internal.Seq
instance Witherable.FilterableWithIndex GHC.Types.Int Data.Vector.Vector
instance Witherable.FilterableWithIndex GHC.Types.Int GHC.Internal.Functor.ZipList.ZipList
instance (WithIndex.FunctorWithIndex i f, Witherable.FilterableWithIndex j g) => Witherable.FilterableWithIndex (i, j) (Data.Functor.Compose.Compose f g)
instance Witherable.FilterableWithIndex () GHC.Internal.Maybe.Maybe
instance Witherable.FilterableWithIndex GHC.Internal.Base.Void GHC.Internal.Data.Proxy.Proxy
instance Witherable.FilterableWithIndex i t => Witherable.FilterableWithIndex i (Control.Applicative.Backwards.Backwards t)
instance Witherable.FilterableWithIndex i f => Witherable.FilterableWithIndex i (Control.Monad.Trans.Identity.IdentityT f)
instance Witherable.FilterableWithIndex i t => Witherable.FilterableWithIndex i (Data.Functor.Reverse.Reverse t)
instance (WithIndex.FunctorWithIndex i f, WithIndex.FoldableWithIndex i f, GHC.Internal.Base.Alternative f) => Witherable.FilterableWithIndex i (Witherable.WrappedFoldable f)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Witherable.FilterableWithIndex k (Data.HashMap.Internal.HashMap k)
instance Witherable.FilterableWithIndex k (Data.Map.Internal.Map k)
instance (Witherable.Filterable f, Witherable.Filterable g) => Witherable.Filterable (f GHC.Internal.Generics.:*: g)
instance (Witherable.Filterable f, Witherable.Filterable g) => Witherable.Filterable (f GHC.Internal.Generics.:+: g)
instance (GHC.Internal.Base.Functor f, Witherable.Filterable g) => Witherable.Filterable (f GHC.Internal.Generics.:.: g)
instance Witherable.Filterable t => Witherable.Filterable (Control.Applicative.Backwards.Backwards t)
instance (GHC.Internal.Base.Functor f, Witherable.Filterable g) => Witherable.Filterable (Data.Functor.Compose.Compose f g)
instance Witherable.Filterable (GHC.Internal.Data.Functor.Const.Const r)
instance GHC.Internal.Base.Monoid e => Witherable.Filterable (GHC.Internal.Data.Either.Either e)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Witherable.Filterable (Data.HashMap.Internal.HashMap k)
instance Witherable.Filterable f => Witherable.Filterable (Control.Monad.Trans.Identity.IdentityT f)
instance Witherable.Filterable Data.IntMap.Internal.IntMap
instance Witherable.Filterable (GHC.Internal.Generics.K1 i c)
instance Witherable.Filterable []
instance Witherable.Filterable f => Witherable.Filterable (GHC.Internal.Generics.M1 i c f)
instance Witherable.Filterable (Data.Map.Internal.Map k)
instance Witherable.Filterable GHC.Internal.Maybe.Maybe
instance GHC.Internal.Base.Functor f => Witherable.Filterable (Control.Monad.Trans.Maybe.MaybeT f)
instance (Witherable.Filterable f, Witherable.Filterable g) => Witherable.Filterable (Data.Functor.Product.Product f g)
instance Witherable.Filterable GHC.Internal.Data.Proxy.Proxy
instance Witherable.Filterable f => Witherable.Filterable (GHC.Internal.Generics.Rec1 f)
instance Witherable.Filterable t => Witherable.Filterable (Data.Functor.Reverse.Reverse t)
instance Witherable.Filterable Data.Sequence.Internal.Seq
instance (Witherable.Filterable f, Witherable.Filterable g) => Witherable.Filterable (Data.Functor.Sum.Sum f g)
instance Witherable.Filterable GHC.Internal.Generics.U1
instance Witherable.Filterable GHC.Internal.Generics.V1
instance Witherable.Filterable Data.Vector.Vector
instance (GHC.Internal.Data.Foldable.Foldable f, GHC.Internal.Base.Alternative f) => Witherable.Filterable (Witherable.WrappedFoldable f)
instance Witherable.Filterable GHC.Internal.Functor.ZipList.ZipList
instance WithIndex.FoldableWithIndex i f => WithIndex.FoldableWithIndex i (Witherable.WrappedFoldable f)
instance GHC.Internal.Data.Foldable.Foldable f => GHC.Internal.Data.Foldable.Foldable (Witherable.WrappedFoldable f)
instance WithIndex.FunctorWithIndex i f => WithIndex.FunctorWithIndex i (Witherable.WrappedFoldable f)
instance GHC.Internal.Base.Functor Witherable.BoolPair
instance GHC.Internal.Base.Functor f => GHC.Internal.Base.Functor (Witherable.WrappedFoldable f)
instance WithIndex.TraversableWithIndex i f => WithIndex.TraversableWithIndex i (Witherable.WrappedFoldable f)
instance GHC.Internal.Data.Traversable.Traversable f => GHC.Internal.Data.Traversable.Traversable (Witherable.WrappedFoldable f)
instance (Witherable.WitherableWithIndex i f, Witherable.WitherableWithIndex j g) => Witherable.WitherableWithIndex (GHC.Internal.Data.Either.Either i j) (Data.Functor.Product.Product f g)
instance (Witherable.WitherableWithIndex i f, Witherable.WitherableWithIndex j g) => Witherable.WitherableWithIndex (GHC.Internal.Data.Either.Either i j) (Data.Functor.Sum.Sum f g)
instance Witherable.WitherableWithIndex GHC.Types.Int Data.IntMap.Internal.IntMap
instance Witherable.WitherableWithIndex GHC.Types.Int []
instance Witherable.WitherableWithIndex GHC.Types.Int Data.Sequence.Internal.Seq
instance Witherable.WitherableWithIndex GHC.Types.Int Data.Vector.Vector
instance Witherable.WitherableWithIndex GHC.Types.Int GHC.Internal.Functor.ZipList.ZipList
instance (WithIndex.TraversableWithIndex i f, Witherable.WitherableWithIndex j g) => Witherable.WitherableWithIndex (i, j) (Data.Functor.Compose.Compose f g)
instance Witherable.WitherableWithIndex () GHC.Internal.Maybe.Maybe
instance Witherable.WitherableWithIndex GHC.Internal.Base.Void GHC.Internal.Data.Proxy.Proxy
instance Witherable.WitherableWithIndex i t => Witherable.WitherableWithIndex i (Control.Applicative.Backwards.Backwards t)
instance Witherable.WitherableWithIndex i f => Witherable.WitherableWithIndex i (Control.Monad.Trans.Identity.IdentityT f)
instance Witherable.WitherableWithIndex i t => Witherable.WitherableWithIndex i (Data.Functor.Reverse.Reverse t)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Witherable.WitherableWithIndex k (Data.HashMap.Internal.HashMap k)
instance Witherable.WitherableWithIndex k (Data.Map.Internal.Map k)
instance (Witherable.Witherable f, Witherable.Witherable g) => Witherable.Witherable (f GHC.Internal.Generics.:*: g)
instance (Witherable.Witherable f, Witherable.Witherable g) => Witherable.Witherable (f GHC.Internal.Generics.:+: g)
instance (GHC.Internal.Data.Traversable.Traversable f, Witherable.Witherable g) => Witherable.Witherable (f GHC.Internal.Generics.:.: g)
instance Witherable.Witherable t => Witherable.Witherable (Control.Applicative.Backwards.Backwards t)
instance (GHC.Internal.Data.Traversable.Traversable f, Witherable.Witherable g) => Witherable.Witherable (Data.Functor.Compose.Compose f g)
instance Witherable.Witherable (GHC.Internal.Data.Functor.Const.Const r)
instance GHC.Internal.Base.Monoid e => Witherable.Witherable (GHC.Internal.Data.Either.Either e)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Witherable.Witherable (Data.HashMap.Internal.HashMap k)
instance Witherable.Witherable f => Witherable.Witherable (Control.Monad.Trans.Identity.IdentityT f)
instance Witherable.Witherable Data.IntMap.Internal.IntMap
instance Witherable.Witherable (GHC.Internal.Generics.K1 i c)
instance Witherable.Witherable []
instance Witherable.Witherable f => Witherable.Witherable (GHC.Internal.Generics.M1 i c f)
instance Witherable.Witherable (Data.Map.Internal.Map k)
instance Witherable.Witherable GHC.Internal.Maybe.Maybe
instance GHC.Internal.Data.Traversable.Traversable t => Witherable.Witherable (Control.Monad.Trans.Maybe.MaybeT t)
instance (Witherable.Witherable f, Witherable.Witherable g) => Witherable.Witherable (Data.Functor.Product.Product f g)
instance Witherable.Witherable GHC.Internal.Data.Proxy.Proxy
instance Witherable.Witherable f => Witherable.Witherable (GHC.Internal.Generics.Rec1 f)
instance Witherable.Witherable t => Witherable.Witherable (Data.Functor.Reverse.Reverse t)
instance Witherable.Witherable Data.Sequence.Internal.Seq
instance (Witherable.Witherable f, Witherable.Witherable g) => Witherable.Witherable (Data.Functor.Sum.Sum f g)
instance Witherable.Witherable GHC.Internal.Generics.U1
instance Witherable.Witherable GHC.Internal.Generics.V1
instance Witherable.Witherable Data.Vector.Vector
instance (GHC.Internal.Base.Alternative f, GHC.Internal.Data.Traversable.Traversable f) => Witherable.Witherable (Witherable.WrappedFoldable f)
instance Witherable.Witherable GHC.Internal.Functor.ZipList.ZipList
