diff --git a/README.md b/README.md
index 80951d01..80303c18 100644
--- a/README.md
+++ b/README.md
@@ -100,10 +100,11 @@ to the *methods* provided by Sanctuary's types. In `x.map(y)`, for example,
the `map` method takes an implicit argument `x` in addition to the explicit
argument `y`. The type of the value upon which a method is invoked appears
at the beginning of the signature, separated from the arguments and return
-value by a squiggly arrow (`~>`). The type of the `map` method of the Maybe
-type is written `Maybe a ~> (a -> b) -> Maybe b`. One could read this as:
+value by a squiggly arrow (`~>`). The type of the `fantasy-land/map` method
+of the Maybe type is written `Maybe a ~> (a -> b) -> Maybe b`. One could
+read this as:
-_When the `map` method is invoked on a value of type `Maybe a`
+_When the `fantasy-land/map` method is invoked on a value of type `Maybe a`
(for any type `a`) with an argument of type `a -> b` (for any type `b`),
it returns a value of type `Maybe b`._
@@ -118,23 +119,6 @@ Functor type class. Type-class constraints appear at the beginning of a
type signature, separated from the rest of the signature by a fat arrow
(`=>`).
-### Accessible pseudotype
-
-What is the type of values which support property access? In other words,
-what is the type of which every value except `null` and `undefined` is a
-member? Object is close, but `Object.create(null)` produces a value which
-supports property access but which is not a member of the Object type.
-
-Sanctuary uses the Accessible pseudotype to represent the set of values
-which support property access.
-
-### Integer pseudotype
-
-The Integer pseudotype represents integers in the range (-2^53 .. 2^53).
-It is a pseudotype because each Integer is represented by a Number value.
-Sanctuary's run-time type checking asserts that a valid Number value is
-provided wherever an Integer value is required.
-
### Type representatives
What is the type of `Number`? One answer is `a -> Number`, since it's a
@@ -168,7 +152,7 @@ S.add(2, true);
//
// The value at position 1 is not a member of ‘FiniteNumber’.
//
-// See https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.0#FiniteNumber for information about the sanctuary-def/FiniteNumber type.
+// See https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#FiniteNumber for information about the sanctuary-def/FiniteNumber type.
```
Compare this to the behaviour of Ramda's unchecked equivalent:
@@ -195,7 +179,7 @@ const S = create({checkTypes, env});
## API
-
+
Takes an options record and returns a Sanctuary module. `checkTypes`
specifies whether to enable type checking. The module's polymorphic
@@ -246,7 +230,7 @@ S.map(S.sub(1), Identity(43));
See also [`env`](#env).
-
+
The default environment, which may be used as is or as the basis of a
custom environment in conjunction with [`create`](#create).
@@ -273,7 +257,7 @@ The following are all equivalent (`_` represents the placeholder):
- `f(_, _, z)(x, y)`
- `f(_, _, z)(_, y)(x)`
-
+
The special [placeholder](#placeholder) value.
@@ -287,7 +271,7 @@ The special [placeholder](#placeholder) value.
### Classify
-
+
Returns the result of parsing the [type identifier][] of the given value.
@@ -299,11 +283,11 @@ Returns the result of parsing the [type identifier][] of the given value.
{namespace: Nothing, name: 'Array', version: 0}
```
-
+
-Takes a [type representative](#type-representatives) and a value of
-any type and returns `true` if the given value is of the specified
-type; `false` otherwise. Subtyping is not respected.
+Takes a [type representative](#type-representatives) and a value of any
+type and returns `true` [iff][] the given value is of the specified type.
+Subtyping is not respected.
```javascript
> S.is(Number, 42)
@@ -318,7 +302,7 @@ false
### Showable
-
+
Alias of [`Z.toString`][].
@@ -340,7 +324,7 @@ Alias of [`Z.toString`][].
Sanctuary is compatible with the [Fantasy Land][] specification.
-
+
Curried version of [`Z.equals`][] which requires two arguments of the
same type.
@@ -363,9 +347,10 @@ true
false
```
-
+
-Flipped version of [`Z.lt`][] intended for partial application.
+Returns `true` [iff][] the *second* argument is less than the first
+according to [`Z.lt`][]. The arguments must be provided one at a time.
See also [`lt_`](#lt_).
@@ -374,9 +359,10 @@ See also [`lt_`](#lt_).
[1, 2]
```
-
+
-Curried version of [`Z.lt`][].
+Returns `true` [iff][] the first argument is less than the second
+according to [`Z.lt`][].
See also [`lt`](#lt).
@@ -391,9 +377,11 @@ true
false
```
-
+
-Flipped version of [`Z.lte`][] intended for partial application.
+Returns `true` [iff][] the *second* argument is less than or equal to
+the first according to [`Z.lte`][]. The arguments must be provided one
+at a time.
See also [`lte_`](#lte_).
@@ -402,9 +390,10 @@ See also [`lte_`](#lte_).
[1, 2, 3]
```
-
+
-Curried version of [`Z.lte`][].
+Returns `true` [iff][] the first argument is less than or equal to the
+second according to [`Z.lte`][].
See also [`lte`](#lte).
@@ -419,9 +408,10 @@ true
false
```
-
+
-Flipped version of [`Z.gt`][] intended for partial application.
+Returns `true` [iff][] the *second* argument is greater than the first
+according to [`Z.gt`][]. The arguments must be provided one at a time.
See also [`gt_`](#gt_).
@@ -430,9 +420,10 @@ See also [`gt_`](#gt_).
[4, 5]
```
-
+
-Curried version of [`Z.gt`][].
+Returns `true` [iff][] the first argument is greater than the second
+according to [`Z.gt`][].
See also [`gt`](#gt).
@@ -447,9 +438,11 @@ false
true
```
-
+
-Flipped version of [`Z.gte`][] intended for partial application.
+Returns `true` [iff][] the *second* argument is greater than or equal
+to the first according to [`Z.gte`][]. The arguments must be provided
+one at a time.
See also [`gte_`](#gte_).
@@ -458,9 +451,10 @@ See also [`gte_`](#gte_).
[3, 4, 5]
```
-
+
-Curried version of [`Z.gte`][].
+Returns `true` [iff][] the first argument is greater than or equal to
+the second according to [`Z.gte`][].
See also [`gte`](#gte).
@@ -475,7 +469,7 @@ false
true
```
-
+
Returns the smaller of its two arguments (according to [`Z.lte`][]).
@@ -492,7 +486,7 @@ new Date('1999-12-31')
'10'
```
-
+
Returns the larger of its two arguments (according to [`Z.lte`][]).
@@ -509,7 +503,7 @@ new Date('2000-01-01')
'2'
```
-
+
[Type-safe][sanctuary-def] version of [`Z.id`][].
@@ -518,7 +512,7 @@ new Date('2000-01-01')
42
```
-
+
Curried version of [`Z.concat`][].
@@ -534,9 +528,12 @@ Curried version of [`Z.concat`][].
> S.concat(S.Just([1, 2, 3]), S.Just([4, 5, 6]))
Just([1, 2, 3, 4, 5, 6])
+
+> S.concat(Sum(18), Sum(24))
+Sum(42)
```
-
+
[Type-safe][sanctuary-def] version of [`Z.empty`][].
@@ -549,9 +546,21 @@ Just([1, 2, 3, 4, 5, 6])
> S.empty(Object)
{}
+
+> S.empty(Sum)
+Sum(0)
+```
+
+
+
+[Type-safe][sanctuary-def] version of [`Z.invert`][].
+
+```javascript
+> S.invert(Sum(5))
+Sum(-5)
```
-
+
Curried version of [`Z.map`][].
@@ -584,7 +593,7 @@ from combinatory logic (i.e. [`compose`](#compose)):
10
```
-
+
Curried version of [`Z.bimap`][].
@@ -596,7 +605,7 @@ Left('FOO')
Right(8)
```
-
+
Curried version of [`Z.promap`][].
@@ -605,7 +614,7 @@ Curried version of [`Z.promap`][].
11
```
-
+
Curried version of [`Z.alt`][].
@@ -623,7 +632,7 @@ Right(1)
Right(2)
```
-
+
[Type-safe][sanctuary-def] version of [`Z.zero`][].
@@ -638,7 +647,7 @@ Right(2)
Nothing
```
-
+
Takes a curried binary function, an initial value, and a [Foldable][],
and applies the function to the initial value and the Foldable's first
@@ -648,8 +657,6 @@ until each of the Foldable's values has been used. Returns the initial
value if the Foldable is empty; the result of the final application
otherwise.
-See also [`reduce_`](#reduce_).
-
```javascript
> S.reduce(S.add, 0, [1, 2, 3, 4, 5])
15
@@ -658,11 +665,7 @@ See also [`reduce_`](#reduce_).
[5, 4, 3, 2, 1]
```
-
-
-Variant of [`reduce`](#reduce) which takes an uncurried binary function.
-
-
+
Curried version of [`Z.traverse`][].
@@ -686,9 +689,10 @@ Just({a: 10, b: 11, c: 12})
Nothing
```
-
+
-Curried version of [`Z.sequence`][].
+Curried version of [`Z.sequence`][]. Inverts the given `t (f a)`
+to produce an `f (t a)`.
```javascript
> S.sequence(Array, S.Just([1, 2, 3]))
@@ -707,7 +711,7 @@ Just({a: 1, b: 2, c: 3})
Nothing
```
-
+
Curried version of [`Z.ap`][].
@@ -737,7 +741,7 @@ from combinatory logic:
'Hask'
```
-
+
Promotes a curried binary function to a function which operates on two
[Apply][]s.
@@ -756,7 +760,7 @@ Just(true)
Just(false)
```
-
+
Promotes a curried ternary function to a function which operates on three
[Apply][]s.
@@ -769,7 +773,7 @@ Just(6)
Nothing
```
-
+
Curried version of [`Z.apFirst`][]. Combines two effectful actions,
keeping only the result of the first. Equivalent to Haskell's `(<*)`
@@ -785,7 +789,7 @@ See also [`apSecond`](#apSecond).
Just(1)
```
-
+
Curried version of [`Z.apSecond`][]. Combines two effectful actions,
keeping only the result of the second. Equivalent to Haskell's `(*>)`
@@ -801,7 +805,7 @@ See also [`apFirst`](#apFirst).
Just(2)
```
-
+
Curried version of [`Z.of`][].
@@ -819,7 +823,7 @@ Just(42)
Right(42)
```
-
+
Curried version of [`Z.chain`][].
@@ -837,7 +841,7 @@ Just(123)
Nothing
```
-
+
[Type-safe][sanctuary-def] version of [`Z.join`][].
Removes one level of nesting from a nested monadic structure.
@@ -865,7 +869,7 @@ from combinatory logic:
'abcabc'
```
-
+
Performs a [`chain`](#chain)-like computation with constant stack usage.
Similar to [`Z.chainRec`][], but curried and more convenient due to the
@@ -879,7 +883,7 @@ use of the Either type to indicate completion (via a Right).
['oo!', 'oo?', 'on!', 'on?', 'no!', 'no?', 'nn!', 'nn?']
```
-
+
Curried version of [`Z.extend`][].
@@ -888,11 +892,11 @@ Curried version of [`Z.extend`][].
['xyz', 'yz', 'z']
```
-
+
[Type-safe][sanctuary-def] version of [`Z.extract`][].
-
+
[Type-safe][sanctuary-def] version of [`Z.contramap`][].
@@ -901,9 +905,10 @@ Curried version of [`Z.extend`][].
3
```
-
+
-Curried version of [`Z.filter`][].
+Curried version of [`Z.filter`][]. Filters its second argument in
+accordance with the given predicate.
See also [`filterM`](#filterM).
@@ -912,9 +917,10 @@ See also [`filterM`](#filterM).
[1, 3, 5]
```
-
+
-Curried version of [`Z.filterM`][].
+Curried version of [`Z.filterM`][]. Filters its second argument in
+accordance with the given predicate.
See also [`filter`](#filter).
@@ -929,7 +935,7 @@ Just(9)
Nothing
```
-
+
Discards the first inner value which does not satisfy the predicate, and
all subsequent inner values.
@@ -942,7 +948,7 @@ all subsequent inner values.
[]
```
-
+
Retains the first inner value which does not satisfy the predicate, and
all subsequent inner values.
@@ -957,7 +963,7 @@ all subsequent inner values.
### Combinator
-
+
The I combinator. Returns its argument. Equivalent to Haskell's `id`
function.
@@ -967,7 +973,7 @@ function.
'foo'
```
-
+
The K combinator. Takes two values and returns the first. Equivalent to
Haskell's `const` function.
@@ -980,7 +986,7 @@ Haskell's `const` function.
[42, 42, 42, 42, 42]
```
-
+
The A combinator. Takes a function and a value, and returns the result
of applying the function to the value. Equivalent to Haskell's `($)`
@@ -994,7 +1000,7 @@ function.
[101, 10]
```
-
+
The T ([thrush][]) combinator. Takes a value and a function, and returns
the result of applying the function to the value. Equivalent to Haskell's
@@ -1010,7 +1016,7 @@ the result of applying the function to the value. Equivalent to Haskell's
### Function
-
+
Curries the given binary function.
@@ -1022,7 +1028,7 @@ Curries the given binary function.
[10, 100, 1000]
```
-
+
Curries the given ternary function.
@@ -1039,7 +1045,7 @@ replaceString
'orange icecream'
```
-
+
Curries the given quaternary function.
@@ -1056,7 +1062,7 @@ createRect
{x: 0, y: 0, width: 10, height: 10}
```
-
+
Curries the given quinary function.
@@ -1077,7 +1083,7 @@ toUrl
'https://example.com:443/foo/bar'
```
-
+
Takes a curried binary function and two values, and returns the
result of applying the function to the values in reverse order.
@@ -1089,13 +1095,9 @@ This is the C combinator from combinatory logic.
'barfoo'
```
-
-
-Variant of [`flip`](#flip) which takes an uncurried binary function.
-
### Composition
-
+
Curried version of [`Z.compose`][].
@@ -1112,7 +1114,7 @@ See also [`pipe`](#pipe).
10
```
-
+
Takes an array of functions assumed to be unary and a value of any type,
and returns the result of applying the sequence of transformations to
@@ -1126,41 +1128,35 @@ of functions. `pipe([f, g, h], x)` is equivalent to `h(g(f(x)))`.
9
```
-
+
Takes a binary function `f`, a unary function `g`, and two
values `x` and `y`. Returns `f(g(x))(g(y))`.
This is the P combinator from combinatory logic.
-See also [`on_`](#on_).
-
```javascript
> S.on(S.concat, S.reverse, [1, 2, 3], [4, 5, 6])
[3, 2, 1, 6, 5, 4]
```
-
-
-Variant of [`on`](#on) which takes an uncurried binary function.
-
### Maybe type
The Maybe type represents optional values: a value of type `Maybe a` is
either a Just whose value is of type `a` or Nothing (with no value).
-The Maybe type satisfies the [Setoid][], [Monoid][], [Monad][],
+The Maybe type satisfies the [Ord][], [Monoid][], [Monad][],
[Alternative][], [Traversable][], and [Extend][] specifications.
-
+
A [`UnaryType`][UnaryType] for use with [sanctuary-def][].
-
+
The [type representative](#type-representatives) for the Maybe type.
-
+
Nothing.
@@ -1169,7 +1165,7 @@ Nothing.
Nothing
```
-
+
Takes a value of any type and returns a Just with the given value.
@@ -1178,38 +1174,47 @@ Takes a value of any type and returns a Just with the given value.
Just(42)
```
-
+
Maybe type identifier, `'sanctuary/Maybe'`.
-
+
Returns Nothing.
+It is idiomatic to use [`empty`](#empty) rather than use this function
+directly.
+
```javascript
> S.empty(S.Maybe)
Nothing
```
-
+
Takes a value of any type and returns a Just with the given value.
+It is idiomatic to use [`of`](#of) rather than use this function
+directly.
+
```javascript
> S.of(S.Maybe, 42)
Just(42)
```
-
+
Returns Nothing.
+It is idiomatic to use [`zero`](#zero) rather than use this function
+directly.
+
```javascript
> S.zero(S.Maybe)
Nothing
```
-
+
`true` if `this` is Nothing; `false` if `this` is a Just.
@@ -1221,7 +1226,7 @@ true
false
```
-
+
`true` if `this` is a Just; `false` if `this` is Nothing.
@@ -1233,7 +1238,7 @@ true
false
```
-
+
Returns the string representation of the Maybe.
@@ -1245,7 +1250,7 @@ Returns the string representation of the Maybe.
'Just([1, 2, 3])'
```
-
+
Returns the string representation of the Maybe. This method is used by
`util.inspect` and the REPL to format a Maybe for display.
@@ -1260,7 +1265,7 @@ See also [`Maybe#toString`][].
'Just([1, 2, 3])'
```
-
+
Takes a value `m` of the same type and returns `true` if:
@@ -1269,6 +1274,9 @@ Takes a value `m` of the same type and returns `true` if:
- `this` and `m` are both Justs, and their values are equal according
to [`Z.equals`][].
+It is idiomatic to use [`equals`](#equals) rather than use this method
+directly.
+
```javascript
> S.equals(S.Nothing, S.Nothing)
true
@@ -1283,7 +1291,7 @@ false
false
```
-
+
Takes a value `m` of the same type and returns `true` if:
@@ -1292,6 +1300,9 @@ Takes a value `m` of the same type and returns `true` if:
- `this` and `m` are both Justs and the value of `this` is less than
or equal to the value of `m` according to [`Z.lte`][].
+It is idiomatic to use [`lte`](#lte) or [`lte_`](#lte_) rather than use
+this method directly.
+
```javascript
> S.lte_(S.Nothing, S.Nothing)
true
@@ -1309,7 +1320,7 @@ true
false
```
-
+
Returns the result of concatenating two Maybe values of the same type.
`a` must have a [Semigroup][].
@@ -1323,6 +1334,9 @@ the given Just's value.
Otherwise, this method returns the Just.
+It is idiomatic to use [`concat`](#concat) rather than use this method
+directly.
+
```javascript
> S.concat(S.Nothing, S.Nothing)
Nothing
@@ -1337,12 +1351,15 @@ Just([1, 2, 3])
Just([1, 2, 3])
```
-
+
Takes a function and returns `this` if `this` is Nothing; otherwise
it returns a Just whose value is the result of applying the function
to this Just's value.
+It is idiomatic to use [`map`](#map) rather than use this method
+directly.
+
```javascript
> S.map(Math.sqrt, S.Nothing)
Nothing
@@ -1351,12 +1368,14 @@ Nothing
Just(3)
```
-
+
Takes a Maybe and returns Nothing unless `this` is a Just *and* the
argument is a Just, in which case it returns a Just whose value is
the result of applying the given Just's value to this Just's value.
+It is idiomatic to use [`ap`](#ap) rather than use this method directly.
+
```javascript
> S.ap(S.Nothing, S.Nothing)
Nothing
@@ -1371,11 +1390,14 @@ Nothing
Just(3)
```
-
+
Takes a function and returns `this` if `this` is Nothing; otherwise
it returns the result of applying the function to this Just's value.
+It is idiomatic to use [`chain`](#chain) rather than use this method
+directly.
+
```javascript
> S.chain(S.parseFloat, S.Nothing)
Nothing
@@ -1387,11 +1409,14 @@ Nothing
Just(12.34)
```
-
+
Chooses between `this` and the other Maybe provided as an argument.
Returns `this` if `this` is a Just; the other Maybe otherwise.
+It is idiomatic to use [`alt`](#alt) rather than use this method
+directly.
+
```javascript
> S.alt(S.Nothing, S.Nothing)
Nothing
@@ -1406,7 +1431,7 @@ Just(2)
Just(3)
```
-
+
Takes a function and an initial value of any type, and returns:
@@ -1415,15 +1440,18 @@ Takes a function and an initial value of any type, and returns:
- the result of applying the function to the initial value and this
Just's value.
+It is idiomatic to use [`reduce`](#reduce) rather than use this method
+directly.
+
```javascript
-> S.reduce_(Math.pow, 10, S.Nothing)
+> S.reduce(S.curry2(Math.pow), 10, S.Nothing)
10
-> S.reduce_(Math.pow, 10, S.Just(3))
+> S.reduce(S.curry2(Math.pow), 10, S.Just(3))
1000
```
-
+
Takes the type representative of some [Applicative][] and a function
which returns a value of that Applicative, and returns:
@@ -1434,6 +1462,9 @@ which returns a value of that Applicative, and returns:
- the result of mapping [`Just`](#Just) over the result of applying the
first function to this Just's value.
+It is idiomatic to use [`traverse`](#traverse) rather than use this
+method directly.
+
```javascript
> S.traverse(Array, S.words, S.Nothing)
[Nothing]
@@ -1442,12 +1473,15 @@ which returns a value of that Applicative, and returns:
[Just('foo'), Just('bar'), Just('baz')]
```
-
+
Takes a function and returns `this` if `this` is Nothing; otherwise
it returns a Just whose value is the result of applying the function
to `this`.
+It is idiomatic to use [`extend`](#extend) rather than use this method
+directly.
+
```javascript
> S.extend(x => x.value + 1, S.Nothing)
Nothing
@@ -1456,7 +1490,7 @@ Nothing
Just(43)
```
-
+
Returns `true` if the given Maybe is Nothing; `false` if it is a Just.
@@ -1468,7 +1502,7 @@ true
false
```
-
+
Returns `true` if the given Maybe is a Just; `false` if it is Nothing.
@@ -1480,7 +1514,7 @@ true
false
```
-
+
Takes a default value and a Maybe, and returns the Maybe's value
if the Maybe is a Just; the default value otherwise.
@@ -1496,7 +1530,7 @@ See also [`fromMaybe_`](#fromMaybe_) and
0
```
-
+
Variant of [`fromMaybe`](#fromMaybe) which takes a thunk so the default
value is only computed if required.
@@ -1511,7 +1545,7 @@ value is only computed if required.
832040
```
-
+
Returns the given Maybe's value if the Maybe is a Just; `null` otherwise.
[Nullable][] is defined in [sanctuary-def][].
@@ -1526,7 +1560,7 @@ See also [`fromMaybe`](#fromMaybe).
null
```
-
+
Takes a value and returns Nothing if the value is `null` or `undefined`;
Just the value otherwise.
@@ -1539,7 +1573,7 @@ Nothing
Just(42)
```
-
+
Takes a value of any type, a function, and a Maybe. If the Maybe is
a Just, the return value is the result of applying the function to
@@ -1555,7 +1589,7 @@ See also [`maybe_`](#maybe_).
0
```
-
+
Variant of [`maybe`](#maybe) which takes a thunk so the default value
is only computed if required.
@@ -1570,7 +1604,7 @@ is only computed if required.
832040
```
-
+
Takes an array of Maybes and returns an array containing each Just's
value. Equivalent to Haskell's `catMaybes` function.
@@ -1582,7 +1616,7 @@ See also [`lefts`](#lefts) and [`rights`](#rights).
['foo', 'baz']
```
-
+
Takes a function and an array, applies the function to each element of
the array, and returns an array of "successful" results. If the result of
@@ -1597,7 +1631,7 @@ In general terms, `mapMaybe` filters an array while mapping over it.
[1, 4]
```
-
+
Takes a unary function `f` which may throw and a value `x` of any type,
and applies `f` to `x` inside a `try` block. If an exception is caught,
@@ -1614,29 +1648,15 @@ Just(2)
Nothing
```
-
+
Binary version of [`encase`](#encase).
-See also [`encase2_`](#encase2_).
-
-
-
-Variant of [`encase2`](#encase2) which takes an uncurried binary
-function.
-
-
+
Ternary version of [`encase`](#encase).
-See also [`encase3_`](#encase3_).
-
-
-
-Variant of [`encase3`](#encase3) which takes an uncurried ternary
-function.
-
-
+
Converts a Maybe to an Either. Nothing becomes a Left (containing the
first argument); a Just becomes a Right.
@@ -1657,18 +1677,18 @@ The Either type represents values with two possibilities: a value of type
`Either a b` is either a Left whose value is of type `a` or a Right whose
value is of type `b`.
-The Either type satisfies the [Setoid][], [Semigroup][], [Monad][],
+The Either type satisfies the [Ord][], [Semigroup][], [Monad][],
[Alt][], [Traversable][], [Extend][], and [Bifunctor][] specifications.
-
+
A [`BinaryType`][BinaryType] for use with [sanctuary-def][].
-
+
The [type representative](#type-representatives) for the Either type.
-
+
Takes a value of any type and returns a Left with the given value.
@@ -1677,7 +1697,7 @@ Takes a value of any type and returns a Left with the given value.
Left('Cannot divide by zero')
```
-
+
Takes a value of any type and returns a Right with the given value.
@@ -1686,20 +1706,23 @@ Takes a value of any type and returns a Right with the given value.
Right(42)
```
-
+
Either type identifier, `'sanctuary/Either'`.
-
+
Takes a value of any type and returns a Right with the given value.
+It is idiomatic to use [`of`](#of) rather than use this function
+directly.
+
```javascript
> S.of(S.Either, 42)
Right(42)
```
-
+
`true` if `this` is a Left; `false` if `this` is a Right.
@@ -1711,7 +1734,7 @@ true
false
```
-
+
`true` if `this` is a Right; `false` if `this` is a Left.
@@ -1723,7 +1746,7 @@ true
false
```
-
+
Returns the string representation of the Either.
@@ -1735,7 +1758,7 @@ Returns the string representation of the Either.
'Right([1, 2, 3])'
```
-
+
Returns the string representation of the Either. This method is used by
`util.inspect` and the REPL to format a Either for display.
@@ -1750,13 +1773,16 @@ See also [`Either#toString`][].
'Right([1, 2, 3])'
```
-
+
Takes a value `e` of the same type and returns `true` if:
- `this` and `e` are both Lefts or both Rights, and their values are
equal according to [`Z.equals`][].
+It is idiomatic to use [`equals`](#equals) rather than use this method
+directly.
+
```javascript
> S.equals(S.Right([1, 2, 3]), S.Right([1, 2, 3]))
true
@@ -1765,7 +1791,7 @@ true
false
```
-
+
Takes a value `e` of the same type and returns `true` if:
@@ -1774,6 +1800,9 @@ Takes a value `e` of the same type and returns `true` if:
- `this` and `e` are both Lefts or both Rights, and the value of `this`
is less than or equal to the value of `e` according to [`Z.lte`][].
+It is idiomatic to use [`lte`](#lte) or [`lte_`](#lte_) rather than use
+this method directly.
+
```javascript
> S.lte_(S.Left(10), S.Right(0))
true
@@ -1788,7 +1817,7 @@ true
false
```
-
+
Returns the result of concatenating two Either values of the same type.
`a` must have a [Semigroup][], as must `b`.
@@ -1803,6 +1832,9 @@ the given Right's value.
Otherwise, this method returns the Right.
+It is idiomatic to use [`concat`](#concat) rather than use this method
+directly.
+
```javascript
> S.concat(S.Left('abc'), S.Left('def'))
Left('abcdef')
@@ -1817,12 +1849,15 @@ Right([1, 2, 3])
Right([1, 2, 3])
```
-
+
Takes a function and returns `this` if `this` is a Left; otherwise it
returns a Right whose value is the result of applying the function to
this Right's value.
+It is idiomatic to use [`map`](#map) rather than use this method
+directly.
+
See also [`Either#fantasy-land/bimap`][].
```javascript
@@ -1833,7 +1868,7 @@ Left('Cannot divide by zero')
Right(3)
```
-
+
Takes two functions and returns:
@@ -1846,6 +1881,9 @@ Takes two functions and returns:
Similar to [`Either#fantasy-land/map`][], but supports mapping over the
left side as well as the right side.
+It is idiomatic to use [`bimap`](#bimap) rather than use this method
+directly.
+
```javascript
> S.bimap(S.toUpper, S.add(1), S.Left('abc'))
Left('ABC')
@@ -1854,12 +1892,14 @@ Left('ABC')
Right(43)
```
-
+
Takes an Either and returns a Left unless `this` is a Right *and* the
argument is a Right, in which case it returns a Right whose value is
the result of applying the given Right's value to this Right's value.
+It is idiomatic to use [`ap`](#ap) rather than use this method directly.
+
```javascript
> S.ap(S.Left('No such function'), S.Left('Cannot divide by zero'))
Left('No such function')
@@ -1874,11 +1914,14 @@ Left('Cannot divide by zero')
Right(3)
```
-
+
Takes a function and returns `this` if `this` is a Left; otherwise
it returns the result of applying the function to this Right's value.
+It is idiomatic to use [`chain`](#chain) rather than use this method
+directly.
+
```javascript
> global.sqrt = n =>
. n < 0 ? S.Left('Cannot represent square root of negative number')
@@ -1895,11 +1938,14 @@ Left('Cannot represent square root of negative number')
Right(5)
```
-
+
Chooses between `this` and the other Either provided as an argument.
Returns `this` if `this` is a Right; the other Either otherwise.
+It is idiomatic to use [`alt`](#alt) rather than use this method
+directly.
+
```javascript
> S.alt(S.Left('A'), S.Left('B'))
Left('B')
@@ -1914,7 +1960,7 @@ Right(2)
Right(3)
```
-
+
Takes a function and an initial value of any type, and returns:
@@ -1923,15 +1969,18 @@ Takes a function and an initial value of any type, and returns:
- the result of applying the function to the initial value and this
Right's value.
+It is idiomatic to use [`reduce`](#reduce) rather than use this method
+directly.
+
```javascript
-> S.reduce_(Math.pow, 10, S.Left('Cannot divide by zero'))
+> S.reduce(S.curry2(Math.pow), 10, S.Left('Cannot divide by zero'))
10
-> S.reduce_(Math.pow, 10, S.Right(3))
+> S.reduce(S.curry2(Math.pow), 10, S.Right(3))
1000
```
-
+
Takes the type representative of some [Applicative][] and a function
which returns a value of that Applicative, and returns:
@@ -1942,6 +1991,9 @@ which returns a value of that Applicative, and returns:
- the result of mapping [`Right`](#Right) over the result of applying
the first function to this Right's value.
+It is idiomatic to use [`traverse`](#traverse) rather than use this
+method directly.
+
```javascript
> S.traverse(Array, S.words, S.Left('Request failed'))
[Left('Request failed')]
@@ -1950,12 +2002,15 @@ which returns a value of that Applicative, and returns:
[Right('foo'), Right('bar'), Right('baz')]
```
-
+
Takes a function and returns `this` if `this` is a Left; otherwise it
returns a Right whose value is the result of applying the function to
`this`.
+It is idiomatic to use [`extend`](#extend) rather than use this method
+directly.
+
```javascript
> S.extend(x => x.value + 1, S.Left('Cannot divide by zero'))
Left('Cannot divide by zero')
@@ -1964,7 +2019,7 @@ Left('Cannot divide by zero')
Right(43)
```
-
+
Returns `true` if the given Either is a Left; `false` if it is a Right.
@@ -1976,7 +2031,7 @@ true
false
```
-
+
Returns `true` if the given Either is a Right; `false` if it is a Left.
@@ -1988,7 +2043,7 @@ true
false
```
-
+
Takes a default value and an Either, and returns the Right value
if the Either is a Right; the default value otherwise.
@@ -2001,7 +2056,7 @@ if the Either is a Right; the default value otherwise.
0
```
-
+
Converts an arbitrary value to an Either: a Left if the value is `null`
or `undefined`; a Right otherwise. The first argument specifies the
@@ -2021,7 +2076,7 @@ Left('Invalid protocol')
Right('https:')
```
-
+
Takes two functions and an Either, and returns the result of
applying the first function to the Left's value, if the Either
@@ -2036,7 +2091,7 @@ Right's value, if the Either is a Right.
'42'
```
-
+
Takes an array of Eithers and returns an array containing each Left's
value.
@@ -2048,7 +2103,7 @@ See also [`rights`](#rights).
['foo', 'bar']
```
-
+
Takes an array of Eithers and returns an array containing each Right's
value.
@@ -2060,7 +2115,7 @@ See also [`lefts`](#lefts).
[20, 10]
```
-
+
Takes a predicate and a value, and returns a Right of the value if it
satisfies the predicate; a Left of the value otherwise.
@@ -2073,7 +2128,7 @@ Left(0)
Right(1)
```
-
+
Takes two unary functions, `f` and `g`, the second of which may throw,
and a value `x` of any type. Applies `g` to `x` inside a `try` block.
@@ -2094,29 +2149,15 @@ Left(new SyntaxError('Unexpected end of JSON input'))
Left('Unexpected end of JSON input')
```
-
+
Binary version of [`encaseEither`](#encaseEither).
-See also [`encaseEither2_`](#encaseEither2_).
-
-
-
-Variant of [`encaseEither2`](#encaseEither2) which takes an uncurried
-binary function.
-
-
+
Ternary version of [`encaseEither`](#encaseEither).
-See also [`encaseEither3_`](#encaseEither3_).
-
-
-
-Variant of [`encaseEither3`](#encaseEither3) which takes an uncurried
-ternary function.
-
-
+
Converts an Either to a Maybe. A Left becomes Nothing; a Right becomes
a Just.
@@ -2133,7 +2174,7 @@ Just(42)
### Logic
-
+
Boolean "and".
@@ -2151,7 +2192,7 @@ false
true
```
-
+
Boolean "or".
@@ -2169,7 +2210,7 @@ true
true
```
-
+
Boolean "not".
@@ -2183,7 +2224,7 @@ true
false
```
-
+
Takes a unary predicate and a value of any type, and returns the logical
negation of applying the predicate to the value.
@@ -2198,7 +2239,7 @@ true
false
```
-
+
Takes a unary predicate, a unary "if" function, a unary "else"
function, and a value of any type, and returns the result of
@@ -2216,7 +2257,7 @@ See also [`when`](#when) and [`unless`](#unless).
4
```
-
+
Takes a unary predicate, a unary function, and a value of any type, and
returns the result of applying the function to the value if the value
@@ -2232,7 +2273,7 @@ See also [`unless`](#unless) and [`ifElse`](#ifElse).
-1
```
-
+
Takes a unary predicate, a unary function, and a value of any type, and
returns the result of applying the function to the value if the value
@@ -2248,12 +2289,12 @@ See also [`when`](#when) and [`ifElse`](#ifElse).
-1
```
-
+
-Takes an array of unary predicates and a value of any type
-and returns `true` if all the predicates pass; `false` otherwise.
-None of the subsequent predicates will be evaluated after the
-first failed predicate.
+Takes a structure containing zero or more predicates, and a value
+of any type. Returns `true` [iff][] the value satisfies all of the
+predicates. None of the subsequent predicates will be applied after
+the first predicate not satisfied.
```javascript
> S.allPass([S.test(/q/), S.test(/u/), S.test(/i/)], 'quiessence')
@@ -2263,12 +2304,12 @@ true
false
```
-
+
-Takes an array of unary predicates and a value of any type
-and returns `true` if any of the predicates pass; `false` otherwise.
-None of the subsequent predicates will be evaluated after the
-first passed predicate.
+Takes a structure containing zero or more predicates, and a value
+of any type. Returns `true` [iff][] the value satisfies any of the
+predicates. None of the subsequent predicates will be applied after
+the first predicate satisfied.
```javascript
> S.anyPass([S.test(/q/), S.test(/u/), S.test(/i/)], 'incandescent')
@@ -2291,26 +2332,9 @@ containing `'a'`, `'b'`, and `'c'`. But what is the type of `'a'`?
'abc' :: String, List String, List (List String), ...
-Every member of `String` is also a member of `List String`! This
-affects the interpretation of type signatures. Consider the type of
-[`indexOf`](#indexOf):
-
- a -> List a -> Maybe Integer
-
-Assume the second argument is `'hello' :: List String`. `a` must then be
-replaced with `String`:
-
- String -> List String -> Maybe Integer
-
-Since `List String` and `String` are interchangeable, the former can be
-replaced with the latter:
-
- String -> String -> Maybe Integer
+Every member of `String` is also a member of `List String`!
-It's then apparent that the first argument needn't be a single-character
-string; the correspondence between arrays and strings does not hold.
-
-
+
Returns Just a list containing the elements from the supplied list
from a beginning index (inclusive) to an end index (exclusive).
@@ -2319,15 +2343,15 @@ the end interval, and the list contains both (half-open) intervals.
Accepts negative indices, which indicate an offset from the end of
the list.
+See also [`take`](#take), [`drop`](#drop), [`takeLast`](#takeLast),
+and [`dropLast`](#dropLast).
+
```javascript
> S.slice(1, 3, ['a', 'b', 'c', 'd', 'e'])
Just(['b', 'c'])
-> S.slice(-2, -0, ['a', 'b', 'c', 'd', 'e'])
-Just(['d', 'e'])
-
-> S.slice(2, -0, ['a', 'b', 'c', 'd', 'e'])
-Just(['c', 'd', 'e'])
+> S.slice(-3, -1, ['a', 'b', 'c', 'd', 'e'])
+Just(['c', 'd'])
> S.slice(1, 6, ['a', 'b', 'c', 'd', 'e'])
Nothing
@@ -2336,7 +2360,7 @@ Nothing
Just('nana')
```
-
+
Takes an index and a list and returns Just the element of the list at
the index if the index is within the list's bounds; Nothing otherwise.
@@ -2353,7 +2377,7 @@ Nothing
Just('d')
```
-
+
Takes a list and returns Just the first element of the list if the
list contains at least one element; Nothing if the list is empty.
@@ -2366,7 +2390,7 @@ Just(1)
Nothing
```
-
+
Takes a list and returns Just the last element of the list if the
list contains at least one element; Nothing if the list is empty.
@@ -2379,7 +2403,7 @@ Just(3)
Nothing
```
-
+
Takes a list and returns Just a list containing all but the first
of the list's elements if the list contains at least one element;
@@ -2393,7 +2417,7 @@ Just([2, 3])
Nothing
```
-
+
Takes a list and returns Just a list containing all but the last
of the list's elements if the list contains at least one element;
@@ -2407,7 +2431,7 @@ Just([1, 2])
Nothing
```
-
+
Returns Just the first N elements of the given collection if N is
greater than or equal to zero and less than or equal to the length
@@ -2424,7 +2448,7 @@ Just('abcd')
Nothing
```
-
+
Returns Just the last N elements of the given collection if N is
greater than or equal to zero and less than or equal to the length
@@ -2441,7 +2465,7 @@ Just('defg')
Nothing
```
-
+
Returns Just all but the first N elements of the given collection
if N is greater than or equal to zero and less than or equal to the
@@ -2458,7 +2482,7 @@ Just('efg')
Nothing
```
-
+
Returns Just all but the last N elements of the given collection
if N is greater than or equal to zero and less than or equal to the
@@ -2475,61 +2499,33 @@ Just('abc')
Nothing
```
-
-
-Returns the elements of the given list in reverse order.
-
-```javascript
-> S.reverse([1, 2, 3])
-[3, 2, 1]
-
-> S.reverse('abc')
-'cba'
-```
+### Array
-
+
-Takes a value of any type and a list, and returns Just the index
-of the first occurrence of the value in the list, if applicable;
-Nothing otherwise.
+Returns the number of elements of the given structure.
```javascript
-> S.indexOf('a', ['b', 'a', 'n', 'a', 'n', 'a'])
-Just(1)
-
-> S.indexOf('x', ['b', 'a', 'n', 'a', 'n', 'a'])
-Nothing
-
-> S.indexOf('an', 'banana')
-Just(1)
-
-> S.indexOf('ax', 'banana')
-Nothing
-```
-
-
+> S.size([])
+0
-Takes a value of any type and a list, and returns Just the index
-of the last occurrence of the value in the list, if applicable;
-Nothing otherwise.
+> S.size(['foo', 'bar', 'baz'])
+3
-```javascript
-> S.lastIndexOf('a', ['b', 'a', 'n', 'a', 'n', 'a'])
-Just(5)
+> S.size(Nil)
+0
-> S.lastIndexOf('x', ['b', 'a', 'n', 'a', 'n', 'a'])
-Nothing
+> S.size(Cons('foo', Cons('bar', Cons('baz', Nil))))
+3
-> S.lastIndexOf('an', 'banana')
-Just(3)
+> S.size(S.Nothing)
+0
-> S.lastIndexOf('ax', 'banana')
-Nothing
+> S.size(S.Just('quux'))
+1
```
-### Array
-
-
+
Returns the result of appending the first argument to the second.
@@ -2539,6 +2535,9 @@ See also [`prepend`](#prepend).
> S.append(3, [1, 2])
[1, 2, 3]
+> S.append(3, Cons(1, Cons(2, Nil)))
+Cons(1, Cons(2, Cons(3, Nil)))
+
> S.append([1], S.Nothing)
Just([1])
@@ -2546,7 +2545,7 @@ Just([1])
Just([1, 2, 3])
```
-
+
Returns the result of prepending the first argument to the second.
@@ -2556,6 +2555,9 @@ See also [`append`](#append).
> S.prepend(1, [2, 3])
[1, 2, 3]
+> S.prepend(1, Cons(2, Cons(3, Nil)))
+Cons(1, Cons(2, Cons(3, Nil)))
+
> S.prepend([1], S.Nothing)
Just([1])
@@ -2563,7 +2565,7 @@ Just([1])
Just([1, 2, 3])
```
-
+
Joins the strings of the second argument separated by the first argument.
@@ -2578,10 +2580,10 @@ See also [`splitOn`](#splitOn).
'foo:bar:baz'
```
-
+
-Takes a value and a structure and returns `true` if the value is an
-element of the structure; `false` otherwise.
+Takes a value and a structure and returns `true` [iff][] the value is an
+element of the structure.
See also [`find`](#find).
@@ -2608,7 +2610,7 @@ false
false
```
-
+
Takes a predicate and a structure and returns Just the leftmost element
of the structure which satisfies the predicate; Nothing if there is no
@@ -2624,7 +2626,7 @@ Just(-2)
Nothing
```
-
+
Combines [`map`](#map) and [`prop`](#prop). `pluck(k, xs)` is equivalent
to `map(prop(k), xs)`.
@@ -2637,7 +2639,7 @@ to `map(prop(k), xs)`.
Just(1)
```
-
+
Takes a function and a seed value, and returns an array generated by
applying the function repeatedly. The array is initially empty. The
@@ -2654,7 +2656,7 @@ of the function should result in either:
[1, 2, 3, 4]
```
-
+
Returns an array of consecutive integers starting with the first argument
and ending with the second argument minus one. Returns `[]` if the second
@@ -2671,7 +2673,7 @@ argument is less than or equal to the first argument.
[]
```
-
+
Splits its array argument into an array of arrays of equal,
adjacent elements. Equality is determined by the function
@@ -2679,8 +2681,6 @@ provided as the first argument. Its behaviour can be surprising
for functions that aren't reflexive, transitive, and symmetric
(see [equivalence][] relation).
-See also [`groupBy_`](#groupBy_).
-
Properties:
- `forall f :: a -> a -> Boolean, xs :: Array a.
@@ -2694,11 +2694,22 @@ Properties:
[[2], [-3, 3, 3, 3], [4, -4], [4]]
```
-
+
+
+Reverses the elements of the given structure.
-Variant of [`groupBy`](#groupBy) which takes an uncurried function.
+```javascript
+> S.reverse([1, 2, 3])
+[3, 2, 1]
-
+> S.reverse(Cons(1, Cons(2, Cons(3, Nil))))
+Cons(3, Cons(2, Cons(1, Nil)))
+
+> S.pipe([S.splitOn(''), S.reverse, S.joinWith('')], 'abc')
+'cba'
+```
+
+
Performs a [stable sort][] of the elements of the given structure, using
[`Z.lte`][] for comparisons.
@@ -2717,7 +2728,7 @@ See also [`sortBy`](#sortBy).
[Left(2), Left(4), Right(1), Right(3)]
```
-
+
Performs a [stable sort][] of the elements of the given structure, using
[`Z.lte`][] to compare the values produced by applying the given function
@@ -2755,7 +2766,7 @@ See also [`sort`](#sort).
### Object
-
+
Takes a property name and an object with known properties and returns
the value of the specified property. If for some reason the object
@@ -2770,7 +2781,7 @@ See also [`pluck`](#pluck).
1
```
-
+
Takes a property path (an array of property names) and an object with
known structure and returns the value at the given path. If for some
@@ -2784,7 +2795,7 @@ instead.
1
```
-
+
Takes a predicate, a property name, and an object and returns Just the
value of the specified object property if it exists and the value
@@ -2801,9 +2812,15 @@ Nothing
> S.get(S.is(Number), 'x', {})
Nothing
+
+> S.get($.test([], $.Array($.Number)), 'x', {x: [1, 2, 3]})
+Just([1, 2, 3])
+
+> S.get($.test([], $.Array($.Number)), 'x', {x: [1, 2, 3, null]})
+Nothing
```
-
+
Takes a predicate, a property path (an array of property names), and
an object and returns Just the value at the given path if such a path
@@ -2822,7 +2839,59 @@ Nothing
Nothing
```
-
+### StrMap
+
+StrMap is an abbreviation of _string map_. A string map is an object,
+such as `{foo: 1, bar: 2, baz: 3}`, whose values are all members of
+the same type. Formally, a value is a member of type `StrMap a` if its
+[type identifier][] is `'Object'` and the values of its enumerable own
+properties are all members of type `a`.
+
+
+
+Takes a string and a value of any type, and returns a string map with
+a single entry (mapping the key to the value).
+
+```javascript
+> S.singleton('foo', 42)
+{foo: 42}
+```
+
+
+
+Takes a string, a value of any type, and a string map, and returns a
+string map comprising all the entries of the given string map plus the
+entry specified by the first two arguments (which takes precedence).
+
+Equivalent to Haskell's `insert` function. Similar to Clojure's `assoc`
+function.
+
+```javascript
+> S.insert('c', 3, {a: 1, b: 2})
+{a: 1, b: 2, c: 3}
+
+> S.insert('a', 4, {a: 1, b: 2})
+{a: 4, b: 2}
+```
+
+
+
+Takes a string and a string map, and returns a string map comprising all
+the entries of the given string map except the one whose key matches the
+given string (if such a key exists).
+
+Equivalent to Haskell's `delete` function. Similar to Clojure's `dissoc`
+function.
+
+```javascript
+> S.remove('c', {a: 1, b: 2, c: 3})
+{a: 1, b: 2}
+
+> S.remove('c', {})
+{}
+```
+
+
Returns the keys of the given string map, in arbitrary order.
@@ -2831,7 +2900,7 @@ Returns the keys of the given string map, in arbitrary order.
['a', 'b', 'c']
```
-
+
Returns the values of the given string map, in arbitrary order.
@@ -2840,7 +2909,7 @@ Returns the values of the given string map, in arbitrary order.
[1, 2, 3]
```
-
+
Returns the key–value pairs of the given string map, in arbitrary order.
@@ -2849,9 +2918,23 @@ Returns the key–value pairs of the given string map, in arbitrary order.
[['a', 1], ['b', 2], ['c', 3]]
```
+
+
+Returns a string map containing the key–value pairs specified by the
+given [Foldable][]. If a key appears in multiple pairs, the rightmost
+pair takes precedence.
+
+```javascript
+> S.fromPairs([['a', 1], ['b', 2], ['c', 3]])
+{a: 1, b: 2, c: 3}
+
+> S.fromPairs([['x', 1], ['x', 2]])
+{x: 2}
+```
+
### Number
-
+
Negates its argument.
@@ -2863,7 +2946,7 @@ Negates its argument.
42
```
-
+
Returns the sum of two (finite) numbers.
@@ -2872,7 +2955,7 @@ Returns the sum of two (finite) numbers.
2
```
-
+
Returns the sum of the given array of (finite) numbers.
@@ -2890,7 +2973,7 @@ Returns the sum of the given array of (finite) numbers.
0
```
-
+
Takes a finite number `n` and returns the _subtract `n`_ function.
@@ -2901,7 +2984,7 @@ See also [`sub_`](#sub_).
[0, 1, 2]
```
-
+
Returns the difference between two (finite) numbers.
@@ -2912,7 +2995,7 @@ See also [`sub`](#sub).
2
```
-
+
Returns the product of two (finite) numbers.
@@ -2921,7 +3004,7 @@ Returns the product of two (finite) numbers.
8
```
-
+
Returns the product of the given array of (finite) numbers.
@@ -2939,17 +3022,59 @@ Returns the product of the given array of (finite) numbers.
1
```
-
+
+
+Takes a non-zero finite number `n` and returns the _divide by `n`_
+function.
+
+See also [`div_`](#div_).
+
+```javascript
+> S.map(S.div(2), [0, 1, 2, 3])
+[0, 0.5, 1, 1.5]
+```
+
+
Returns the result of dividing its first argument (a finite number) by
its second argument (a non-zero finite number).
+See also [`div`](#div).
+
```javascript
-> S.div(7, 2)
+> S.div_(7, 2)
3.5
+
+> S.map(S.div_(24), [1, 2, 3, 4])
+[24, 12, 8, 6]
```
-
+
+
+Takes a finite number `n` and returns the _power of `n`_ function.
+
+See also [`pow_`](#pow_).
+
+```javascript
+> S.map(S.pow(2), [-3, -2, -1, 0, 1, 2, 3])
+[9, 4, 1, 0, 1, 4, 9]
+
+> S.map(S.pow(0.5), [1, 4, 9, 16, 25])
+[1, 2, 3, 4, 5]
+```
+
+
+
+Curried version of [`Math.pow`][].
+
+See also [`pow`](#pow).
+
+```javascript
+> S.map(S.pow_(10), [-3, -2, -1, 0, 1, 2, 3])
+[0.001, 0.01, 0.1, 1, 10, 100, 1000]
+```
+
+
Returns the mean of the given array of (finite) numbers.
@@ -2969,7 +3094,7 @@ Nothing
### Integer
-
+
Returns `true` if the given integer is even; `false` if it is odd.
@@ -2981,7 +3106,7 @@ true
false
```
-
+
Returns `true` if the given integer is odd; `false` if it is even.
@@ -2995,7 +3120,7 @@ false
### Parse
-
+
Takes a string and returns Just the date represented by the string
if it does in fact represent a date; Nothing otherwise.
@@ -3008,7 +3133,7 @@ Just(new Date('2011-01-19T17:40:00.000Z'))
Nothing
```
-
+
Takes a string and returns Just the number represented by the string
if it does in fact represent a number; Nothing otherwise.
@@ -3021,7 +3146,7 @@ Just(-123.45)
Nothing
```
-
+
Takes a radix (an integer between 2 and 36 inclusive) and a string,
and returns Just the number represented by the string if it does in
@@ -3043,26 +3168,29 @@ Just(255)
Nothing
```
-
+
Takes a predicate and a string which may or may not be valid JSON, and
returns Just the result of applying `JSON.parse` to the string *if* the
result satisfies the predicate; Nothing otherwise.
```javascript
-> S.parseJson(S.is(Array), '["foo","bar","baz"]')
-Just(['foo', 'bar', 'baz'])
+> S.parseJson($.test([], $.Array($.Integer)), '[')
+Nothing
-> S.parseJson(S.is(Array), '[')
+> S.parseJson($.test([], $.Array($.Integer)), '["1","2","3"]')
Nothing
-> S.parseJson(S.is(Object), '["foo","bar","baz"]')
+> S.parseJson($.test([], $.Array($.Integer)), '[0,1.5,3,4.5]')
Nothing
+
+> S.parseJson($.test([], $.Array($.Integer)), '[1,2,3]')
+Just([1, 2, 3])
```
### RegExp
-
+
Takes a [RegexFlags][] and a pattern, and returns a RegExp.
@@ -3071,7 +3199,7 @@ Takes a [RegexFlags][] and a pattern, and returns a RegExp.
/:\d+:/g
```
-
+
Takes a string which may contain regular expression metacharacters,
and returns a string with those metacharacters escaped.
@@ -3085,10 +3213,10 @@ Properties:
'\\-=\\*\\{XYZ\\}\\*=\\-'
```
-
+
-Takes a pattern and a string, and returns `true` if the pattern
-matches the string; `false` otherwise.
+Takes a pattern and a string, and returns `true` [iff][] the pattern
+matches the string.
```javascript
> S.test(/^a/, 'abacus')
@@ -3098,7 +3226,7 @@ true
false
```
-
+
Takes a pattern and a string, and returns Just a match record if the
pattern matches the string; Nothing otherwise.
@@ -3121,7 +3249,7 @@ Just({match: 'goodbye', groups: [Just('good')]})
Just({match: 'bye', groups: [Nothing]})
```
-
+
Takes a pattern and a string, and returns an array of match records.
@@ -3142,7 +3270,7 @@ See also [`match`](#match).
### String
-
+
Returns the upper-case equivalent of its argument.
@@ -3153,7 +3281,7 @@ See also [`toLower`](#toLower).
'ABC DEF 123'
```
-
+
Returns the lower-case equivalent of its argument.
@@ -3164,7 +3292,7 @@ See also [`toUpper`](#toUpper).
'abc def 123'
```
-
+
Strips leading and trailing whitespace characters.
@@ -3173,7 +3301,7 @@ Strips leading and trailing whitespace characters.
'foo bar'
```
-
+
Returns Just the portion of the given string (the second argument) left
after removing the given prefix (the first argument) if the string starts
@@ -3189,7 +3317,7 @@ Just('sanctuary.js.org')
Nothing
```
-
+
Returns Just the portion of the given string (the second argument) left
after removing the given suffix (the first argument) if the string ends
@@ -3205,7 +3333,7 @@ Just('README')
Nothing
```
-
+
Takes a string and returns the array of words the string contains
(words are delimited by whitespace characters).
@@ -3217,7 +3345,7 @@ See also [`unwords`](#unwords).
['foo', 'bar', 'baz']
```
-
+
Takes an array of words and returns the result of joining the words
with separating spaces.
@@ -3229,7 +3357,7 @@ See also [`words`](#words).
'foo bar baz'
```
-
+
Takes a string and returns the array of lines the string contains
(lines are delimited by newlines: `'\n'` or `'\r\n'` or `'\r'`).
@@ -3242,7 +3370,7 @@ See also [`unlines`](#unlines).
['foo', 'bar', 'baz']
```
-
+
Takes an array of lines and returns the result of joining the lines
after appending a terminating line feed (`'\n'`) to each.
@@ -3254,7 +3382,7 @@ See also [`lines`](#lines).
'foo\nbar\nbaz\n'
```
-
+
Returns the substrings of its second argument separated by occurrences
of its first argument.
@@ -3266,7 +3394,7 @@ See also [`joinWith`](#joinWith) and [`splitOnRegex`](#splitOnRegex).
['foo', 'bar', 'baz']
```
-
+
Takes a pattern and a string, and returns the result of splitting the
string at every non-overlapping occurrence of the pattern.
@@ -3287,64 +3415,67 @@ See also [`splitOn`](#splitOn).
['foo', 'bar', 'baz']
```
-[$.Array]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#Array
-[$.String]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#String
-[Alt]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#alt
-[Alternative]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#alternative
-[Applicative]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#applicative
-[Apply]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#apply
-[Bifunctor]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#bifunctor
-[BinaryType]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#BinaryType
+[$.Array]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#Array
+[$.String]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#String
+[Alt]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#alt
+[Alternative]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#alternative
+[Applicative]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#applicative
+[Apply]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#apply
+[Bifunctor]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#bifunctor
+[BinaryType]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#BinaryType
[Either]: #either-type
-[Extend]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#extend
-[Fantasy Land]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0
-[Foldable]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#foldable
+[Extend]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#extend
+[Fantasy Land]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0
+[Foldable]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#foldable
[Haskell]: https://www.haskell.org/
[Maybe]: #maybe-type
-[Monad]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#monad
-[Monoid]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#monoid
-[Nullable]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#Nullable
+[Monad]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#monad
+[Monoid]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#monoid
+[Nullable]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#Nullable
+[Ord]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#ord
[PureScript]: http://www.purescript.org/
[Ramda]: http://ramdajs.com/
-[RegexFlags]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#RegexFlags
-[Semigroup]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#semigroup
-[Semigroupoid]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#semigroupoid
-[Setoid]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#setoid
-[Traversable]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#traversable
-[UnaryType]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1#UnaryType
-[`Z.alt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#alt
-[`Z.ap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#ap
-[`Z.apFirst`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#apFirst
-[`Z.apSecond`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#apSecond
-[`Z.bimap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#bimap
-[`Z.chain`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#chain
-[`Z.chainRec`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#chainRec
-[`Z.compose`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#compose
-[`Z.concat`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#concat
-[`Z.contramap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#contramap
-[`Z.empty`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#empty
-[`Z.equals`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#equals
-[`Z.extend`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#extend
-[`Z.extract`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#extract
-[`Z.filter`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#filter
-[`Z.filterM`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#filterM
-[`Z.gt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#gt
-[`Z.gte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#gte
-[`Z.id`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#id
-[`Z.join`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#join
-[`Z.lt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#lt
-[`Z.lte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#lte
-[`Z.map`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#map
-[`Z.of`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#of
-[`Z.promap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#promap
-[`Z.sequence`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#sequence
-[`Z.toString`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#toString
-[`Z.traverse`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#traverse
-[`Z.zero`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v6.0.0#zero
-[`of`]: https://github.com/fantasyland/fantasy-land/tree/v3.3.0#of-method
+[RegexFlags]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#RegexFlags
+[Semigroup]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#semigroup
+[Semigroupoid]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#semigroupoid
+[Traversable]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#traversable
+[UnaryType]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#UnaryType
+[`Math.pow`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow
+[`Z.alt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#alt
+[`Z.ap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#ap
+[`Z.apFirst`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#apFirst
+[`Z.apSecond`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#apSecond
+[`Z.bimap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#bimap
+[`Z.chain`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#chain
+[`Z.chainRec`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#chainRec
+[`Z.compose`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#compose
+[`Z.concat`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#concat
+[`Z.contramap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#contramap
+[`Z.empty`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#empty
+[`Z.equals`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#equals
+[`Z.extend`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#extend
+[`Z.extract`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#extract
+[`Z.filter`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#filter
+[`Z.filterM`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#filterM
+[`Z.gt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#gt
+[`Z.gte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#gte
+[`Z.id`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#id
+[`Z.invert`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#invert
+[`Z.join`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#join
+[`Z.lt`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#lt
+[`Z.lte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#lte
+[`Z.map`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#map
+[`Z.of`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#of
+[`Z.promap`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#promap
+[`Z.sequence`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#sequence
+[`Z.toString`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#toString
+[`Z.traverse`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#traverse
+[`Z.zero`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v7.1.1#zero
+[`of`]: https://github.com/fantasyland/fantasy-land/tree/v3.4.0#of-method
[equivalence]: https://en.wikipedia.org/wiki/Equivalence_relation
+[iff]: https://en.wikipedia.org/wiki/If_and_only_if
[parseInt]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt
-[sanctuary-def]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.12.1
+[sanctuary-def]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0
[stable sort]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability
[thrush]: https://github.com/raganwald-deprecated/homoiconic/blob/master/2008-10-30/thrush.markdown
[type identifier]: https://github.com/sanctuary-js/sanctuary-type-identifiers/tree/v2.0.1
diff --git a/index.js b/index.js
index 7111a810..514d52a7 100644
--- a/index.js
+++ b/index.js
@@ -246,7 +246,7 @@
// readmeUrl :: String -> String
function readmeUrl(id) {
- var version = '0.13.2'; // updated programmatically
+ var version = '0.14.0'; // updated programmatically
return 'https://github.com/sanctuary-js/sanctuary/tree/v' + version +
'#' + id;
}
diff --git a/package.json b/package.json
index e65f1d9a..9525ec83 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "sanctuary",
- "version": "0.13.2",
+ "version": "0.14.0",
"description": "Refuge from unsafe JavaScript",
"license": "MIT",
"repository": {