## Semigroup overview

If a type `A` can form a `Semigroup` it has an associative binary operation.

``````interface Semigroup<A> {
readonly concat: (x: A, y: A) => A
}
``````

Associativity means the following equality must hold for any choice of `x`, `y`, and `z`.

``````concat(x, concat(y, z)) = concat(concat(x, y), z)
``````

A common example of a semigroup is the type `string` with the operation `+`.

``````import { Semigroup } from 'fp-ts/Semigroup'

const semigroupString: Semigroup<string> = {
concat: (x, y) => x + y,
}

const x = 'x'
const y = 'y'
const z = 'z'

semigroupString.concat(x, y) // 'xy'

semigroupString.concat(x, semigroupString.concat(y, z)) // 'xyz'

semigroupString.concat(semigroupString.concat(x, y), z) // 'xyz'
``````

# constructors

## constant

Signature

``````export declare const constant: <A>(a: A) => Semigroup<A>
``````

## max

Get a semigroup where `concat` will return the maximum, based on the provided order.

Signature

``````export declare const max: <A>(O: Or.Ord<A>) => Semigroup<A>
``````

Example

``````import * as N from 'fp-ts/number'
import * as S from 'fp-ts/Semigroup'

const S1 = S.max(N.Ord)

assert.deepStrictEqual(S1.concat(1, 2), 2)
``````

## min

Get a semigroup where `concat` will return the minimum, based on the provided order.

Signature

``````export declare const min: <A>(O: Or.Ord<A>) => Semigroup<A>
``````

Example

``````import * as N from 'fp-ts/number'
import * as S from 'fp-ts/Semigroup'

const S1 = S.min(N.Ord)

assert.deepStrictEqual(S1.concat(1, 2), 1)
``````

# instances

## first

Always return the first argument.

Signature

``````export declare const first: <A = never>() => Semigroup<A>
``````

Example

``````import * as S from 'fp-ts/Semigroup'

assert.deepStrictEqual(S.first<number>().concat(1, 2), 1)
``````

## last

Always return the last argument.

Signature

``````export declare const last: <A = never>() => Semigroup<A>
``````

Example

``````import * as S from 'fp-ts/Semigroup'

assert.deepStrictEqual(S.last<number>().concat(1, 2), 2)
``````

# model

## Semigroup (interface)

Signature

``````export interface Semigroup<A> extends Magma<A> {}
``````

# utils

## concatAll

Given a sequence of `as`, concat them and return the total.

If `as` is empty, return the provided `startWith` value.

Signature

``````export declare const concatAll: <A>(S: Semigroup<A>) => (startWith: A) => (as: readonly A[]) => A
``````

Example

``````import { concatAll } from 'fp-ts/Semigroup'
import * as N from 'fp-ts/number'

const sum = concatAll(N.SemigroupSum)(0)

assert.deepStrictEqual(sum([1, 2, 3]), 6)
assert.deepStrictEqual(sum([]), 0)
``````

## intercalate

Between each pair of elements insert `middle`.

Signature

``````export declare const intercalate: <A>(middle: A) => (S: Semigroup<A>) => Semigroup<A>
``````

Example

``````import { intercalate } from 'fp-ts/Semigroup'
import * as S from 'fp-ts/string'
import { pipe } from 'fp-ts/function'

const S1 = pipe(S.Semigroup, intercalate(' + '))

assert.strictEqual(S1.concat('a', 'b'), 'a + b')
``````

## reverse

The dual of a `Semigroup`, obtained by swapping the arguments of `concat`.

Signature

``````export declare const reverse: <A>(S: Semigroup<A>) => Semigroup<A>
``````

Example

``````import { reverse } from 'fp-ts/Semigroup'
import * as S from 'fp-ts/string'

assert.deepStrictEqual(reverse(S.Semigroup).concat('a', 'b'), 'ba')
``````

## struct

Given a struct of semigroups returns a semigroup for the struct.

Signature

``````export declare const struct: <A>(semigroups: { [K in keyof A]: Semigroup<A[K]> }) => Semigroup<{
readonly [K in keyof A]: A[K]
}>
``````

Example

``````import { struct } from 'fp-ts/Semigroup'
import * as N from 'fp-ts/number'

interface Point {
}

const S = struct<Point>({
x: N.SemigroupSum,
y: N.SemigroupSum,
})

assert.deepStrictEqual(S.concat({ x: 1, y: 2 }, { x: 3, y: 4 }), { x: 4, y: 6 })
``````

## tuple

Given a tuple of semigroups returns a semigroup for the tuple.

Signature

``````export declare const tuple: <A extends readonly unknown[]>(
...semigroups: { [K in keyof A]: Semigroup<A[K]> }
``````

Example

``````import { tuple } from 'fp-ts/Semigroup'
import * as B from 'fp-ts/boolean'
import * as N from 'fp-ts/number'
import * as S from 'fp-ts/string'

const S1 = tuple(S.Semigroup, N.SemigroupSum)
assert.deepStrictEqual(S1.concat(['a', 1], ['b', 2]), ['ab', 3])

const S2 = tuple(S.Semigroup, N.SemigroupSum, B.SemigroupAll)
assert.deepStrictEqual(S2.concat(['a', 1, true], ['b', 2, false]), ['ab', 3, false])
``````

# zone of death

## fold

Use `concatAll` instead.

Signature

``````export declare function fold<A>(S: Semigroup<A>): {
(startWith: A): (as: ReadonlyArray<A>) => A
}
``````

## getDualSemigroup

Use `reverse` instead.

Signature

``````export declare const getDualSemigroup: <A>(S: Semigroup<A>) => Semigroup<A>
``````

## getFirstSemigroup

Use `first` instead.

Signature

``````export declare const getFirstSemigroup: <A = never>() => Semigroup<A>
``````

## getFunctionSemigroup

Use `getSemigroup` instead.

Signature

``````export declare const getFunctionSemigroup: <S>(S: Semigroup<S>) => <A = never>() => Semigroup<(a: A) => S>
``````

## getIntercalateSemigroup

Use `intercalate` instead.

Signature

``````export declare const getIntercalateSemigroup: <A>(middle: A) => (S: Semigroup<A>) => Semigroup<A>
``````

## getJoinSemigroup

Use `max` instead.

Signature

``````export declare const getJoinSemigroup: <A>(O: Or.Ord<A>) => Semigroup<A>
``````

## getLastSemigroup

Use `last` instead.

Signature

``````export declare const getLastSemigroup: <A = never>() => Semigroup<A>
``````

## getMeetSemigroup

Use `min` instead.

Signature

``````export declare const getMeetSemigroup: <A>(O: Or.Ord<A>) => Semigroup<A>
``````

## getObjectSemigroup

Use `getAssignSemigroup` instead.

Signature

``````export declare const getObjectSemigroup: <A extends object = never>() => Semigroup<A>
``````

## getStructSemigroup

Use `struct` instead.

Signature

``````export declare const getStructSemigroup: <O extends Readonly<Record<string, any>>>(semigroups: {
[K in keyof O]: Semigroup<O[K]>
}) => Semigroup<O>
``````

## getTupleSemigroup

Use `tuple` instead.

Signature

``````export declare const getTupleSemigroup: <T extends readonly Semigroup<any>[]>(
...semigroups: T
) => Semigroup<{ [K in keyof T]: T[K] extends Semigroup<infer A> ? A : never }>
``````

## semigroupAll

Use `SemigroupAll` instead.

Signature

``````export declare const semigroupAll: Semigroup<boolean>
``````

## semigroupAny

Use `SemigroupAny` instead.

Signature

``````export declare const semigroupAny: Semigroup<boolean>
``````

## semigroupProduct

Use `SemigroupProduct` instead.

Signature

``````export declare const semigroupProduct: Semigroup<number>
``````

## semigroupString

Use `Semigroup` instead.

Signature

``````export declare const semigroupString: Semigroup<string>
``````

## semigroupSum

Use `SemigroupSum` instead.

Signature

``````export declare const semigroupSum: Semigroup<number>
``````

Use `void` module instead.
``````export declare const semigroupVoid: Semigroup<void>