# Prelude

- Package
- prelude
- Repository
- purerl/purescript-prelude

`Prelude`

is a module that re-exports many other foundational modules from the `purescript-prelude`

library
(e.g. the Monad type class hierarchy, the Monoid type classes, Eq, Ord, etc.).

Typically, this module will be imported in most other libraries and projects as an open import.

```
module MyModule where
import Prelude -- open import
import Data.Maybe (Maybe(..)) -- closed import
```

## Re-exports from **Control.**Applicative

### #Applicative Source

`class Applicative :: (Type -> Type) -> Constraint`

`class (Apply f) <= Applicative f where`

The `Applicative`

type class extends the `Apply`

type class
with a `pure`

function, which can be used to create values of type `f a`

from values of type `a`

.

Where `Apply`

provides the ability to lift functions of two or
more arguments to functions whose arguments are wrapped using `f`

, and
`Functor`

provides the ability to lift functions of one
argument, `pure`

can be seen as the function which lifts functions of
*zero* arguments. That is, `Applicative`

functors support a lifting
operation for any number of function arguments.

Instances must satisfy the following laws in addition to the `Apply`

laws:

- Identity:
`(pure identity) <*> v = v`

- Composition:
`pure (<<<) <*> f <*> g <*> h = f <*> (g <*> h)`

- Homomorphism:
`(pure f) <*> (pure x) = pure (f x)`

- Interchange:
`u <*> (pure y) = (pure (_ $ y)) <*> u`

#### Members

`pure :: forall a. a -> f a`

#### Instances

### #when Source

`when :: forall m. Applicative m => Boolean -> m Unit -> m Unit`

Perform an applicative action when a condition is true.

### #unless Source

`unless :: forall m. Applicative m => Boolean -> m Unit -> m Unit`

Perform an applicative action unless a condition is true.

### #liftA1 Source

`liftA1 :: forall f a b. Applicative f => (a -> b) -> f a -> f b`

`liftA1`

provides a default implementation of `(<$>)`

for any
`Applicative`

functor, without using `(<$>)`

as provided
by the `Functor`

-`Applicative`

superclass
relationship.

`liftA1`

can therefore be used to write `Functor`

instances
as follows:

```
instance functorF :: Functor F where
map = liftA1
```

## Re-exports from **Control.**Apply

### #Apply Source

`class Apply :: (Type -> Type) -> Constraint`

`class (Functor f) <= Apply f where`

The `Apply`

class provides the `(<*>)`

which is used to apply a function
to an argument under a type constructor.

`Apply`

can be used to lift functions of two or more arguments to work on
values wrapped with the type constructor `f`

. It might also be understood
in terms of the `lift2`

function:

```
lift2 :: forall f a b c. Apply f => (a -> b -> c) -> f a -> f b -> f c
lift2 f a b = f <$> a <*> b
```

`(<*>)`

is recovered from `lift2`

as `lift2 ($)`

. That is, `(<*>)`

lifts
the function application operator `($)`

to arguments wrapped with the
type constructor `f`

.

Put differently...

```
foo =
functionTakingNArguments <$> computationProducingArg1
<*> computationProducingArg2
<*> ...
<*> computationProducingArgN
```

Instances must satisfy the following law in addition to the `Functor`

laws:

- Associative composition:
`(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

Formally, `Apply`

represents a strong lax semi-monoidal endofunctor.

#### Members

`apply :: forall a b. f (a -> b) -> f a -> f b`

#### Instances

## Re-exports from **Control.**Bind

### #Bind Source

`class Bind :: (Type -> Type) -> Constraint`

`class (Apply m) <= Bind m where`

The `Bind`

type class extends the `Apply`

type class with a
"bind" operation `(>>=)`

which composes computations in sequence, using
the return value of one computation to determine the next computation.

The `>>=`

operator can also be expressed using `do`

notation, as follows:

```
x >>= f = do y <- x
f y
```

where the function argument of `f`

is given the name `y`

.

Instances must satisfy the following laws in addition to the `Apply`

laws:

- Associativity:
`(x >>= f) >>= g = x >>= (\k -> f k >>= g)`

- Apply Superclass:
`apply f x = f >>= \f’ -> map f’ x`

Associativity tells us that we can regroup operations which use `do`

notation so that we can unambiguously write, for example:

```
do x <- m1
y <- m2 x
m3 x y
```

#### Members

`bind :: forall a b. m a -> (a -> m b) -> m b`

#### Instances

### #Discard Source

`class Discard a where`

A class for types whose values can safely be discarded
in a `do`

notation block.

An example is the `Unit`

type, since there is only one
possible value which can be returned.

#### Members

#### Instances

### #(<=<) Source

Operator alias for Control.Bind.composeKleisliFlipped *(right-associative / precedence 1)*

## Re-exports from **Control.**Category

### #Category Source

`class Category :: forall k. (k -> k -> Type) -> Constraint`

`class (Semigroupoid a) <= Category a where`

`Category`

s consist of objects and composable morphisms between them, and
as such are `Semigroupoids`

, but unlike `semigroupoids`

must have an identity element.

Instances must satisfy the following law in addition to the
`Semigroupoid`

law:

- Identity:
`identity <<< p = p <<< identity = p`

#### Members

`identity :: forall t. a t t`

#### Instances

## Re-exports from **Control.**Monad

### #Monad Source

`class Monad :: (Type -> Type) -> Constraint`

`class (Applicative m, Bind m) <= Monad m`

The `Monad`

type class combines the operations of the `Bind`

and
`Applicative`

type classes. Therefore, `Monad`

instances represent type
constructors which support sequential composition, and also lifting of
functions of arbitrary arity.

Instances must satisfy the following laws in addition to the
`Applicative`

and `Bind`

laws:

- Left Identity:
`pure x >>= f = f x`

- Right Identity:
`x >>= pure = x`

#### Instances

### #liftM1 Source

`liftM1 :: forall m a b. Monad m => (a -> b) -> m a -> m b`

`liftM1`

provides a default implementation of `(<$>)`

for any
`Monad`

, without using `(<$>)`

as provided by the
`Functor`

-`Monad`

superclass relationship.

`liftM1`

can therefore be used to write `Functor`

instances
as follows:

```
instance functorF :: Functor F where
map = liftM1
```

## Re-exports from **Control.**Semigroupoid

### #Semigroupoid Source

`class Semigroupoid :: forall k. (k -> k -> Type) -> Constraint`

`class Semigroupoid a where`

A `Semigroupoid`

is similar to a `Category`

but does not
require an identity element `identity`

, just composable morphisms.

`Semigroupoid`

s must satisfy the following law:

- Associativity:
`p <<< (q <<< r) = (p <<< q) <<< r`

One example of a `Semigroupoid`

is the function type constructor `(->)`

,
with `(<<<)`

defined as function composition.

#### Members

`compose :: forall b c d. a c d -> a b c -> a b d`

#### Instances

### #(>>>) Source

Operator alias for Control.Semigroupoid.composeFlipped *(right-associative / precedence 9)*

## Re-exports from **Data.**Boolean

## Re-exports from **Data.**BooleanAlgebra

### #BooleanAlgebra Source

`class (HeytingAlgebra a) <= BooleanAlgebra a `

The `BooleanAlgebra`

type class represents types that behave like boolean
values.

Instances should satisfy the following laws in addition to the
`HeytingAlgebra`

law:

- Excluded middle:
`a || not a = tt`

#### Instances

`BooleanAlgebra Boolean`

`BooleanAlgebra Unit`

`(BooleanAlgebra b) => BooleanAlgebra (a -> b)`

`(RowToList row list, BooleanAlgebraRecord list row row) => BooleanAlgebra (Record row)`

`BooleanAlgebra (Proxy a)`

`BooleanAlgebra (Proxy2 a)`

`BooleanAlgebra (Proxy3 a)`

## Re-exports from **Data.**Bounded

### #Bounded Source

## Re-exports from **Data.**CommutativeRing

### #CommutativeRing Source

`class (Ring a) <= CommutativeRing a `

The `CommutativeRing`

class is for rings where multiplication is
commutative.

Instances must satisfy the following law in addition to the `Ring`

laws:

- Commutative multiplication:
`a * b = b * a`

#### Instances

`CommutativeRing Int`

`CommutativeRing Number`

`CommutativeRing Unit`

`(CommutativeRing b) => CommutativeRing (a -> b)`

`(RowToList row list, CommutativeRingRecord list row row) => CommutativeRing (Record row)`

`CommutativeRing (Proxy a)`

`CommutativeRing (Proxy2 a)`

`CommutativeRing (Proxy3 a)`

## Re-exports from **Data.**DivisionRing

### #DivisionRing Source

`class (Ring a) <= DivisionRing a where`

The `DivisionRing`

class is for non-zero rings in which every non-zero
element has a multiplicative inverse. Division rings are sometimes also
called *skew fields*.

Instances must satisfy the following laws in addition to the `Ring`

laws:

- Non-zero ring:
`one /= zero`

- Non-zero multiplicative inverse:
`recip a * a = a * recip a = one`

for all non-zero`a`

The result of `recip zero`

is left undefined; individual instances may
choose how to handle this case.

If a type has both `DivisionRing`

and `CommutativeRing`

instances, then
it is a field and should have a `Field`

instance.

#### Members

`recip :: a -> a`

#### Instances

## Re-exports from **Data.**Eq

### #Eq Source

`class Eq a where`

The `Eq`

type class represents types which support decidable equality.

`Eq`

instances should satisfy the following laws:

- Reflexivity:
`x == x = true`

- Symmetry:
`x == y = y == x`

- Transitivity: if
`x == y`

and`y == z`

then`x == z`

**Note:** The `Number`

type is not an entirely law abiding member of this
class due to the presence of `NaN`

, since `NaN /= NaN`

. Additionally,
computing with `Number`

can result in a loss of precision, so sometimes
values that should be equivalent are not.

#### Members

#### Instances

## Re-exports from **Data.**EuclideanRing

### #EuclideanRing Source

`class (CommutativeRing a) <= EuclideanRing a where`

The `EuclideanRing`

class is for commutative rings that support division.
The mathematical structure this class is based on is sometimes also called
a *Euclidean domain*.

Instances must satisfy the following laws in addition to the `Ring`

laws:

- Integral domain:
`one /= zero`

, and if`a`

and`b`

are both nonzero then so is their product`a * b`

- Euclidean function
`degree`

:- Nonnegativity: For all nonzero
`a`

,`degree a >= 0`

- Quotient/remainder: For all
`a`

and`b`

, where`b`

is nonzero, let`q = a / b`

and`r = a `mod` b`

; then`a = q*b + r`

, and also either`r = zero`

or`degree r < degree b`

- Nonnegativity: For all nonzero
- Submultiplicative euclidean function:
- For all nonzero
`a`

and`b`

,`degree a <= degree (a * b)`

- For all nonzero

The behaviour of division by `zero`

is unconstrained by these laws,
meaning that individual instances are free to choose how to behave in this
case. Similarly, there are no restrictions on what the result of
`degree zero`

is; it doesn't make sense to ask for `degree zero`

in the
same way that it doesn't make sense to divide by `zero`

, so again,
individual instances may choose how to handle this case.

For any `EuclideanRing`

which is also a `Field`

, one valid choice
for `degree`

is simply `const 1`

. In fact, unless there's a specific
reason not to, `Field`

types should normally use this definition of
`degree`

.

The `EuclideanRing Int`

instance is one of the most commonly used
`EuclideanRing`

instances and deserves a little more discussion. In
particular, there are a few different sensible law-abiding implementations
to choose from, with slightly different behaviour in the presence of
negative dividends or divisors. The most common definitions are "truncating"
division, where the result of `a / b`

is rounded towards 0, and "Knuthian"
or "flooring" division, where the result of `a / b`

is rounded towards
negative infinity. A slightly less common, but arguably more useful, option
is "Euclidean" division, which is defined so as to ensure that `a `mod` b`

is always nonnegative. With Euclidean division, `a / b`

rounds towards
negative infinity if the divisor is positive, and towards positive infinity
if the divisor is negative. Note that all three definitions are identical if
we restrict our attention to nonnegative dividends and divisors.

In versions 1.x, 2.x, and 3.x of the Prelude, the `EuclideanRing Int`

instance used truncating division. As of 4.x, the `EuclideanRing Int`

instance uses Euclidean division. Additional functions `quot`

and `rem`

are
supplied if truncating division is desired.

#### Members

#### Instances

### #lcm Source

`lcm :: forall a. Eq a => EuclideanRing a => a -> a -> a`

The *least common multiple* of two values.

### #gcd Source

`gcd :: forall a. Eq a => EuclideanRing a => a -> a -> a`

The *greatest common divisor* of two values.

## Re-exports from **Data.**Field

### #Field Source

`class (EuclideanRing a, DivisionRing a) <= Field a `

The `Field`

class is for types that are (commutative) fields.

Mathematically, a field is a ring which is commutative and in which every
nonzero element has a multiplicative inverse; these conditions correspond
to the `CommutativeRing`

and `DivisionRing`

classes in PureScript
respectively. However, the `Field`

class has `EuclideanRing`

and
`DivisionRing`

as superclasses, which seems like a stronger requirement
(since `CommutativeRing`

is a superclass of `EuclideanRing`

). In fact, it
is not stronger, since any type which has law-abiding `CommutativeRing`

and `DivisionRing`

instances permits exactly one law-abiding
`EuclideanRing`

instance. We use a `EuclideanRing`

superclass here in
order to ensure that a `Field`

constraint on a function permits you to use
`div`

on that type, since `div`

is a member of `EuclideanRing`

.

This class has no laws or members of its own; it exists as a convenience, so a single constraint can be used when field-like behaviour is expected.

This module also defines a single `Field`

instance for any type which has
both `EuclideanRing`

and `DivisionRing`

instances. Any other instance
would overlap with this instance, so no other `Field`

instances should be
defined in libraries. Instead, simply define `EuclideanRing`

and
`DivisionRing`

instances, and this will permit your type to be used with a
`Field`

constraint.

#### Instances

`(EuclideanRing a, DivisionRing a) => Field a`

## Re-exports from **Data.**Function

### #flip Source

`flip :: forall a b c. (a -> b -> c) -> b -> a -> c`

Given a function that takes two arguments, applies the arguments to the function in a swapped order.

```
flip append "1" "2" == append "2" "1" == "21"
const 1 "two" == 1
flip const 1 "two" == const "two" 1 == "two"
```

### #const Source

`const :: forall a b. a -> b -> a`

Returns its first argument and ignores its second.

```
const 1 "hello" = 1
```

It can also be thought of as creating a function that ignores its argument:

```
const 1 = \_ -> 1
```

### #($) Source

Operator alias for Data.Function.apply *(right-associative / precedence 0)*

Applies a function to an argument: the reverse of `(#)`

.

```
length $ groupBy productCategory $ filter isInStock $ products
```

is equivalent to:

```
length (groupBy productCategory (filter isInStock products))
```

Or another alternative equivalent, applying chain of composed functions to a value:

```
length <<< groupBy productCategory <<< filter isInStock $ products
```

### #(#) Source

Operator alias for Data.Function.applyFlipped *(left-associative / precedence 1)*

Applies an argument to a function: the reverse of `($)`

.

```
products # filter isInStock # groupBy productCategory # length
```

is equivalent to:

```
length (groupBy productCategory (filter isInStock products))
```

Or another alternative equivalent, applying a value to a chain of composed functions:

```
products # filter isInStock >>> groupBy productCategory >>> length
```

## Re-exports from **Data.**Functor

### #Functor Source

`class Functor :: (Type -> Type) -> Constraint`

`class Functor f where`

A `Functor`

is a type constructor which supports a mapping operation
`map`

.

`map`

can be used to turn functions `a -> b`

into functions
`f a -> f b`

whose argument and return types use the type constructor `f`

to represent some computational context.

Instances must satisfy the following laws:

- Identity:
`map identity = identity`

- Composition:
`map (f <<< g) = map f <<< map g`

#### Members

`map :: forall a b. (a -> b) -> f a -> f b`

#### Instances

### #void Source

`void :: forall f a. Functor f => f a -> f Unit`

The `void`

function is used to ignore the type wrapped by a
`Functor`

, replacing it with `Unit`

and keeping only the type
information provided by the type constructor itself.

`void`

is often useful when using `do`

notation to change the return type
of a monadic computation:

```
main = forE 1 10 \n -> void do
print n
print (n * n)
```

### #flap Source

`flap :: forall f a b. Functor f => f (a -> b) -> a -> f b`

Apply a value in a computational context to a value in no context.

Generalizes `flip`

.

```
longEnough :: String -> Bool
hasSymbol :: String -> Bool
hasDigit :: String -> Bool
password :: String
validate :: String -> Array Bool
validate = flap [longEnough, hasSymbol, hasDigit]
```

```
flap (-) 3 4 == 1
threeve <$> Just 1 <@> 'a' <*> Just true == Just (threeve 1 'a' true)
```

## Re-exports from **Data.**HeytingAlgebra

### #HeytingAlgebra Source

`class HeytingAlgebra a where`

The `HeytingAlgebra`

type class represents types that are bounded lattices with
an implication operator such that the following laws hold:

- Associativity:
`a || (b || c) = (a || b) || c`

`a && (b && c) = (a && b) && c`

- Commutativity:
`a || b = b || a`

`a && b = b && a`

- Absorption:
`a || (a && b) = a`

`a && (a || b) = a`

- Idempotent:
`a || a = a`

`a && a = a`

- Identity:
`a || ff = a`

`a && tt = a`

- Implication:
`a `implies` a = tt`

`a && (a `implies` b) = a && b`

`b && (a `implies` b) = b`

`a `implies` (b && c) = (a `implies` b) && (a `implies` c)`

- Complemented:
`not a = a `implies` ff`

#### Members

#### Instances

`HeytingAlgebra Boolean`

`HeytingAlgebra Unit`

`(HeytingAlgebra b) => HeytingAlgebra (a -> b)`

`HeytingAlgebra (Proxy a)`

`HeytingAlgebra (Proxy2 a)`

`HeytingAlgebra (Proxy3 a)`

`(RowToList row list, HeytingAlgebraRecord list row row) => HeytingAlgebra (Record row)`

## Re-exports from **Data.**Monoid

### #Monoid Source

`class (Semigroup m) <= Monoid m where`

A `Monoid`

is a `Semigroup`

with a value `mempty`

, which is both a
left and right unit for the associative operation `<>`

:

- Left unit:
`(mempty <> x) = x`

- Right unit:
`(x <> mempty) = x`

`Monoid`

s are commonly used as the result of fold operations, where
`<>`

is used to combine individual results, and `mempty`

gives the result
of folding an empty collection of elements.

### Newtypes for Monoid

Some types (e.g. `Int`

, `Boolean`

) can implement multiple law-abiding
instances for `Monoid`

. Let's use `Int`

as an example

`<>`

could be`+`

and`mempty`

could be`0`

`<>`

could be`*`

and`mempty`

could be`1`

.

To clarify these ambiguous situations, one should use the newtypes
defined in `Data.Monoid.<NewtypeName>`

modules.

In the above ambiguous situation, we could use `Additive`

for the first situation or `Multiplicative`

for the second one.

#### Members

`mempty :: m`

#### Instances

## Re-exports from **Data.**NaturalTransformation

### #type (~>) Source

Operator alias for Data.NaturalTransformation.NaturalTransformation *(right-associative / precedence 4)*

## Re-exports from **Data.**Ord

### #Ord Source

## Re-exports from **Data.**Ordering

### #Ordering Source

`data Ordering`

The `Ordering`

data type represents the three possible outcomes of
comparing two values:

`LT`

- The first value is *less than* the second.
`GT`

- The first value is *greater than* the second.
`EQ`

- The first value is *equal to* the second.

#### Constructors

#### Instances

## Re-exports from **Data.**Ring

### #Ring Source

`class (Semiring a) <= Ring a where`

The `Ring`

class is for types that support addition, multiplication,
and subtraction operations.

Instances must satisfy the following laws in addition to the `Semiring`

laws:

- Additive inverse:
`a - a = zero`

- Compatibility of
`sub`

and`negate`

:`a - b = a + (zero - b)`

#### Members

`sub :: a -> a -> a`

#### Instances

## Re-exports from **Data.**Semigroup

### #Semigroup Source

`class Semigroup a where`

The `Semigroup`

type class identifies an associative operation on a type.

Instances are required to satisfy the following law:

- Associativity:
`(x <> y) <> z = x <> (y <> z)`

One example of a `Semigroup`

is `String`

, with `(<>)`

defined as string
concatenation. Another example is `List a`

, with `(<>)`

defined as
list concatenation.

### Newtypes for Semigroup

There are two other ways to implement an instance for this type class regardless of which type is used. These instances can be used by wrapping the values in one of the two newtypes below:

`First`

- Use the first argument every time:`append first _ = first`

.`Last`

- Use the last argument every time:`append _ last = last`

.

#### Members

`append :: a -> a -> a`

#### Instances

## Re-exports from **Data.**Semiring

### #Semiring Source

`class Semiring a where`

The `Semiring`

class is for types that support an addition and
multiplication operation.

Instances must satisfy the following laws:

- Commutative monoid under addition:
- Associativity:
`(a + b) + c = a + (b + c)`

- Identity:
`zero + a = a + zero = a`

- Commutative:
`a + b = b + a`

- Associativity:
- Monoid under multiplication:
- Associativity:
`(a * b) * c = a * (b * c)`

- Identity:
`one * a = a * one = a`

- Associativity:
- Multiplication distributes over addition:
- Left distributivity:
`a * (b + c) = (a * b) + (a * c)`

- Right distributivity:
`(a + b) * c = (a * c) + (b * c)`

- Left distributivity:
- Annihilation:
`zero * a = a * zero = zero`

**Note:** The `Number`

and `Int`

types are not fully law abiding
members of this class hierarchy due to the potential for arithmetic
overflows, and in the case of `Number`

, the presence of `NaN`

and
`Infinity`

values. The behaviour is unspecified in these cases.

#### Members

#### Instances

## Re-exports from **Data.**Show

### #Show Source

`class Show a where`

The `Show`

type class represents those types which can be converted into
a human-readable `String`

representation.

While not required, it is recommended that for any expression `x`

, the
string `show x`

be executable PureScript code which evaluates to the same
value as the expression `x`

.

#### Members

#### Instances

## Re-exports from **Data.**Unit

### #Unit Source

`data Unit :: Type`

The `Unit`

type has a single inhabitant, called `unit`

. It represents
values with no computational content.

`Unit`

is often used, wrapped in a monadic type constructor, as the
return type of a computation where only the *effects* are important.

When returning a value of type `Unit`

from an FFI function, it is
recommended to use `undefined`

, or not return a value at all.

#### Instances

## Re-exports from **Data.**Void

### #Void Source

`newtype Void`

An uninhabited data type. In other words, one can never create
a runtime value of type `Void`

becaue no such value exists.

`Void`

is useful to eliminate the possibility of a value being created.
For example, a value of type `Either Void Boolean`

can never have
a Left value created in PureScript.

This should not be confused with the keyword `void`

that commonly appears in
C-family languages, such as Java:

```
public class Foo {
void doSomething() { System.out.println("hello world!"); }
}
```

In PureScript, one often uses `Unit`

to achieve similar effects as
the `void`

of C-family languages above.

#### Instances

- Modules
- Control.
Applicative - Control.
Apply - Control.
Bind - Control.
Category - Control.
Monad - Control.
Semigroupoid - Data.
Boolean - Data.
BooleanAlgebra - Data.
Bounded - Data.
Bounded. Generic - Data.
CommutativeRing - Data.
DivisionRing - Data.
Eq - Data.
Eq. Generic - Data.
EuclideanRing - Data.
Field - Data.
Function - Data.
Functor - Data.
Generic. Rep - Data.
HeytingAlgebra - Data.
HeytingAlgebra. Generic - Data.
Monoid - Data.
Monoid. Additive - Data.
Monoid. Conj - Data.
Monoid. Disj - Data.
Monoid. Dual - Data.
Monoid. Endo - Data.
Monoid. Generic - Data.
Monoid. Multiplicative - Data.
NaturalTransformation - Data.
Ord - Data.
Ord. Generic - Data.
Ordering - Data.
Ring - Data.
Ring. Generic - Data.
Semigroup - Data.
Semigroup. First - Data.
Semigroup. Generic - Data.
Semigroup. Last - Data.
Semiring - Data.
Semiring. Generic - Data.
Show - Data.
Show. Generic - Data.
Symbol - Data.
Unit - Data.
Void - Prelude
- Record.
Unsafe - Type.
Data. Row - Type.
Data. RowList - Type.
Proxy

The

`bind`

/`>>=`

function for`Array`

works by applying a function to each element in the array, and flattening the results into a single, new array.Array's

`bind`

/`>>=`

works like a nested for loop. Each`bind`

adds another level of nesting in the loop. For example: