-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Align and Zip type-classes from the common Semialign ancestor. -- -- The major use of These of this is provided by the -- align member of Semialign class, representing a -- generalized notion of "zipping with padding" that combines structures -- without truncating to the size of the smaller input. -- -- It turns out that zip operation fits well the -- Semialign class, forming lattice-like structure. @package semialign @version 1 -- | Zipping and aligning of functors with non-uniform shapes. module Data.Semialign -- | Functors supporting a zip and align operations that -- takes the intersection and union of non-uniform shapes. -- -- Minimal definition: either align or alignWith and either -- zip or zipWith. -- --

Laws

-- -- The laws of align and zip resemble lattice laws. There -- is a plenty of laws, but they are simply satisfied. -- -- And an addition property if f is Foldable, which tries -- to enforce align-feel: neither values are duplicated nor lost. -- -- Note: join f x = f x x -- -- Idempotency -- --

--   join align ≡ fmap (join These)
--   join zip   ≡ fmap (join (,))
--

-- -- Commutativity -- --

--   align x y ≡ swap <$> align y x
--     zip x y ≡ swap <$> zip y x
--

-- -- Associativity -- --

--   align x (align y z) ≡ assoc <$> align (align x y) z
--       zip x (zip y z) ≡ assoc <$> zip (zip x y) z
--

-- -- Absorption -- --

--   fst    <$> zip xs (align xs ys) ≡ xs
--   toThis <$> align xs (zip xs ys) ≡ This <$> xs
--     where
--       toThis (This a)    = This a
--       toThis (These a _) = This a
--       toThis (That b)    = That b
--

-- -- With -- --

--   alignWith f a b ≡ f <$> align a b
--     zipWith f a b ≡ f <$> zip a b
--

-- -- Functoriality -- --

--   align (f <$> x) (g <$> y) ≡ bimap f g <$> align x y
--     zip (f <$> x) (g <$> y) ≡ bimap f g <$> zip x y
--

-- -- Zippyness -- --

--   fmap fst (zip x x) ≡ x
--   fmap snd (zip x x) ≡ x
--   zip (fmap fst x) (fmap snd x) ≡ x
--

-- -- Alignedness, if f is Foldable -- --

--   toList x ≡ toListOf (folded . here) (align x y)
--            ≡ mapMaybe justHere (toList (align x y))
--

-- -- Distributivity -- --

--                      align (zip xs ys) zs ≡ undistrThesePair <$> zip (align xs zs) (align ys zs)
--   distrPairThese <$> zip (align xs ys) zs ≡                      align (zip xs zs) (zip ys zs)
--                      zip (align xs ys) zs ≡ undistrPairThese <$> align (zip xs zs) (zip ys zs)
--

-- -- Note, the following doesn't hold: -- --

--   distrThesePair <$> align (zip xs ys) zs ≢ zip (align xs zs) (align ys zs)
--

-- -- when xs = [] and ys = zs = [0], then the left hand -- side is "only" [(That 0, That 0)], but the -- right hand side is [(That 0, These 0 0)]. class Functor f => Semialign f -- | Analogous to zip, combines two structures by taking -- the union of their shapes and using These to hold the -- elements. align :: Semialign f => f a -> f b -> f (These a b) -- | Analogous to zipWith, combines two structures by -- taking the union of their shapes and combining the elements with the -- given function. alignWith :: Semialign f => (These a b -> c) -> f a -> f b -> f c -- | Combines to structures by taking the intersection of their shapes and -- using pair to hold the elements. zip :: Semialign f => f a -> f b -> f (a, b) -- | Combines to structures by taking the intersection of their shapes and -- combining the elements with the given function. zipWith :: Semialign f => (a -> b -> c) -> f a -> f b -> f c -- | A unit of align. -- --

Laws

-- --

--   (`align` nil) ≡ fmap This
--   (nil `align`) ≡ fmap That
--

class Semialign f => Align f -- | An empty structure. aligning with nil -- will produce a structure with the same shape and elements as the other -- input, modulo This or That. nil :: Align f => f a -- | Alignable functors supporting an "inverse" to align: splitting -- a union shape into its component parts. -- --

Laws

-- --

--   uncurry align (unalign xs) ≡ xs
--   unalign (align xs ys) ≡ (xs, ys)
--

-- --

Compatibility note

-- -- In version 1 unalign was changed to return (f a, f b) -- pair, instead of (f (Just a), f (Just b)). Old behaviour can -- be achieved with if ever needed. -- --

--   >>> unzipWith (unalign . Just) [This 'a', That 'b', These 'c' 'd']
--   ([Just 'a',Nothing,Just 'c'],[Nothing,Just 'b',Just 'd'])
--

class Semialign f => Unalign f unalign :: Unalign f => f (These a b) -> (f a, f b) unalignWith :: Unalign f => (c -> These a b) -> f c -> (f a, f b) -- | A unit of zip. -- --

--   fst <$> zip xs (full y) ≡ xs
--   snd <$> zip (full x) ys ≡ ys
--

class Semialign f => Zip f -- | A full strucutre. full :: Zip f => a -> f a -- | Right inverse of zip. -- -- This class is definable for every Functor. See -- unzipDefault. -- --

Laws

-- --

--   uncurry zip (unzip xs) ≡ xs
--   unzip (zip xs xs) ≡ (xs, xs)
--

-- -- Note: -- --

--   unzip (zip xs ys) ≢ (xs, _) or (_, ys)
--

-- -- For sequence-like types this holds, but for Map-like it doesn't. class Semialign f => Unzip f unzipWith :: Unzip f => (c -> (a, b)) -> f c -> (f a, f b) unzip :: Unzip f => f (a, b) -> (f a, f b) unzipDefault :: Functor f => f (a, b) -> (f a, f b) -- | Align two structures and combine with mappend. -- -- See salign. malign will be deprecated after -- Semigroup becomes a super class of Monoid malign :: (Semialign f, Monoid a) => f a -> f a -> f a -- | Align two structures and combine with <>. salign :: (Semialign f, Semigroup a) => f a -> f a -> f a -- | Align two structures as in zip, but filling in blanks with -- Nothing. padZip :: Semialign f => f a -> f b -> f (Maybe a, Maybe b) -- | Align two structures as in zipWith, but filling in blanks with -- Nothing. padZipWith :: Semialign f => (Maybe a -> Maybe b -> c) -> f a -> f b -> f c -- | Left-padded zip. lpadZip :: [a] -> [b] -> [(Maybe a, b)] -- | Left-padded zipWith. lpadZipWith :: (Maybe a -> b -> c) -> [a] -> [b] -> [c] -- | Right-padded zip. rpadZip :: [a] -> [b] -> [(a, Maybe b)] -- | Right-padded zipWith. rpadZipWith :: (a -> Maybe b -> c) -> [a] -> [b] -> [c] alignVectorWith :: (Vector v a, Vector v b, Vector v c) => (These a b -> c) -> v a -> v b -> v c -- | These-based aligning and unaligning of functors with -- non-uniform shapes. -- -- For a traversals traversal of (bi)foldable (bi)functors through said -- functors see Data.Crosswalk. module Data.Align -- | Functors supporting a zip and align operations that -- takes the intersection and union of non-uniform shapes. -- -- Minimal definition: either align or alignWith and either -- zip or zipWith. -- --

Laws

--   join align ≡ fmap (join These)
--   join zip   ≡ fmap (join (,))
--

-- -- Commutativity -- --

--   align x y ≡ swap <$> align y x
--     zip x y ≡ swap <$> zip y x
--

-- -- Associativity -- --

--   align x (align y z) ≡ assoc <$> align (align x y) z
--       zip x (zip y z) ≡ assoc <$> zip (zip x y) z
--

-- -- Absorption -- --

--   fst    <$> zip xs (align xs ys) ≡ xs
--   toThis <$> align xs (zip xs ys) ≡ This <$> xs
--     where
--       toThis (This a)    = This a
--       toThis (These a _) = This a
--       toThis (That b)    = That b
--

-- -- With -- --

--   alignWith f a b ≡ f <$> align a b
--     zipWith f a b ≡ f <$> zip a b
--

-- -- Functoriality -- --

--   align (f <$> x) (g <$> y) ≡ bimap f g <$> align x y
--     zip (f <$> x) (g <$> y) ≡ bimap f g <$> zip x y
--

-- -- Zippyness -- --

--   fmap fst (zip x x) ≡ x
--   fmap snd (zip x x) ≡ x
--   zip (fmap fst x) (fmap snd x) ≡ x
--

-- -- Alignedness, if f is Foldable -- --

--   toList x ≡ toListOf (folded . here) (align x y)
--            ≡ mapMaybe justHere (toList (align x y))
--

-- -- Distributivity -- --

--                      align (zip xs ys) zs ≡ undistrThesePair <$> zip (align xs zs) (align ys zs)
--   distrPairThese <$> zip (align xs ys) zs ≡                      align (zip xs zs) (zip ys zs)
--                      zip (align xs ys) zs ≡ undistrPairThese <$> align (zip xs zs) (zip ys zs)
--

-- -- Note, the following doesn't hold: -- --

--   distrThesePair <$> align (zip xs ys) zs ≢ zip (align xs zs) (align ys zs)
--

Laws

-- --

--   (`align` nil) ≡ fmap This
--   (nil `align`) ≡ fmap That
--

Laws

-- --

--   uncurry align (unalign xs) ≡ xs
--   unalign (align xs ys) ≡ (xs, ys)
--

-- --

Compatibility note

-- -- In version 1 unalign was changed to return (f a, f b) -- pair, instead of (f (Just a), f (Just b)). Old behaviour can -- be achieved with if ever needed. -- --

--   >>> unzipWith (unalign . Just) [This 'a', That 'b', These 'c' 'd']
--   ([Just 'a',Nothing,Just 'c'],[Nothing,Just 'b',Just 'd'])
--

class Semialign f => Unalign f unalign :: Unalign f => f (These a b) -> (f a, f b) unalignWith :: Unalign f => (c -> These a b) -> f c -> (f a, f b) -- | Align two structures and combine with mappend. -- -- See salign. malign will be deprecated after -- Semigroup becomes a super class of Monoid malign :: (Semialign f, Monoid a) => f a -> f a -> f a -- | Align two structures and combine with <>. salign :: (Semialign f, Semigroup a) => f a -> f a -> f a -- | Align two structures as in zip, but filling in blanks with -- Nothing. padZip :: Semialign f => f a -> f b -> f (Maybe a, Maybe b) -- | Align two structures as in zipWith, but filling in blanks with -- Nothing. padZipWith :: Semialign f => (Maybe a -> Maybe b -> c) -> f a -> f b -> f c -- | Left-padded zip. lpadZip :: [a] -> [b] -> [(Maybe a, b)] -- | Left-padded zipWith. lpadZipWith :: (Maybe a -> b -> c) -> [a] -> [b] -> [c] -- | Right-padded zip. rpadZip :: [a] -> [b] -> [(a, Maybe b)] -- | Right-padded zipWith. rpadZipWith :: (a -> Maybe b -> c) -> [a] -> [b] -> [c] alignVectorWith :: (Vector v a, Vector v b, Vector v c) => (These a b -> c) -> v a -> v b -> v c module Data.Crosswalk -- | Foldable functors supporting traversal through an alignable functor. -- -- Minimal definition: crosswalk or sequenceL. -- -- Laws: -- --

--   crosswalk (const nil) = const nil
--   crosswalk f = sequenceL . fmap f
--

class (Functor t, Foldable t) => Crosswalk t crosswalk :: (Crosswalk t, Align f) => (a -> f b) -> t a -> f (t b) sequenceL :: (Crosswalk t, Align f) => t (f a) -> f (t a) -- | Bifoldable bifunctors supporting traversal through an alignable -- functor. -- -- Minimal definition: bicrosswalk or bisequenceL. -- -- Laws: -- --

--   bicrosswalk (const empty) (const empty) = const empty
--   bicrosswalk f g = bisequenceL . bimap f g
--

class (Bifunctor t, Bifoldable t) => Bicrosswalk t bicrosswalk :: (Bicrosswalk t, Align f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d) bisequenceL :: (Bicrosswalk t, Align f) => t (f a) (f b) -> f (t a b) instance Data.Crosswalk.Bicrosswalk Data.Either.Either instance Data.Crosswalk.Bicrosswalk Data.These.These instance Data.Crosswalk.Crosswalk Data.Functor.Identity.Identity instance Data.Crosswalk.Crosswalk GHC.Maybe.Maybe instance Data.Crosswalk.Crosswalk [] instance Data.Crosswalk.Crosswalk Data.Sequence.Internal.Seq instance Data.Crosswalk.Crosswalk (Data.These.These a) instance Data.Crosswalk.Crosswalk Data.Vector.Vector instance Data.Crosswalk.Crosswalk ((,) a) instance (Data.Crosswalk.Crosswalk f, Data.Crosswalk.Crosswalk g) => Data.Crosswalk.Crosswalk (Data.Functor.Compose.Compose f g) -- | Zipping and unzipping of functors with non-uniform shapes. module Data.Zip -- | Functors supporting a zip and align operations that -- takes the intersection and union of non-uniform shapes. -- -- Minimal definition: either align or alignWith and either -- zip or zipWith. -- --

Laws

--   join align ≡ fmap (join These)
--   join zip   ≡ fmap (join (,))
--

-- -- Commutativity -- --

--   align x y ≡ swap <$> align y x
--     zip x y ≡ swap <$> zip y x
--

-- -- Associativity -- --

--   align x (align y z) ≡ assoc <$> align (align x y) z
--       zip x (zip y z) ≡ assoc <$> zip (zip x y) z
--

-- -- Absorption -- --

--   fst    <$> zip xs (align xs ys) ≡ xs
--   toThis <$> align xs (zip xs ys) ≡ This <$> xs
--     where
--       toThis (This a)    = This a
--       toThis (These a _) = This a
--       toThis (That b)    = That b
--

-- -- With -- --

--   alignWith f a b ≡ f <$> align a b
--     zipWith f a b ≡ f <$> zip a b
--

-- -- Functoriality -- --

--   align (f <$> x) (g <$> y) ≡ bimap f g <$> align x y
--     zip (f <$> x) (g <$> y) ≡ bimap f g <$> zip x y
--

-- -- Zippyness -- --

--   fmap fst (zip x x) ≡ x
--   fmap snd (zip x x) ≡ x
--   zip (fmap fst x) (fmap snd x) ≡ x
--

-- -- Alignedness, if f is Foldable -- --

--   toList x ≡ toListOf (folded . here) (align x y)
--            ≡ mapMaybe justHere (toList (align x y))
--

-- -- Distributivity -- --

--                      align (zip xs ys) zs ≡ undistrThesePair <$> zip (align xs zs) (align ys zs)
--   distrPairThese <$> zip (align xs ys) zs ≡                      align (zip xs zs) (zip ys zs)
--                      zip (align xs ys) zs ≡ undistrPairThese <$> align (zip xs zs) (zip ys zs)
--

-- -- Note, the following doesn't hold: -- --

--   distrThesePair <$> align (zip xs ys) zs ≢ zip (align xs zs) (align ys zs)
--

--   fst <$> zip xs (full y) ≡ xs
--   snd <$> zip (full x) ys ≡ ys
--

class Semialign f => Zip f -- | A full strucutre. full :: Zip f => a -> f a -- | Right inverse of zip. -- -- This class is definable for every Functor. See -- unzipDefault. -- --

Laws

-- --

--   uncurry zip (unzip xs) ≡ xs
--   unzip (zip xs xs) ≡ (xs, xs)
--

-- -- Note: -- --

--   unzip (zip xs ys) ≢ (xs, _) or (_, ys)
--

-- -- For sequence-like types this holds, but for Map-like it doesn't. class Semialign f => Unzip f unzipWith :: Unzip f => (c -> (a, b)) -> f c -> (f a, f b) unzip :: Unzip f => f (a, b) -> (f a, f b) unzipDefault :: Functor f => f (a, b) -> (f a, f b) newtype Zippy f a Zippy :: f a -> Zippy f a [getZippy] :: Zippy f a -> f a instance GHC.Base.Functor f => GHC.Base.Functor (Data.Zip.Zippy f) instance GHC.Read.Read (f a) => GHC.Read.Read (Data.Zip.Zippy f a) instance GHC.Show.Show (f a) => GHC.Show.Show (Data.Zip.Zippy f a) instance GHC.Classes.Ord (f a) => GHC.Classes.Ord (Data.Zip.Zippy f a) instance GHC.Classes.Eq (f a) => GHC.Classes.Eq (Data.Zip.Zippy f a) instance (Data.Semialign.Internal.Semialign f, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Data.Zip.Zippy f a) instance (Data.Semialign.Internal.Zip f, GHC.Base.Monoid a) => GHC.Base.Monoid (Data.Zip.Zippy f a) instance Data.Semialign.Internal.Semialign f => Data.Functor.Bind.Class.Apply (Data.Zip.Zippy f) instance Data.Semialign.Internal.Zip f => GHC.Base.Applicative (Data.Zip.Zippy f)