1371017 · rowtype-yoga/purescript-native

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

on golang help sign in

Prelude documentation

1371017Phil Freeman12 years ago

prelude/README.md+149−21

compare with golang

unifiedsplit

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

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

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

76+as function composition.

76#### `semigroupoidArr`

78#### `semigroupoidArr`

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

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

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

87```

89```

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

90#### `Category`

93#### `Category`

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

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

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

161```

164```

162

165

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

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

164

167

165```purescript

168```purescript

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

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

167```

170```

168

171

169−

170#### `cons`

172#### `cons`

171

173

172``` purescript

174``` purescript

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

181 show :: a -> String

183 show :: a -> String

182```

184```

183

185

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`.

184

190

185#### `showUnit`

191#### `showUnit`

186

192

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

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

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

225```

231```

226

232

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

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

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

229

234

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+

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

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

231

239

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

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

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

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

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

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

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

240```

248```

241

249

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

251+

252+```purescript

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

254+```

242

255

243#### `void`

256#### `void`

244

257

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

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

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

247```

260```

248

261

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+```

249

272

250#### `Apply`

273#### `Apply`

251

274

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

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

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

255```

278```

256

279

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

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

258−strong lax semi-monoidal endofunctor.

259

281

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+

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

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

261

294

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

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

263

296

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

264

298

265#### `Applicative`

299#### `Applicative`

266

300

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

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

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

270```

304```

271

305

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

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

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

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.

274

312

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

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

276

314

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

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

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

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

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

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

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

287```

325```

288

326

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+```

289

336

290#### `Bind`

337#### `Bind`

291

338

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

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

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

295```

342```

296

343

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`.

298

355

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

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

300

357

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

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

302

359

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+```

303

371

304#### `Monad`

372#### `Monad`

305

373

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

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

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

308```

376```

309

377

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

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

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

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

312

380

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

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

314

382

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

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

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

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

317

385

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+

318

391

319#### `return`

392#### `return`

320

393

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

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

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

323```

396```

324

397

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

325

399

326#### `liftM1`

400#### `liftM1`

327

401

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

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

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

330```

404```

331

405

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+```

332

415

333#### `ap`

416#### `ap`

334

417

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

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

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

337```

420```

338

421

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+```

339

431

340#### `functorArr`

432#### `functorArr`

341

433

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

384

476

385Addition and multiplication, satisfying the following laws:

477Addition and multiplication, satisfying the following laws:

386

478

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

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

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

480+- `a` is a monoid under multiplication

389- multiplication distributes over addition

481- multiplication distributes over addition

390- multiplication by `zero` annihilates `a`

482- multiplication by `zero` annihilates `a`

391

483

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

485 = Unit { }

577 = Unit { }

486```

578```

487

579

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.

488

584

489#### `unit`

585#### `unit`

490

586

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

492unit :: Unit

588unit :: Unit

493```

589```

494

590

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

495

592

496#### `Eq`

593#### `Eq`

497

594

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

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

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

502```

599```

503

600

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.

505

611

506#### `refEq`

612#### `refEq`

507

613

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

561 | EQ

667 | EQ

562```

668```

563

669

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.

564

675

565#### `eqOrdering`

676#### `eqOrdering`

566

677

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

590 compare :: a -> a -> Ordering

701 compare :: a -> a -> Ordering

591```

702```

592

703

593−Class for types that have ordered comparisons.

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

594

705

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

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

596

707

597- Reflexivity: `a <= a`

708- Reflexivity: `a <= a`

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

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

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

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

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

606```

717```

607

718

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

608

720

609#### `(>)`

721#### `(>)`

610

722

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

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

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

613```

725```

614

726

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

615

728

616#### `(<=)`

729#### `(<=)`

617

730

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

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

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

620```

733```

621

734

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

622

736

623#### `(>=)`

737#### `(>=)`

624

738

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

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

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

627```

741```

628

742

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

629

744

630#### `ordUnit`

745#### `ordUnit`

631

746

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

675 complement :: b -> b

790 complement :: b -> b

676```

791```

677

792

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

678

794

679#### `bitsNumber`

795#### `bitsNumber`

680

796

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

692 not :: b -> b

808 not :: b -> b

693```

809```

694

810

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+

695

815

696#### `boolLikeBoolean`

816#### `boolLikeBoolean`

697

817

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

707 (<>) :: a -> a -> a

827 (<>) :: a -> a -> a

708```

828```

709

829

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.

710

837

711#### `semigroupUnit`

838#### `semigroupUnit`

712

839

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

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

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

736```

863```

737

864

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

738

866

739

867

740## Module Data.Function

868## Module Data.Function

prelude/images/Prelude.png

Binary file not shown.

prelude/prelude.purs+148−20

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

79 -- |

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

81 -- |

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

83+ -- | as function composition.

82 class Semigroupoid a where

84 class Semigroupoid a where

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

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

85 instance semigroupoidArr :: Semigroupoid (->) where

87 instance semigroupoidArr :: Semigroupoid (->) where

86 (<<<) f g x = f (g x)

88 (<<<) f g x = f (g x)

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

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

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

89 (>>>) f g = g <<< f

92 (>>>) f g = g <<< f

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

143

146

144 infixr 6 :

147 infixr 6 :

145

148

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

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

147 -- |

150 -- |

148 -- | ```purescript

151 -- | ```purescript

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

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

150 -- | ```

153 -- | ```

151− -- |

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

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

153 (:) = cons

155 (:) = cons

154

156

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

161 }

163 }

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

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

163

165

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`.

164 class Show a where

170 class Show a where

165 show :: a -> String

171 show :: a -> String

166

172

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

210 infixl 4 <$>

216 infixl 4 <$>

211 infixl 1 <#>

217 infixl 1 <#>

212

218

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

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

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

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.

215 -- |

223 -- |

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

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

217 -- |

225 -- |

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

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

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

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

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

221 class Functor f where

229 class Functor f where

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

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

223

231

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

233+ -- |

234+ -- | ```purescript

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

236+ -- | ```

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

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

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

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

226

239

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+ -- | ```

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

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

228 void fa = const unit <$> fa

251 void fa = const unit <$> fa

229

252

230 infixl 4 <*>

253 infixl 4 <*>

231

254

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

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

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

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`.

234 -- |

267 -- |

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

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

236 -- |

269 -- |

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

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

238 -- |

271 -- |

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

239 class (Functor f) <= Apply f where

273 class (Functor f) <= Apply f where

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

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

241

275

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

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

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

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.

244 -- |

282 -- |

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

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

246 -- |

284 -- |

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

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

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

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

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

252 class (Apply f) <= Applicative f where

290 class (Apply f) <= Applicative f where

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

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

254

292

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+ -- | ```

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

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

256 liftA1 f a = pure f <*> a

303 liftA1 f a = pure f <*> a

257

304

258 infixl 1 >>=

305 infixl 1 >>=

259

306

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

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`.

261− -- |

318+ -- |

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

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

263 -- |

320 -- |

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

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

265 -- |

322 -- |

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+ -- | ```

266 class (Apply m) <= Bind m where

334 class (Apply m) <= Bind m where

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

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

268

336

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

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

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

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

271 -- |

339 -- |

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

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

273 -- |

341 -- |

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

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

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

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

276 -- |

344 -- |

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+ -- |

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

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

278

351

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

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

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

280 return = pure

354 return = pure

281

355

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+ -- | ```

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

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

283 liftM1 f a = do

366 liftM1 f a = do

284 a' <- a

367 a' <- a

285 return (f a')

368 return (f a')

286

369

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+ -- | ```

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

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

288 ap f a = do

380 ap f a = do

289 f' <- f

381 f' <- f

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

417

509

418 instance numNumber :: Num Number

510 instance numNumber :: Num Number

419

511

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.

420 newtype Unit = Unit {}

516 newtype Unit = Unit {}

421

517

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

422 unit :: Unit

519 unit :: Unit

423 unit = Unit {}

520 unit = Unit {}

424

521

425 infix 4 ==

522 infix 4 ==

426 infix 4 /=

523 infix 4 /=

427

524

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.

429 class Eq a where

535 class Eq a where

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

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

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

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

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

483 (==) xs ys = eqArrayImpl (==) xs ys

589 (==) xs ys = eqArrayImpl (==) xs ys

484 (/=) xs ys = not (xs == ys)

590 (/=) xs ys = not (xs == ys)

485

591

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.

486 data Ordering = LT | GT | EQ

597 data Ordering = LT | GT | EQ

487

598

488 instance eqOrdering :: Eq Ordering where

599 instance eqOrdering :: Eq Ordering where

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

502 (<>) GT _ = GT

613 (<>) GT _ = GT

503 (<>) EQ y = y

614 (<>) EQ y = y

504

615

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

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

506 -- |

617 -- |

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

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

508 -- |

619 -- |

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

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

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

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

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

515

626

516 infixl 4 <

627 infixl 4 <

517

628

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

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

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

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

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

520 LT -> true

632 LT -> true

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

522

634

523 infixl 4 >

635 infixl 4 >

524

636

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

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

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

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

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

527 GT -> true

640 GT -> true

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

529

642

530 infixl 4 <=

643 infixl 4 <=

531

644

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

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

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

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

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

534 GT -> false

648 GT -> false

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

536

650

537 infixl 4 >=

651 infixl 4 >=

538

652

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

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

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

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

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

541 LT -> false

656 LT -> false

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

586 infixl 10 .|.

701 infixl 10 .|.

587 infixl 10 .^.

702 infixl 10 .^.

588

703

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

589 class Bits b where

705 class Bits b where

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

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

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

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

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

668 infixr 2 ||

784 infixr 2 ||

669 infixr 3 &&

785 infixr 3 &&

670

786

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+ -- |

671 class BoolLike b where

791 class BoolLike b where

672 (&&) :: b -> b -> b

792 (&&) :: b -> b -> b

673 (||) :: b -> b -> b

793 (||) :: b -> b -> b

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

705

825

706 infixr 5 <>

826 infixr 5 <>

707

827

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.

708 class Semigroup a where

835 class Semigroup a where

709 (<>) :: a -> a -> a

836 (<>) :: a -> a -> a

710

837

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

728

855

729 infixr 5 ++

856 infixr 5 ++

730

857

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

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

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

732 (++) = (<>)

860 (++) = (<>)

733

861