-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Function combinator "between" and derived combinators
--
-- It turns out that this combinator
--
--
-- f ~@~ g = (f .) . (. g)
--
--
-- is a powerful thing. It was abstracted from following (commonly used)
-- pattern f . h . g where f and g are fixed.
--
-- This library not only define ~@~ combinator, but also some
-- derived combinators that can help us to easily define a lot of things
-- including lenses. See lens package for detais on what lenses
-- are.
--
-- Function Data.Function.on can be implemented using
-- ~@~ as:
--
--
-- on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
-- on f g = (id ~@~ g ~@~ g) f
--
--
-- If function on3 existed in base then it could be
-- defined as:
--
--
-- on3 :: (b -> b -> b -> d) -> (a -> b) -> a -> a -> a -> d
-- on3 f g = (id ~@~ g ~@~ g ~@~ g) f
--
--
-- Other usage examples and documentation can be found in
-- Data.Function.Between.
@package between
@version 0.9.0.2
-- | During development it is common occurrence to modify deeply nested
-- structures. One of the best known libraries for this purpose is
-- lens, but it's quite overkill for some purposes.
--
-- This module describes simple and composable combinators that are built
-- on top of very basic concept:
--
--
-- f . h . g
--
--
-- Where f and g are fixed. It is possible to reduce it
-- to just:
--
--
-- (f .) . (. g)
--
--
-- Which is the core pattern used by all functions defined in this
-- module.
--
-- Trying to generalize this pattern further ends as: (f
-- <$>) . (<$> g), where
-- <$> = fmap. Other combinations of
-- substituting . for fmap will end up less or equally
-- generic. Type of such expression is:
--
--
-- \f g -> (f <$>) . (<$> g)
-- :: Functor f => (b -> c) -> f a -> (a -> b) -> f c
--
--
-- Which doesn't give us much more power. Instead of going for such
-- generalization we kept the original ((f .) .
-- (. g)) which we named between or ~@~ in its
-- infix form.
module Data.Function.Between
-- | Core combinator of this module and we build others on top of. It also
-- has an infix form ~@~ and flipped infix form ~@@~.
--
-- This function Defined as:
--
--
-- between f g -> (f .) . (. g)
--
between :: (c -> d) -> (a -> b) -> (b -> c) -> a -> d
-- | Infix variant of between.
--
-- Fixity is left associative and set to value 8, which is one less then
-- fixity of function composition (.).
(~@~) :: (c -> d) -> (a -> b) -> (b -> c) -> a -> d
-- | Flipped variant of ~@~, i.e. flipped infix variant of
-- between.
--
-- Fixity is right associative and set to value 8, which is one less then
-- fixity of function composition (.).
(~@@~) :: (a -> b) -> (c -> d) -> (b -> c) -> a -> d
-- | As ~@~, but first function is also parametrised with
-- a, hence the name ^@~. Character ^ indicates
-- which argument is parametrised with additional argument.
--
-- This function is defined as:
--
--
-- (f ^@~ g) h a -> (f a ~@~ g) h a
--
--
-- Fixity is left associative and set to value 8, which is one less then
-- fixity of function composition (.).
(^@~) :: (a -> c -> d) -> (a -> b) -> (b -> c) -> a -> d
-- | Flipped variant of ^@~.
--
-- Fixity is right associative and set to value 8, which is one less then
-- fixity of function composition (.).
(~@@^) :: (a -> b) -> (a -> c -> d) -> (b -> c) -> a -> d
-- | Pass additional argument to first two function arguments.
--
-- This function is defined as:
--
--
-- (f ^@^ g) h a b -> (f a ~@~ g a) h b
--
--
-- See also ^@~ to note the difference, most importantly that
-- ^@~ passes the same argument to all its functional arguments.
-- Function ^@~ can be defined in terms of this one as:
--
--
-- (f ^@~ g) h a = (f ^@^ const g) h a a
--
--
-- We can do it also the other way around and define ^@^ using
-- ^@~:
--
--
-- f ^@^ g =
-- curry . (f . snd ^@~ uncurry g)
--
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(^@^) :: (a -> d -> e) -> (a -> b -> c) -> (c -> d) -> a -> b -> e
-- | Flipped variant of ^@^.
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(^@@^) :: (a -> b -> c) -> (a -> d -> e) -> (c -> d) -> a -> b -> e
-- | Apply function g to each argument of binary function and
-- f to its result. In suffix "2l" the number is equal to arity
-- of the function it accepts as a third argument and character "l" is
-- for "left associative".
--
--
-- between2l f g = (f ~@~ g) ~@~ g
--
--
-- Interesting observation:
--
--
-- (\f g -> between2l id g f) === on
--
between2l :: (c -> d) -> (a -> b) -> (b -> b -> c) -> a -> a -> d
-- | Apply function g to each argument of ternary function and
-- f to its result. In suffix "3l" the number is equal to arity
-- of the function it accepts as a third argument and character "l" is
-- for "left associative".
--
-- This function is defined as:
--
--
-- between3l f g = ((f ~@~ g) ~@~ g) ~@~ g
--
--
-- Alternatively it can be defined using between2l:
--
--
-- between3l f g = between2l f g ~@~ g
--
between3l :: (c -> d) -> (a -> b) -> (b -> b -> b -> c) -> a -> a -> a -> d
-- | Convenience wrapper for:
--
--
-- \f g -> fmap f ~@~ fmap g
--
--
-- Name of <~@~> simply says that we apply <$>
-- (fmap) to both its arguments and then we apply ~@~.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(<~@~>) :: (Functor f, Functor g) => (c -> d) -> (a -> b) -> (f b -> g c) -> f a -> g d
-- | Flipped variant of <~@~>.
--
-- Name of <~@@~> simply says that we apply <$>
-- (fmap) to both its arguments and then we apply ~@@~.
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(<~@@~>) :: (Functor f, Functor g) => (a -> b) -> (c -> d) -> (f b -> g c) -> f a -> g d
-- | Apply fmap to first argument of ~@~. Dual to ~@~>
-- which applies fmap to second argument.
--
-- Defined as:
--
--
-- f <~@~ g = fmap f ~@~ g
--
--
-- This function allows us to define lenses mostly for pair of functions
-- that form an isomorphism. See section Constructing Lenses for
-- details.
--
-- Name of <~@~ simply says that we apply <$>
-- (fmap) to first (left) argument and then we apply ~@~.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(<~@~) :: Functor f => (c -> d) -> (a -> b) -> (b -> f c) -> a -> f d
-- | Flipped variant of <~@~.
--
-- This function allows us to define lenses mostly for pair of functions
-- that form an isomorphism. See section Constructing Lenses for
-- details.
--
-- Name of ~@@~> simply says that we apply <$>
-- (fmap) to second (right) argument and then we apply
-- ~@@~.
--
-- Fixity is right associative and set to value 8, which is one less then
-- fixity of function composition (.).
(~@@~>) :: Functor f => (a -> b) -> (c -> d) -> (b -> f c) -> a -> f d
-- | Apply fmap to second argument of ~@~. Dual to <~@~
-- which applies fmap to first argument.
--
-- Defined as:
--
--
-- f ~@~> g -> f ~@~ fmap g
--
--
-- Name of ~@~> simply says that we apply <$>
-- (fmap) to second (right) argument and then we apply ~@~.
--
-- Fixity is right associative and set to value 8, which is one less then
-- of function composition (.).
(~@~>) :: Functor f => (c -> d) -> (a -> b) -> (f b -> c) -> f a -> d
-- | Flipped variant of ~@~>.
--
-- Name of <~@@~ simply says that we apply <$>
-- (fmap) to first (left) argument and then we apply ~@@~.
--
-- Fixity is left associative and set to value 8, which is one less then
-- fixity of function composition (.).
(<~@@~) :: Functor f => (a -> b) -> (c -> d) -> (f b -> c) -> f a -> d
-- | Convenience wrapper for: \f g -> fmap . f ^@~
-- g.
--
-- This function has the same functionality as function
--
--
-- lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
--
--
-- Which is defined in lens package. Only difference is that
-- arguments of <^@~ are flipped. See also section
-- Constructing Lenses.
--
-- Name of <^@~ simply says that we apply <$>
-- (fmap) to first (left) arguments and then we apply ^@~.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(<^@~) :: Functor f => (a -> c -> d) -> (a -> b) -> (b -> f c) -> a -> f d
-- | Flipped variant of ~@^>.
--
-- This function has the same functionality as function
--
--
-- lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
--
--
-- Which is defined in lens package. See also section
-- Constructing Lenses.
--
-- Name of ~@^> simply says that we apply <$>
-- (fmap) to second (right) arguments and then we apply
-- ~@^>.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(~@@^>) :: Functor f => (a -> b) -> (a -> c -> d) -> (b -> f c) -> a -> f d
-- | Convenience wrapper for: \f g -> fmap . f ^@^
-- fmap . g.
--
-- Name of <^@^> simply says that we apply <$>
-- (fmap) to both its arguments and then we apply ^@^.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(<^@^>) :: (Functor f, Functor g) => (a -> d -> e) -> (a -> b -> c) -> (f c -> g d) -> a -> f b -> g e
-- | Flipped variant of <^@^>.
--
-- Name of <^@@^> simply says that we apply <$>
-- (fmap) to both its arguments and then we apply ^@@^.
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(<^@@^>) :: (Functor f, Functor g) => (a -> b -> c) -> (a -> d -> e) -> (f c -> g d) -> a -> f b -> g e
-- | Convenience wrapper for: \f g -> fmap . f ^@^
-- g.
--
-- This function allows us to define generic lenses from gettern and
-- setter. See section Constructing Lenses for details.
--
-- Name of <^@^ simply says that we apply <$>
-- (fmap) to first (left) arguments and then we apply ^@^.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(<^@^) :: Functor f => (a -> d -> e) -> (a -> b -> c) -> (c -> f d) -> a -> b -> f e
-- | Flipped variant of <^@^.
--
-- This function allows us to define generic lenses from gettern and
-- setter. See section Constructing Lenses for details.
--
-- Name of ^@@^> simply says that we apply <$>
-- (fmap) to second (right) arguments and then we apply
-- ^@@^.
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(^@@^>) :: Functor f => (a -> b -> c) -> (a -> d -> e) -> (c -> f d) -> a -> b -> f e
-- | Convenience wrapper for: \f g -> f ^@^ fmap .
-- g.
--
-- Name of ^@^> simply says that we apply <$>
-- (fmap) to second (right) arguments and then we apply
-- ^@^.
--
-- Fixity is left associative and set to value 8, which is one less then
-- of function composition (.).
(^@^>) :: Functor f => (a -> d -> e) -> (a -> b -> c) -> (f c -> d) -> a -> f b -> e
-- | Flipped variant of <^@^>.
--
-- Name of <^@@^> simply says that we apply <$>
-- (fmap) to first (left) arguments and then we apply ^@@^.
--
-- Fixity is set to value 8, which is one less then of function
-- composition (.).
(<^@@^) :: Functor f => (a -> b -> c) -> (a -> d -> e) -> (f c -> d) -> a -> f b -> e