1371017 · rowtype-yoga/purescript-native

git.iko.soy/rowtype-yoga/purescript-native

Prelude documentation

commit1371017eeb2ce399ac89dc3a6b9852f458768b82 authorPhil Freeman <paf31@cantab.net> dateMon 2 Mar 2015, 12:24 (12 years ago) parent388a369

3 files changed+297−41

compare with golang

unifiedsplit

prelude/README.md+149−21 prelude/images/Prelude.png prelude/prelude.purs+148−20

prelude/README.md+149−21

@@ -72,6 +72,8 @@ element `id`, just composable morphisms.

7272

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

7474

75+One example of a `Semigroupoid` is the function type constructor `(->)`, with `(<<<)` defined

76+as function composition.

7577

7678#### `semigroupoidArr`

7779

@@ -86,6 +88,7 @@ instance semigroupoidArr :: Semigroupoid Prim.Function

8688(>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

8789```

8890

91+Forwards composition, or `(<<<)` with its arguments reversed.

8992

9093#### `Category`

9194

@@ -160,13 +163,12 @@ length (groupBy productCategory (filter isInStock (products)))

160163(:) :: forall a. a -> [a] -> [a]

161164```

162165

163−Attaches an element to the front of a list.

166+Attaches an element to the front of an array, creating a new array.

164167

165168```purescript

1661691 : [2, 3, 4] = [1, 2, 3, 4]

167170```

168171

169−

170172#### `cons`

171173

172174``` purescript

@@ -181,6 +183,10 @@ class Show a where

181183 show :: a -> String

182184```

183185

186+The `Show` type class represents those types which can be converted into a human-readable `String` representation.

187+

188+While not required, it is recommended that for any expression `x`, the string `show x` be executable PureScript code

189+which evaluates to the same value as the expression `x`.

184190

185191#### `showUnit`

186192

@@ -224,10 +230,12 @@ class Functor f where

224230 (<$>) :: forall a b. (a -> b) -> f a -> f b

225231```

226232

227−A `Functor` is intuitively a type which can be mapped over, and more formally a mapping

228−between [`Category`](#category)s that preserves structure.

233+A `Functor` is a type constructor which supports a mapping operation `(<$>)`.

229234

230−`Functor`s should obey the following rules.

235+`(<$>)` can be used to turn functions `a -> b` into functions `f a -> f b` whose argument and return

236+types use the type constructor `f` to represent some computational context.

237+

238+`Functor` instances should satisfy the following laws:

231239

232240- Identity: `(<$>) id = id`

233241- Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

@@ -239,6 +247,11 @@ between [`Category`](#category)s that preserves structure.

239247(<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

240248```

241249

250+`(<#>)` is `(<$>)` with its arguments flipped. For example:

251+

252+```purescript

253+[1, 2, 3] <#> \n -> n * n

254+```

242255

243256#### `void`

244257

@@ -246,6 +259,16 @@ between [`Category`](#category)s that preserves structure.

246259void :: forall f a. (Functor f) => f a -> f Unit

247260```

248261

262+The `void` function is used to ignore the type wrapped by a [`Functor`](#functor), replacing it with `Unit` and

263+keeping only the type information provided by the type constructor itself.

264+

265+`void` is often useful when using `do` notation to change the return type of a monadic computation:

266+

267+```purescript

268+main = forE 1 10 \n -> void do

269+ print n

270+ print (n * n)

271+```

249272

250273#### `Apply`

251274

@@ -254,13 +277,24 @@ class (Functor f) <= Apply f where

254277 (<*>) :: forall a b. f (a -> b) -> f a -> f b

255278```

256279

257−`Apply`s are intuitively [`Applicative`](#applicative)s less `pure`, and more formally a

258−strong lax semi-monoidal endofunctor.

280+The `Apply` class provides the `(<*>)` which is used to apply a function to an argument under a type constructor.

259281

260−`Apply`s should obey the following rule.

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

283+It might also be understood in terms of the `lift2` function:

284+

285+```purescript

286+lift2 :: forall f a b c. (Apply f) => (a -> b -> c) -> f a -> f b -> f c

287+lift2 f a b = f <$> a <*> b

288+```

289+

290+`(<*>)` is recovered from `lift2` as `lift2 ($)`. That is, `(<*>)` lifts the function application operator `($)` to arguments

291+wrapped with the type constructor `f`.

292+

293+`Apply` instances should satisfy the following law:

261294

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

263296

297+Formally, `Apply` represents a strong lax semi-monoidal endofunctor.

264298

265299#### `Applicative`

266300

@@ -269,10 +303,14 @@ class (Apply f) <= Applicative f where

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

270304```

271305

272−`Applicative`s are [`Functor`](#functor)s which can be "applied" by sequencing composition

273−(`<*>`) or embedding pure expressions (`pure`).

306+The `Applicative` type class extends the [`Apply`](#apply) type class with a `pure` function, which can be used to

307+create values of type `f a` from values of type `a`.

308+

309+Where [`Apply`](#apply) provides the ability to lift functions of two or more arguments to functions whose arguments are wrapped using `f`,

310+and [`Functor`](#functor) provides the ability to lift functions of one argument, `pure` can be seen as the function which lifts functions of

311+_zero_ arguments. That is, `Applicative` functors support a lifting operation for any number of function arguments.

274312

275−`Applicative`s should obey the following rules.

313+`Applicative` instances should satisfy the following laws:

276314

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

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

@@ -286,6 +324,15 @@ class (Apply f) <= Applicative f where

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

287325```

288326

327+`liftA1` provides a default implementation of `(<$>)` for any [`Applicative`](#applicative) functor,

328+without using `(<$>)` as provided by the [`Functor`](#functor)-[`Applicative`](#applicative) superclass relationship.

329+

330+`liftA1` can therefore be used to write [`Functor`](#functor) instances as follows:

331+

332+```purescript

333+instance functorF :: Functor F where

334+ (<$>) = liftA1

335+```

289336

290337#### `Bind`

291338

@@ -294,12 +341,33 @@ class (Apply m) <= Bind m where

294341 (>>=) :: forall a b. m a -> (a -> m b) -> m b

295342```

296343

297−A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially composes actions.

344+The `Bind` type class extends the [`Apply`](#apply) type class with a "bind" operation `(>>=)` which composes computations

345+in sequence, using the return value of one computation to determine the next computation.

346+

347+The `>>=` operator can also be expressed using `do` notation, as follows:

348+

349+```purescript

350+x >>= f = do y <- x

351+ f y

352+```

353+

354+where the function argument of `f` is given the name `y`.

298355

299−`Bind`s should obey the following rule.

356+`Bind` instances should satisfy the following law:

300357

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

302359

360+Or, expressed using `do` notation:

361+

362+- Associativity: `do { z <- do { y <- x ; f y } ; g z } = do { k <- x ; do { y <- f k ; g y } }`

363+

364+Associativity tells us that we can regroup operations which use do-notation, so that we can unambiguously write, for example:

365+

366+```purescript

367+do x <- m1

368+ y <- m2 x

369+ m3 x y

370+```

303371

304372#### `Monad`

305373

@@ -307,14 +375,19 @@ A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially compos

307375class (Applicative m, Bind m) <= Monad m where

308376```

309377

310−`Monad` is a class which can be intuitively thought of as an abstract datatype of actions or

311−more formally though of as a monoid in the category of endofunctors.

378+The `Monad` type class combines the operations of the `Bind` and `Applicative` type classes. Therefore, `Monad` instances

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

312380

313−`Monad`s should obey the following rules.

381+`Monad` instances should satisfy the following laws:

314382

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

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

317385

386+Or, expressed using `do` notation:

387+

388+- Left Identity: `do { y <- pure x ; f y } = f x`

389+- Right Identity: `do { y <- x ; pure y } = x`

390+

318391

319392#### `return`

320393

@@ -322,6 +395,7 @@ more formally though of as a monoid in the category of endofunctors.

322395return :: forall m a. (Monad m) => a -> m a

323396```

324397

398+`return` is an alias for `pure`.

325399

326400#### `liftM1`

327401

@@ -329,6 +403,15 @@ return :: forall m a. (Monad m) => a -> m a

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

330404```

331405

406+`liftM1` provides a default implementation of `(<$>)` for any [`Monad`](#monad),

407+without using `(<$>)` as provided by the [`Functor`](#functor)-[`Monad`](#monad) superclass relationship.

408+

409+`liftM1` can therefore be used to write [`Functor`](#functor) instances as follows:

410+

411+```purescript

412+instance functorF :: Functor F where

413+ (<$>) = liftM1

414+```

332415

333416#### `ap`

334417

@@ -336,6 +419,15 @@ liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

336419ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

337420```

338421

422+`ap` provides a default implementation of `(<*>)` for any [`Monad`](#monad),

423+without using `(<*>)` as provided by the [`Apply`](#apply)-[`Monad`](#monad) superclass relationship.

424+

425+`ap` can therefore be used to write [`Apply`](#apply) instances as follows:

426+

427+```purescript

428+instance applyF :: Apply F where

429+ (<*>) = ap

430+```

339431

340432#### `functorArr`

341433

@@ -384,8 +476,8 @@ class Semiring a where

384476

385477Addition and multiplication, satisfying the following laws:

386478

387−- `a` is a commutative monoid under addition with identity element zero

388−- `a` is a monoid under multiplication with identity element one

479+- `a` is a commutative monoid under addition

480+- `a` is a monoid under multiplication

389481- multiplication distributes over addition

390482- multiplication by `zero` annihilates `a`

391483

@@ -485,6 +577,10 @@ newtype Unit

485577 = Unit { }

486578```

487579

580+The `Unit` type has a single inhabitant, called `unit`. It represents values with no computational content.

581+

582+`Unit` is often used, wrapped in a monadic type constructor, as the return type of a computation where only

583+the _effects_ are important.

488584

489585#### `unit`

490586

@@ -492,6 +588,7 @@ newtype Unit

492588unit :: Unit

493589```

494590

591+`unit` is the sole inhabitant of the `Unit` type.

495592

496593#### `Eq`

497594

@@ -501,7 +598,16 @@ class Eq a where

501598 (/=) :: a -> a -> Boolean

502599```

503600

504−Class for types that have an equality comparison.

601+The `Eq` type class represents types which support decidable equality.

602+

603+`Eq` instances should satisfy the following laws:

604+

605+- Reflexivity: `forall x. x == x = true`

606+- Symmetry: `forall x y. x == y = y == x`

607+- Transitivity: if `x == y` and `y == z` then `x == z`

608+- Negation: `forall x y. x /= y = not (x == y)`

609+

610+`(/=)` may be implemented in terms of `(==)`, but it might give a performance improvement to implement it separately.

505611

506612#### `refEq`

507613

@@ -561,6 +667,11 @@ data Ordering

561667 | EQ

562668```

563669

670+The `Ordering` data type represents the three possible outcomes of comparing two values:

671+

672+`LT` - The first value is _less than_ the second.

673+`GT` - The first value is _greater than_ the second.

674+`EQ` - The first value is _equal to_ or _incomparable to_ the second.

564675

565676#### `eqOrdering`

566677

@@ -590,9 +701,9 @@ class (Eq a) <= Ord a where

590701 compare :: a -> a -> Ordering

591702```

592703

593−Class for types that have ordered comparisons.

704+The `Ord` type class represents types which support comparisons.

594705

595−Represents a partially ordered set satisfying the following laws:

706+`Ord` instances should satisfy the laws of _partially orderings_:

596707

597708- Reflexivity: `a <= a`

598709- Antisymmetry: if `a <= b` and `b <= a` then `a = b`

@@ -605,6 +716,7 @@ Represents a partially ordered set satisfying the following laws:

605716(<) :: forall a. (Ord a) => a -> a -> Boolean

606717```

607718

719+Test whether one value is _strictly less than_ another.

608720

609721#### `(>)`

610722

@@ -612,6 +724,7 @@ Represents a partially ordered set satisfying the following laws:

612724(>) :: forall a. (Ord a) => a -> a -> Boolean

613725```

614726

727+Test whether one value is _strictly greater than_ another.

615728

616729#### `(<=)`

617730

@@ -619,6 +732,7 @@ Represents a partially ordered set satisfying the following laws:

619732(<=) :: forall a. (Ord a) => a -> a -> Boolean

620733```

621734

735+Test whether one value is _non-strictly less than_ another.

622736

623737#### `(>=)`

624738

@@ -626,6 +740,7 @@ Represents a partially ordered set satisfying the following laws:

626740(>=) :: forall a. (Ord a) => a -> a -> Boolean

627741```

628742

743+Test whether one value is _non-strictly greater than_ another.

629744

630745#### `ordUnit`

631746

@@ -675,6 +790,7 @@ class Bits b where

675790 complement :: b -> b

676791```

677792

793+The `Bits` type class identifies types which support bitwise operations.

678794

679795#### `bitsNumber`

680796

@@ -692,6 +808,10 @@ class BoolLike b where

692808 not :: b -> b

693809```

694810

811+The `BoolLike` type class identifies types which support Boolean operations.

812+

813+`BoolLike` instances are required to satisfy the laws of a _Boolean algebra_.

814+

695815

696816#### `boolLikeBoolean`

697817

@@ -707,6 +827,13 @@ class Semigroup a where

707827 (<>) :: a -> a -> a

708828```

709829

830+The `Semigroup` type class identifies an associative operation on a type.

831+

832+`Semigroup` instances are required to satisfy the following law:

833+

834+- Associativity: `forall x y z. (x <> y) <> z = x <> (y <> z)`

835+

836+For example, the `String` type is an instance of `Semigroup`, where `(<>)` is defined to be string concatenation.

710837

711838#### `semigroupUnit`

712839

@@ -735,6 +862,7 @@ instance semigroupArr :: (Semigroup s') => Semigroup (s -> s')

735862(++) :: forall s. (Semigroup s) => s -> s -> s

736863```

737864

865+`(++)` is an alias for `(<>)`.

738866

739867

740868## Module Data.Function

prelude/images/Prelude.png

Binary file not shown.

prelude/prelude.purs+148−20

@@ -79,12 +79,15 @@ module Prelude

7979 -- |

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

8181 -- |

82+ -- | One example of a `Semigroupoid` is the function type constructor `(->)`, with `(<<<)` defined

83+ -- | as function composition.

8284 class Semigroupoid a where

8385 (<<<) :: forall b c d. a c d -> a b c -> a b d

8486

8587 instance semigroupoidArr :: Semigroupoid (->) where

8688 (<<<) f g x = f (g x)

8789

90+ -- | Forwards composition, or `(<<<)` with its arguments reversed.

8891 (>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

8992 (>>>) f g = g <<< f

9093

@@ -143,12 +146,11 @@ module Prelude

143146

144147 infixr 6 :

145148

146− -- | Attaches an element to the front of a list.

149+ -- | Attaches an element to the front of an array, creating a new array.

147150 -- |

148151 -- | ```purescript

149152 -- | 1 : [2, 3, 4] = [1, 2, 3, 4]

150153 -- | ```

151− -- |

152154 (:) :: forall a. a -> [a] -> [a]

153155 (:) = cons

154156

@@ -161,6 +163,10 @@ module Prelude

161163 }

162164 """ :: forall a. a -> [a] -> [a]

163165

166+ -- | The `Show` type class represents those types which can be converted into a human-readable `String` representation.

167+ -- |

168+ -- | While not required, it is recommended that for any expression `x`, the string `show x` be executable PureScript code

169+ -- | which evaluates to the same value as the expression `x`.

164170 class Show a where

165171 show :: a -> String

166172

@@ -210,10 +216,12 @@ module Prelude

210216 infixl 4 <$>

211217 infixl 1 <#>

212218

213− -- | A `Functor` is intuitively a type which can be mapped over, and more formally a mapping

214− -- | between [`Category`](#category)s that preserves structure.

219+ -- | A `Functor` is a type constructor which supports a mapping operation `(<$>)`.

220+ -- |

221+ -- | `(<$>)` can be used to turn functions `a -> b` into functions `f a -> f b` whose argument and return

222+ -- | types use the type constructor `f` to represent some computational context.

215223 -- |

216− -- | `Functor`s should obey the following rules.

224+ -- | `Functor` instances should satisfy the following laws:

217225 -- |

218226 -- | - Identity: `(<$>) id = id`

219227 -- | - Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

@@ -221,28 +229,58 @@ module Prelude

221229 class Functor f where

222230 (<$>) :: forall a b. (a -> b) -> f a -> f b

223231

232+ -- | `(<#>)` is `(<$>)` with its arguments flipped. For example:

233+ -- |

234+ -- | ```purescript

235+ -- | [1, 2, 3] <#> \n -> n * n

236+ -- | ```

224237 (<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

225238 (<#>) fa f = f <$> fa

226239

240+ -- | The `void` function is used to ignore the type wrapped by a [`Functor`](#functor), replacing it with `Unit` and

241+ -- | keeping only the type information provided by the type constructor itself.

242+ -- |

243+ -- | `void` is often useful when using `do` notation to change the return type of a monadic computation:

244+ -- |

245+ -- | ```purescript

246+ -- | main = forE 1 10 \n -> void do

247+ -- | print n

248+ -- | print (n * n)

249+ -- | ```

227250 void :: forall f a. (Functor f) => f a -> f Unit

228251 void fa = const unit <$> fa

229252

230253 infixl 4 <*>

231254

232− -- | `Apply`s are intuitively [`Applicative`](#applicative)s less `pure`, and more formally a

233− -- | strong lax semi-monoidal endofunctor.

255+ -- | The `Apply` class provides the `(<*>)` which is used to apply a function to an argument under a type constructor.

256+ -- |

257+ -- | `Apply` can be used to lift functions of two or more arguments to work on values wrapped with the type constructor `f`.

258+ -- | It might also be understood in terms of the `lift2` function:

259+ -- |

260+ -- | ```purescript

261+ -- | lift2 :: forall f a b c. (Apply f) => (a -> b -> c) -> f a -> f b -> f c

262+ -- | lift2 f a b = f <$> a <*> b

263+ -- | ```

264+ -- |

265+ -- | `(<*>)` is recovered from `lift2` as `lift2 ($)`. That is, `(<*>)` lifts the function application operator `($)` to arguments

266+ -- | wrapped with the type constructor `f`.

234267 -- |

235− -- | `Apply`s should obey the following rule.

268+ -- | `Apply` instances should satisfy the following law:

236269 -- |

237270 -- | - Associative Composition: `(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

238271 -- |

272+ -- | Formally, `Apply` represents a strong lax semi-monoidal endofunctor.

239273 class (Functor f) <= Apply f where

240274 (<*>) :: forall a b. f (a -> b) -> f a -> f b

241275

242− -- | `Applicative`s are [`Functor`](#functor)s which can be "applied" by sequencing composition

243− -- | (`<*>`) or embedding pure expressions (`pure`).

276+ -- | The `Applicative` type class extends the [`Apply`](#apply) type class with a `pure` function, which can be used to

277+ -- | create values of type `f a` from values of type `a`.

278+ -- |

279+ -- | Where [`Apply`](#apply) provides the ability to lift functions of two or more arguments to functions whose arguments are wrapped using `f`,

280+ -- | and [`Functor`](#functor) provides the ability to lift functions of one argument, `pure` can be seen as the function which lifts functions of

281+ -- | _zero_ arguments. That is, `Applicative` functors support a lifting operation for any number of function arguments.

244282 -- |

245− -- | `Applicative`s should obey the following rules.

283+ -- | `Applicative` instances should satisfy the following laws:

246284 -- |

247285 -- | - Identity: `(pure id) <*> v = v`

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

@@ -252,38 +290,92 @@ module Prelude

252290 class (Apply f) <= Applicative f where

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

254292

293+ -- | `liftA1` provides a default implementation of `(<$>)` for any [`Applicative`](#applicative) functor,

294+ -- | without using `(<$>)` as provided by the [`Functor`](#functor)-[`Applicative`](#applicative) superclass relationship.

295+ -- |

296+ -- | `liftA1` can therefore be used to write [`Functor`](#functor) instances as follows:

297+ -- |

298+ -- | ```purescript

299+ -- | instance functorF :: Functor F where

300+ -- | (<$>) = liftA1

301+ -- | ```

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

256303 liftA1 f a = pure f <*> a

257304

258305 infixl 1 >>=

259306

260− -- | A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially composes actions.

261− -- |

262− -- | `Bind`s should obey the following rule.

307+ -- | The `Bind` type class extends the [`Apply`](#apply) type class with a "bind" operation `(>>=)` which composes computations

308+ -- | in sequence, using the return value of one computation to determine the next computation.

309+ -- |

310+ -- | The `>>=` operator can also be expressed using `do` notation, as follows:

311+ -- |

312+ -- | ```purescript

313+ -- | x >>= f = do y <- x

314+ -- | f y

315+ -- | ```

316+ -- |

317+ -- | where the function argument of `f` is given the name `y`.

318+ -- |

319+ -- | `Bind` instances should satisfy the following law:

263320 -- |

264321 -- | - Associativity: `forall f g x. (x >>= f) >>= g = x >>= (\k => f k >>= g)`

265322 -- |

323+ -- | Or, expressed using `do` notation:

324+ -- |

325+ -- | - Associativity: `do { z <- do { y <- x ; f y } ; g z } = do { k <- x ; do { y <- f k ; g y } }`

326+ -- |

327+ -- | Associativity tells us that we can regroup operations which use do-notation, so that we can unambiguously write, for example:

328+ -- |

329+ -- | ```purescript

330+ -- | do x <- m1

331+ -- | y <- m2 x

332+ -- | m3 x y

333+ -- | ```

266334 class (Apply m) <= Bind m where

267335 (>>=) :: forall a b. m a -> (a -> m b) -> m b

268336

269− -- | `Monad` is a class which can be intuitively thought of as an abstract datatype of actions or

270− -- | more formally though of as a monoid in the category of endofunctors.

337+ -- | The `Monad` type class combines the operations of the `Bind` and `Applicative` type classes. Therefore, `Monad` instances

338+ -- | represent type constructors which support sequential composition, and also lifting of functions of arbitrary arity.

271339 -- |

272− -- | `Monad`s should obey the following rules.

340+ -- | `Monad` instances should satisfy the following laws:

273341 -- |

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

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

276344 -- |

345+ -- | Or, expressed using `do` notation:

346+ -- |

347+ -- | - Left Identity: `do { y <- pure x ; f y } = f x`

348+ -- | - Right Identity: `do { y <- x ; pure y } = x`

349+ -- |

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

278351

352+ -- | `return` is an alias for `pure`.

279353 return :: forall m a. (Monad m) => a -> m a

280354 return = pure

281355

356+ -- | `liftM1` provides a default implementation of `(<$>)` for any [`Monad`](#monad),

357+ -- | without using `(<$>)` as provided by the [`Functor`](#functor)-[`Monad`](#monad) superclass relationship.

358+ -- |

359+ -- | `liftM1` can therefore be used to write [`Functor`](#functor) instances as follows:

360+ -- |

361+ -- | ```purescript

362+ -- | instance functorF :: Functor F where

363+ -- | (<$>) = liftM1

364+ -- | ```

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

283366 liftM1 f a = do

284367 a' <- a

285368 return (f a')

286369

370+ -- | `ap` provides a default implementation of `(<*>)` for any [`Monad`](#monad),

371+ -- | without using `(<*>)` as provided by the [`Apply`](#apply)-[`Monad`](#monad) superclass relationship.

372+ -- |

373+ -- | `ap` can therefore be used to write [`Apply`](#apply) instances as follows:

374+ -- |

375+ -- | ```purescript

376+ -- | instance applyF :: Apply F where

377+ -- | (<*>) = ap

378+ -- | ```

287379 ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

288380 ap f a = do

289381 f' <- f

@@ -417,15 +509,29 @@ module Prelude

417509

418510 instance numNumber :: Num Number

419511

512+ -- | The `Unit` type has a single inhabitant, called `unit`. It represents values with no computational content.

513+ -- |

514+ -- | `Unit` is often used, wrapped in a monadic type constructor, as the return type of a computation where only

515+ -- | the _effects_ are important.

420516 newtype Unit = Unit {}

421517

518+ -- | `unit` is the sole inhabitant of the `Unit` type.

422519 unit :: Unit

423520 unit = Unit {}

424521

425522 infix 4 ==

426523 infix 4 /=

427524

428− -- | Class for types that have an equality comparison.

525+ -- | The `Eq` type class represents types which support decidable equality.

526+ -- |

527+ -- | `Eq` instances should satisfy the following laws:

528+ -- |

529+ -- | - Reflexivity: `forall x. x == x = true`

530+ -- | - Symmetry: `forall x y. x == y = y == x`

531+ -- | - Transitivity: if `x == y` and `y == z` then `x == z`

532+ -- | - Negation: `forall x y. x /= y = not (x == y)`

533+ -- |

534+ -- | `(/=)` may be implemented in terms of `(==)`, but it might give a performance improvement to implement it separately.

429535 class Eq a where

430536 (==) :: a -> a -> Boolean

431537 (/=) :: a -> a -> Boolean

@@ -483,6 +589,11 @@ module Prelude

483589 (==) xs ys = eqArrayImpl (==) xs ys

484590 (/=) xs ys = not (xs == ys)

485591

592+ -- | The `Ordering` data type represents the three possible outcomes of comparing two values:

593+ -- |

594+ -- | `LT` - The first value is _less than_ the second.

595+ -- | `GT` - The first value is _greater than_ the second.

596+ -- | `EQ` - The first value is _equal to_ or _incomparable to_ the second.

486597 data Ordering = LT | GT | EQ

487598

488599 instance eqOrdering :: Eq Ordering where

@@ -502,9 +613,9 @@ module Prelude

502613 (<>) GT _ = GT

503614 (<>) EQ y = y

504615

505− -- | Class for types that have ordered comparisons.

616+ -- | The `Ord` type class represents types which support comparisons.

506617 -- |

507− -- | Represents a partially ordered set satisfying the following laws:

618+ -- | `Ord` instances should satisfy the laws of _partially orderings_:

508619 -- |

509620 -- | - Reflexivity: `a <= a`

510621 -- | - Antisymmetry: if `a <= b` and `b <= a` then `a = b`

@@ -515,6 +626,7 @@ module Prelude

515626

516627 infixl 4 <

517628

629+ -- | Test whether one value is _strictly less than_ another.

518630 (<) :: forall a. (Ord a) => a -> a -> Boolean

519631 (<) a1 a2 = case a1 `compare` a2 of

520632 LT -> true

@@ -522,6 +634,7 @@ module Prelude

522634

523635 infixl 4 >

524636

637+ -- | Test whether one value is _strictly greater than_ another.

525638 (>) :: forall a. (Ord a) => a -> a -> Boolean

526639 (>) a1 a2 = case a1 `compare` a2 of

527640 GT -> true

@@ -529,6 +642,7 @@ module Prelude

529642

530643 infixl 4 <=

531644

645+ -- | Test whether one value is _non-strictly less than_ another.

532646 (<=) :: forall a. (Ord a) => a -> a -> Boolean

533647 (<=) a1 a2 = case a1 `compare` a2 of

534648 GT -> false

@@ -536,6 +650,7 @@ module Prelude

536650

537651 infixl 4 >=

538652

653+ -- | Test whether one value is _non-strictly greater than_ another.

539654 (>=) :: forall a. (Ord a) => a -> a -> Boolean

540655 (>=) a1 a2 = case a1 `compare` a2 of

541656 LT -> false

@@ -586,6 +701,7 @@ module Prelude

586701 infixl 10 .|.

587702 infixl 10 .^.

588703

704+ -- | The `Bits` type class identifies types which support bitwise operations.

589705 class Bits b where

590706 (.&.) :: b -> b -> b

591707 (.|.) :: b -> b -> b

@@ -668,6 +784,10 @@ module Prelude

668784 infixr 2 ||

669785 infixr 3 &&

670786

787+ -- | The `BoolLike` type class identifies types which support Boolean operations.

788+ -- |

789+ -- | `BoolLike` instances are required to satisfy the laws of a _Boolean algebra_.

790+ -- |

671791 class BoolLike b where

672792 (&&) :: b -> b -> b

673793 (||) :: b -> b -> b

@@ -705,6 +825,13 @@ module Prelude

705825

706826 infixr 5 <>

707827

828+ -- | The `Semigroup` type class identifies an associative operation on a type.

829+ -- |

830+ -- | `Semigroup` instances are required to satisfy the following law:

831+ -- |

832+ -- | - Associativity: `forall x y z. (x <> y) <> z = x <> (y <> z)`

833+ -- |

834+ -- | For example, the `String` type is an instance of `Semigroup`, where `(<>)` is defined to be string concatenation.

708835 class Semigroup a where

709836 (<>) :: a -> a -> a

710837

@@ -728,6 +855,7 @@ module Prelude

728855

729856 infixr 5 ++

730857

858+ -- | `(++)` is an alias for `(<>)`.

731859 (++) :: forall s. (Semigroup s) => s -> s -> s

732860 (++) = (<>)

733861