Data.Semialign

Functors supporting an align operation that takes the union of non-uniform shapes.

Minimal definition: either align or alignWith.

Laws

The laws of align and zip resemble lattice laws. There is a plenty of laws, but they are simply satisfied.

And an additional 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)

Commutativity

align x y ≡ swap <$> align y x

Associativity

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

With

alignWith f a b ≡ f <$> align a b

Functoriality

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

Alignedness, if f is Foldable

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

A unit of align.

Laws

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

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

Functors supporting a zip operation that takes the intersection of non-uniform shapes.

Minimal definition: either zip or zipWith.

Idempotency

join zip   ≡ fmap (join (,))

Commutativity

zip x y ≡ swap <$> zip y x

Associativity

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

zipWith f a b ≡ f <$> zip a b

Functoriality

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

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

Zippable functors supporting left and right units

Unit

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

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.

Align two structures and combine with <>.

Align two structures as in zip, but filling in blanks with Nothing.

Align two structures as in zipWith, but filling in blanks with Nothing.

Left-padded zip.

Left-padded zipWith.

Right-padded zip.

Right-padded zipWith.