io.atlassian.fugue

Interface Monoid<A>

All Superinterfaces:

Semigroup<A>

public interface Monoid<A>
extends Semigroup<A>

A Monoid is an algebraic structure consisting of an associative binary operation across the values of a given type (a monoid is a Semigroup) and an identity element for this operation. Implementations must follow the monoidal laws:

• Left Identity; forall x. append(zero(), x) == x
• Right Identity; forall x. append(x, zero()) == x
• Associativity; forall x y z. append(append(x, y), z) == append(x, append(y, z))

Methods sum(Iterable) and multiply(int, Object) can be overriden for performance reason, especially if sum(Iterable) can be implemented to not require evaluation of the whole iterable. All other default methods should not be overriden.

Since:

3.1

See Also:

Semigroup

Method Summary

Modifier and Type	Method and Description
static <A,B> Monoid<Pair<A,B>>	compose(Monoid<A> ma, Monoid<B> mb) Composes a monoid with another.
static <A> Monoid<A>	dual(Monoid<A> monoid) Return the dual Monoid.
default A	intersperse(Iterable<? extends A> as, A a) Intersperses the given value between each two elements of the collection, and sums the result.
default A	multiply(int n, A a) Returns a value summed n times (a + a + ...
default A	multiply1p(int n, A a) Returns a value summed n + 1 times ( a + a + ...
default A	sum(Iterable<A> as) Sums the given values.
default A	sumNonEmpty(A head, Iterable<A> tail) Reduce a 'non-empty' Iterable with Semigroup.append(Object, Object)
A	zero() The identity element value for this monoid.

Methods inherited from interface io.atlassian.fugue.Semigroup

append, compose, dual

Method Detail

zero

A zero()

The identity element value for this monoid.

Returns:

The identity element for this monoid.

sum

default A sum(Iterable<A> as)

Sums the given values.

Parameters:

as - The values to sum.

Returns:

The sum of the given values.

multiply

default A multiply(int n,
                   A a)

Returns a value summed n times (a + a + ... + a). The default definition uses peasant multiplication, exploiting associativity to only require `O(log n)` uses of Semigroup.append(Object, Object).

Parameters:

n - multiplier

a - the value to be reapeatly summed

Returns:

a summed n times. If n <= 0, returns zero()

intersperse

default A intersperse(Iterable<? extends A> as,
                      A a)

Intersperses the given value between each two elements of the collection, and sums the result.

Parameters:

as - An iterable of values.

a - The value to intersperse between values of the given iterable.

Returns:

The sum of the given values and the interspersed value.

sumNonEmpty

default A sumNonEmpty(A head,
                      Iterable<A> tail)

Description copied from interface: Semigroup

Reduce a 'non-empty' Iterable with Semigroup.append(Object, Object)

Specified by:

sumNonEmpty in interface Semigroup<A>

Parameters:

head - the head of the 'non-empty' Iterable

tail - the tail (maybe an empty Iterable).

Returns:

the sum of all elements.

multiply1p

default A multiply1p(int n,
                     A a)

Description copied from interface: Semigroup

Returns a value summed n + 1 times ( a + a + ... + a) The default definition uses peasant multiplication, exploiting associativity to only require `O(log n)` uses of Semigroup.append(Object, Object).

Specified by:

multiply1p in interface Semigroup<A>

Parameters:

n - multiplier

a - the value to be reapeatly summed n + 1 times

Returns:

a summed n times. If n <= 0, returns zero()

compose

static <A,B> Monoid<Pair<A,B>> compose(Monoid<A> ma,
                                       Monoid<B> mb)

Composes a monoid with another.

dual

static <A> Monoid<A> dual(Monoid<A> monoid)

Return the dual Monoid.

Parameters:

monoid - a monoid.

Returns:

a Monoid appending in reverse order,