A PartialSemigroup is like a Semigroup, but with an operator returning Maybe a rather than a.

For comparison:

(<>)  :: Semigroup a        => a -> a -> a
(<>?) :: PartialSemigroup a => a -> a -> Maybe a

The associativity axiom for partial semigroups

For all x, y, z:

• If x <>? y = Just xy and y <>? z = Just yz, then

  • x <>? yz = xy <>? z.

Relationship to the semigroup associativity axiom

The partial semigroup associativity axiom is a natural adaptation of the semigroup associativity axiom

x <> (y <> z) = (x <> y) <> z

with a slight modification to accommodate situations where <> is undefined. We may gain some insight into the connection between Semigroup and PartialSemigroup by rephrasing the partial semigroup associativity in terms of a partial <> operator thusly:

For all x, y, z:

• If x <> y and y <> z are both defined, then

  • x <> (y <> z) is defined if and only if (x <> y) <> z is defined, and
  • if these things are all defined, then the axiom for total semigroups x <> (y <> z) = (x <> y) <> z must hold.

A wrapper for Either where the PartialSemigroup operator is defined only over Left values.

Examples

Two Lefts make a Just.

>>> AppendLeft (Left "ab") <>? AppendLeft (Left "cd")
Just (AppendLeft {unAppendLeft = Left "abcd"})

Anything else produces Nothing

>>> AppendLeft (Right "ab") <>? AppendLeft (Right "cd")
Nothing

groupAndConcat combines consecutive Left values, leaving the Right values unmodified.

>>> xs = [Left "a", Left "b", Right "c", Right "d", Left "e", Left "f"]
>>> fmap unAppendLeft . groupAndConcat . fmap AppendLeft $ xs
[Left "ab",Right "c",Right "d",Left "ef"]

A wrapper for Either where the PartialSemigroup operator is defined only over Right values.

Examples

Two Rights make a Just.

>>> AppendRight (Right "ab") <>? AppendRight (Right "cd")
Just (AppendRight {unAppendRight = Right "abcd"})

Anything else produces Nothing

>>> AppendRight (Left "ab") <>? AppendRight (Left "cd")
Nothing

groupAndConcat combines consecutive Right values, leaving the Left values unmodified.

>>> xs = [Left "a", Left "b", Right "c", Right "d", Left "e", Left "f"]
>>> fmap unAppendRight . groupAndConcat . fmap AppendRight $ xs
[Left "a",Left "b",Right "cd",Left "e",Left "f"]

Apply a semigroup operation to any pairs of consecutive list elements where the semigroup operation is defined over them.

Examples

For Either, groupAndConcat combines contiguous sublists of Left and contiguous sublists of Right.

>>> xs = [Left "a", Right "b", Right "c", Left "d", Left "e", Left "f"]
>>> groupAndConcat xs
[Left "a",Right "bc",Left "def"]

If xs is nonempty and the partial semigroup operator is defined for all pairs of values in xs, then partialConcat xs produces a Just result with the combination of all the values. Otherwise, returns Nothing.

Examples

When all values can combine, we get a Just of their combination.

>>> partialConcat [Left "a", Left "b", Left "c"]
Just (Left "abc")

When some values cannot be combined, we get Nothing.

>>> partialConcat [Left "a", Left "b", Right "c"]
Nothing

When the list is empty, we get Nothing.

>>> partialConcat []
Nothing

Like partialConcat, but for non-empty lists.

Examples

When all values can combine, we get a Just of their combination.

>>> partialConcat1 (Left "a" :| [Left "b", Left "c"])
Just (Left "abc")

When some values cannot be combined, we get Nothing.

>>> partialConcat1 (Left "a" :| [Left "b", Right "c"])
Nothing

Examples

If lists are the same length and each pair of elements successfully, then we get a Just result.

>>> xs = [Left "a", Left "b", Right "c"]
>>> ys = [Left "1", Left "2", Right "3"]
>>> partialZip xs ys
Just [Left "a1",Left "b2",Right "c3"]

If the pairs do not all combine, then we get Nothing.

>>> xs = [Left "a", Left "b", Right "c"]
>>> ys = [Left "1", Right "2", Right "3"]
>>> partialZip xs ys
Nothing

If the lists have different lengths, then we get Nothing.

>>> xs = [Left "a", Left "b", Right "c"]
>>> ys = [Left "1", Left "2"]
>>> partialZip xs ys
Nothing

Like partialZip, but for non-empty lists.

Examples

If lists are the same length and each pair of elements successfully, then we get a Just result.

>>> xs = Left "a" :| [Left "b", Right "c"]
>>> ys = Left "1" :| [Left "2", Right "3"]
>>> partialZip1 xs ys
Just (Left "a1" :| [Left "b2",Right "c3"])

If the pairs do not all combine, then we get Nothing.

>>> xs = Left "a" :| [Left "b", Right "c"]
>>> ys = Left "1" :| [Right "2", Right "3"]
>>> partialZip1 xs ys
Nothing

If the lists have different lengths, then we get Nothing.

>>> xs = Left "a" :| [Left "b", Right "c"]
>>> ys = Left "1" :| [Left "2"]
>>> partialZip1 xs ys
Nothing

A wrapper to turn any value with a Semigroup instance into a value with a PartialSemigroup instance whose <>? operator always returns Just.

Examples

>>> Total "ab" <>? Total "cd"
Just (Total {unTotal = "abcd"})

>>> f = getProduct . unTotal
>>> g = Total . Product
>>> fmap f . partialConcat . fmap g $ [1..4]
Just 24

A wrapper for Maybe with an error-propagating Semigroup.

A partial semigroup operation which always fails.

A wrapper for Maybe whose partial semigroup operation fails when two Justs are combined.