Relude.Monoid

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

Right identity

x <> mempty = x

Left identity

mempty <> x = x

Associativity

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

(

Semigroup

law)

Concatenation

mconcat = foldr (<>) mempty

You can alternatively define mconcat instead of mempty, in which case the laws are:

Unit

mconcat (pure x) = x

Multiplication

mconcat (join xss) = mconcat (fmap mconcat xss)

Subclass

mconcat (toList xs) = sconcat xs

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Data.Semigroup.Sum and Data.Semigroup.Product.

NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

Monoid under <|>.

Alt l <> Alt r == Alt (l <|> r)

Examples

>>> Alt (Just 12) <> Alt (Just 24)Alt {getAlt = Just 12}

>>> Alt Nothing <> Alt (Just 24)Alt {getAlt = Just 24}

This data type witnesses the lifting of a Monoid into an Applicative pointwise.

Examples

>>> Ap (Just [1, 2, 3]) <> Ap NothingAp {getAp = Nothing}

>>> Ap [Sum 10, Sum 20] <> Ap [Sum 1, Sum 2]Ap {getAp = [Sum {getSum = 11},Sum {getSum = 12},Sum {getSum = 21},Sum {getSum = 22}]}

Boolean monoid under conjunction (&&).

All x <> All y = All (x && y)

Examples

>>> All True <> mempty <> All False)All {getAll = False}

>>> mconcat (map (\x -> All (even x)) [2,4,6,7,8])All {getAll = False}

>>> All True <> memptyAll {getAll = True}

Boolean monoid under disjunction (||).

Any x <> Any y = Any (x || y)

Examples

>>> Any True <> mempty <> Any FalseAny {getAny = True}

>>> mconcat (map (\x -> Any (even x)) [2,4,6,7,8])Any {getAny = True}

>>> Any False <> memptyAny {getAny = False}

The dual of a Monoid, obtained by swapping the arguments of (<>).

Dual a <> Dual b == Dual (b <> a)

Examples

>>> Dual "Hello" <> Dual "World"Dual {getDual = "WorldHello"}

>>> Dual (Dual "Hello") <> Dual (Dual "World")Dual {getDual = Dual {getDual = "HelloWorld"}}

The monoid of endomorphisms under composition.

Endo f <> Endo g == Endo (f . g)

Examples

>>> let computation = Endo ("Hello, " ++) <> Endo (++ "!")>>> appEndo computation "Haskell""Hello, Haskell!"

>>> let computation = Endo (*3) <> Endo (+1)>>> appEndo computation 16

Maybe monoid returning the leftmost non-Nothing value.

First a is isomorphic to Alt Maybe a, but precedes it historically.

Beware that Data.Monoid.First is different from Data.Semigroup.First. The former returns the first non-Nothing, so Data.Monoid.First Nothing <> x = x. The latter simply returns the first value, thus Data.Semigroup.First Nothing <> x = Data.Semigroup.First Nothing.

Examples

>>> First (Just "hello") <> First Nothing <> First (Just "world")First {getFirst = Just "hello"}

>>> First Nothing <> memptyFirst {getFirst = Nothing}

Maybe monoid returning the rightmost non-Nothing value.

Last a is isomorphic to Dual (First a), and thus to Dual (Alt Maybe a)

Data.Semigroup.Last. The former returns the last non-Nothing, so x <> Data.Monoid.Last Nothing = x. The latter simply returns the last value, thus x <> Data.Semigroup.Last Nothing = Data.Semigroup.Last Nothing.

Examples

>>> Last (Just "hello") <> Last Nothing <> Last (Just "world")Last {getLast = Just "world"}

>>> Last Nothing <> memptyLast {getLast = Nothing}

Monoid under multiplication.

Product x <> Product y == Product (x * y)

Examples

>>> Product 3 <> Product 4 <> memptyProduct {getProduct = 12}

>>> mconcat [ Product n | n <- [2 .. 10]]Product {getProduct = 3628800}

Monoid under addition.

Sum a <> Sum b = Sum (a + b)

Examples

>>> Sum 1 <> Sum 2 <> memptySum {getSum = 3}

>>> mconcat [ Sum n | n <- [3 .. 9]]Sum {getSum = 42}

The class of semigroups (types with an associative binary operation).

Instances should satisfy the following:

Associativity

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

You can alternatively define sconcat instead of (<>), in which case the laws are:

Unit

sconcat (pure x) = x

Multiplication

sconcat (join xss) = sconcat (fmap sconcat xss)

Provide a Semigroup for an arbitrary Monoid.

NOTE: This is not needed anymore since Semigroup became a superclass of Monoid in base-4.11 and this newtype be deprecated at some point in the future.

A generalization of cycle to an arbitrary Semigroup. May fail to terminate for some values in some semigroups.

Examples

>>> take 10 $ cycle1 [1, 2, 3][1,2,3,1,2,3,1,2,3,1]

>>> cycle1 (Right 1)Right 1

>>> cycle1 (Left 1)* hangs forever *

Repeat a value n times.

mtimesDefault n a = a <> a <> ... <> a  -- using <> (n-1) times

In many cases, stimes 0 a for a Monoid will produce mempty. However, there are situations when it cannot do so. In particular, the following situation is fairly common:

data T a = ...

class Constraint1 a
class Constraint1 a => Constraint2 a

instance Constraint1 a => Semigroup (T a)
instance Constraint2 a => Monoid (T a)

Since Constraint1 is insufficient to implement mempty, stimes for T a cannot do so.

When working with such a type, or when working polymorphically with Semigroup instances, mtimesDefault should be used when the multiplier might be zero. It is implemented using stimes when the multiplier is nonzero and mempty when it is zero.

Examples

>>> mtimesDefault 0 "bark"[]

>>> mtimesDefault 3 "meow""meowmeowmeow"

This is a valid definition of stimes for an idempotent Semigroup.

When x <> x = x, this definition should be preferred, because it works in \mathcal{O}(1) rather than \mathcal{O}(\log n).

This is a valid definition of stimes for an idempotent Monoid.

When x <> x = x, this definition should be preferred, because it works in \mathcal{O}(1) rather than \mathcal{O}(\log n)

This is a valid definition of stimes for a Monoid.

Unlike the default definition of stimes, it is defined for 0 and so it should be preferred where possible.

This data type witnesses the lifting of a Monoid into an Applicative pointwise.

Examples

>>> Ap (Just [1, 2, 3]) <> Ap NothingAp {getAp = Nothing}

>>> Ap [Sum 10, Sum 20] <> Ap [Sum 1, Sum 2]Ap {getAp = [Sum {getSum = 11},Sum {getSum = 12},Sum {getSum = 21},Sum {getSum = 22}]}

Extracts Monoid value from Maybe returning mempty if Relude.Nothing.

>>> maybeToMonoid (Just [1,2,3] :: Maybe [Int])[1,2,3]>>> maybeToMonoid (Nothing :: Maybe [Int])[]

Returns the given value in case of the given predicate is satisfied (is True). Otherwise, it returns mempty.

>>> memptyIfFalse True (Just "Hello")Just "Hello">>> memptyIfFalse False "Doesn't matter"""

Returns the given value in case of the given predicate is unsatisfied (is False). Otherwise, it returns mempty.

>>> memptyIfTrue True (Just "Hello")Nothing>>> memptyIfTrue False "Does matter""Does matter"