From 8a8e7e7af5b32a7f33a0f1b9b7a258696e42a851 Mon Sep 17 00:00:00 2001 From: David Chambers Date: Mon, 18 Dec 2017 23:09:10 +0100 Subject: [PATCH] Version 0.14.0 --- README.md | 963 +++++++++++++++++++++++++++++---------------------- index.js | 2 +- package.json | 2 +- 3 files changed, 549 insertions(+), 418 deletions(-) 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 -

create :: { checkTypes :: Boolean, env :: Array Type } -⁠> Module

+

create :: { checkTypes :: Boolean, env :: Array Type } -⁠> Module

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

env :: Array Type

+

env :: Array Type

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

__ :: Placeholder

+

__ :: Placeholder

The special [placeholder](#placeholder) value. @@ -287,7 +271,7 @@ The special [placeholder](#placeholder) value. ### Classify -

type :: Any -⁠> { namespace :: Maybe String, name :: String, version :: Integer }

+

type :: Any -⁠> { namespace :: Maybe String, name :: String, version :: NonNegativeInteger }

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

is :: TypeRep a -⁠> Any -⁠> Boolean

+

is :: TypeRep a -⁠> Any -⁠> Boolean

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

toString :: Any -⁠> String

+

toString :: Any -⁠> String

Alias of [`Z.toString`][]. @@ -340,7 +324,7 @@ Alias of [`Z.toString`][]. Sanctuary is compatible with the [Fantasy Land][] specification. -

equals :: Setoid a => a -⁠> a -⁠> Boolean

+

equals :: Setoid a => a -⁠> a -⁠> Boolean

Curried version of [`Z.equals`][] which requires two arguments of the same type. @@ -363,9 +347,10 @@ true false ``` -

lt :: Ord a => a -⁠> (a -⁠> Boolean)

+

lt :: Ord a => a -⁠> (a -⁠> Boolean)

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

lt_ :: Ord a => a -⁠> a -⁠> Boolean

+

lt_ :: Ord a => a -⁠> a -⁠> Boolean

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

lte :: Ord a => a -⁠> (a -⁠> Boolean)

+

lte :: Ord a => a -⁠> (a -⁠> Boolean)

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

lte_ :: Ord a => a -⁠> a -⁠> Boolean

+

lte_ :: Ord a => a -⁠> a -⁠> Boolean

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

gt :: Ord a => a -⁠> (a -⁠> Boolean)

+

gt :: Ord a => a -⁠> (a -⁠> Boolean)

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

gt_ :: Ord a => a -⁠> a -⁠> Boolean

+

gt_ :: Ord a => a -⁠> a -⁠> Boolean

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

gte :: Ord a => a -⁠> (a -⁠> Boolean)

+

gte :: Ord a => a -⁠> (a -⁠> Boolean)

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

gte_ :: Ord a => a -⁠> a -⁠> Boolean

+

gte_ :: Ord a => a -⁠> a -⁠> Boolean

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

min :: Ord a => a -⁠> a -⁠> a

+

min :: Ord a => a -⁠> a -⁠> a

Returns the smaller of its two arguments (according to [`Z.lte`][]). @@ -492,7 +486,7 @@ new Date('1999-12-31') '10' ``` -

max :: Ord a => a -⁠> a -⁠> a

+

max :: Ord a => a -⁠> a -⁠> a

Returns the larger of its two arguments (according to [`Z.lte`][]). @@ -509,7 +503,7 @@ new Date('2000-01-01') '2' ``` -

id :: Category c => TypeRep c -⁠> c

+

id :: Category c => TypeRep c -⁠> c

[Type-safe][sanctuary-def] version of [`Z.id`][]. @@ -518,7 +512,7 @@ new Date('2000-01-01') 42 ``` -

concat :: Semigroup a => a -⁠> a -⁠> a

+

concat :: Semigroup a => a -⁠> a -⁠> a

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

empty :: Monoid a => TypeRep a -⁠> a

+

empty :: Monoid a => TypeRep a -⁠> a

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

invert :: Group g => g -⁠> g

+ +[Type-safe][sanctuary-def] version of [`Z.invert`][]. + +```javascript +> S.invert(Sum(5)) +Sum(-5) ``` -

map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b

+

map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b

Curried version of [`Z.map`][]. @@ -584,7 +593,7 @@ from combinatory logic (i.e. [`compose`](#compose)): 10 ``` -

bimap :: Bifunctor f => (a -⁠> b) -⁠> (c -⁠> d) -⁠> f a c -⁠> f b d

+

bimap :: Bifunctor f => (a -⁠> b) -⁠> (c -⁠> d) -⁠> f a c -⁠> f b d

Curried version of [`Z.bimap`][]. @@ -596,7 +605,7 @@ Left('FOO') Right(8) ``` -

promap :: Profunctor p => (a -⁠> b) -⁠> (c -⁠> d) -⁠> p b c -⁠> p a d

+

promap :: Profunctor p => (a -⁠> b) -⁠> (c -⁠> d) -⁠> p b c -⁠> p a d

Curried version of [`Z.promap`][]. @@ -605,7 +614,7 @@ Curried version of [`Z.promap`][]. 11 ``` -

alt :: Alt f => f a -⁠> f a -⁠> f a

+

alt :: Alt f => f a -⁠> f a -⁠> f a

Curried version of [`Z.alt`][]. @@ -623,7 +632,7 @@ Right(1) Right(2) ``` -

zero :: Plus f => TypeRep f -⁠> f a

+

zero :: Plus f => TypeRep f -⁠> f a

[Type-safe][sanctuary-def] version of [`Z.zero`][]. @@ -638,7 +647,7 @@ Right(2) Nothing ``` -

reduce :: Foldable f => (b -⁠> a -⁠> b) -⁠> b -⁠> f a -⁠> b

+

reduce :: Foldable f => (b -⁠> a -⁠> b) -⁠> b -⁠> f a -⁠> b

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

reduce_ :: Foldable f => ((b, a) -⁠> b) -⁠> b -⁠> f a -⁠> b

- -Variant of [`reduce`](#reduce) which takes an uncurried binary function. - -

traverse :: (Applicative f, Traversable t) => TypeRep f -⁠> (a -⁠> f b) -⁠> t a -⁠> f (t b)

+

traverse :: (Applicative f, Traversable t) => TypeRep f -⁠> (a -⁠> f b) -⁠> t a -⁠> f (t b)

Curried version of [`Z.traverse`][]. @@ -686,9 +689,10 @@ Just({a: 10, b: 11, c: 12}) Nothing ``` -

sequence :: (Applicative f, Traversable t) => TypeRep f -⁠> t (f a) -⁠> f (t a)

+

sequence :: (Applicative f, Traversable t) => TypeRep f -⁠> t (f a) -⁠> f (t a)

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

ap :: Apply f => f (a -⁠> b) -⁠> f a -⁠> f b

+

ap :: Apply f => f (a -⁠> b) -⁠> f a -⁠> f b

Curried version of [`Z.ap`][]. @@ -737,7 +741,7 @@ from combinatory logic: 'Hask' ``` -

lift2 :: Apply f => (a -⁠> b -⁠> c) -⁠> f a -⁠> f b -⁠> f c

+

lift2 :: Apply f => (a -⁠> b -⁠> c) -⁠> f a -⁠> f b -⁠> f c

Promotes a curried binary function to a function which operates on two [Apply][]s. @@ -756,7 +760,7 @@ Just(true) Just(false) ``` -

lift3 :: Apply f => (a -⁠> b -⁠> c -⁠> d) -⁠> f a -⁠> f b -⁠> f c -⁠> f d

+

lift3 :: Apply f => (a -⁠> b -⁠> c -⁠> d) -⁠> f a -⁠> f b -⁠> f c -⁠> f d

Promotes a curried ternary function to a function which operates on three [Apply][]s. @@ -769,7 +773,7 @@ Just(6) Nothing ``` -

apFirst :: Apply f => f a -⁠> f b -⁠> f a

+

apFirst :: Apply f => f a -⁠> f b -⁠> f a

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

apSecond :: Apply f => f a -⁠> f b -⁠> f b

+

apSecond :: Apply f => f a -⁠> f b -⁠> f b

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

of :: Applicative f => TypeRep f -⁠> a -⁠> f a

+

of :: Applicative f => TypeRep f -⁠> a -⁠> f a

Curried version of [`Z.of`][]. @@ -819,7 +823,7 @@ Just(42) Right(42) ``` -

chain :: Chain m => (a -⁠> m b) -⁠> m a -⁠> m b

+

chain :: Chain m => (a -⁠> m b) -⁠> m a -⁠> m b

Curried version of [`Z.chain`][]. @@ -837,7 +841,7 @@ Just(123) Nothing ``` -

join :: Chain m => m (m a) -⁠> m a

+

join :: Chain m => m (m a) -⁠> m a

[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' ``` -

chainRec :: ChainRec m => TypeRep m -⁠> (a -⁠> m (Either a b)) -⁠> a -⁠> m b

+

chainRec :: ChainRec m => TypeRep m -⁠> (a -⁠> m (Either a b)) -⁠> a -⁠> m b

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?'] ``` -

extend :: Extend w => (w a -⁠> b) -⁠> w a -⁠> w b

+

extend :: Extend w => (w a -⁠> b) -⁠> w a -⁠> w b

Curried version of [`Z.extend`][]. @@ -888,11 +892,11 @@ Curried version of [`Z.extend`][]. ['xyz', 'yz', 'z'] ``` -

extract :: Comonad w => w a -⁠> a

+

extract :: Comonad w => w a -⁠> a

[Type-safe][sanctuary-def] version of [`Z.extract`][]. -

contramap :: Contravariant f => (b -⁠> a) -⁠> f a -⁠> f b

+

contramap :: Contravariant f => (b -⁠> a) -⁠> f a -⁠> f b

[Type-safe][sanctuary-def] version of [`Z.contramap`][]. @@ -901,9 +905,10 @@ Curried version of [`Z.extend`][]. 3 ``` -

filter :: (Applicative f, Foldable f, Monoid (f a)) => (a -⁠> Boolean) -⁠> f a -⁠> f a

+

filter :: (Applicative f, Foldable f, Monoid (f a)) => (a -⁠> Boolean) -⁠> f a -⁠> f a

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

filterM :: (Alternative m, Monad m) => (a -⁠> Boolean) -⁠> m a -⁠> m a

+

filterM :: (Alternative m, Monad m) => (a -⁠> Boolean) -⁠> m a -⁠> m a

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

takeWhile :: (Foldable f, Alternative f) => (a -⁠> Boolean) -⁠> f a -⁠> f a

+

takeWhile :: (Foldable f, Alternative f) => (a -⁠> Boolean) -⁠> f a -⁠> f a

Discards the first inner value which does not satisfy the predicate, and all subsequent inner values. @@ -942,7 +948,7 @@ all subsequent inner values. [] ``` -

dropWhile :: (Foldable f, Alternative f) => (a -⁠> Boolean) -⁠> f a -⁠> f a

+

dropWhile :: (Foldable f, Alternative f) => (a -⁠> Boolean) -⁠> f a -⁠> f a

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 -

I :: a -⁠> a

+

I :: a -⁠> a

The I combinator. Returns its argument. Equivalent to Haskell's `id` function. @@ -967,7 +973,7 @@ function. 'foo' ``` -

K :: a -⁠> b -⁠> a

+

K :: a -⁠> b -⁠> a

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

A :: (a -⁠> b) -⁠> a -⁠> b

+

A :: (a -⁠> b) -⁠> a -⁠> b

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

T :: a -⁠> (a -⁠> b) -⁠> b

+

T :: a -⁠> (a -⁠> b) -⁠> b

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 -

curry2 :: ((a, b) -⁠> c) -⁠> a -⁠> b -⁠> c

+

curry2 :: ((a, b) -⁠> c) -⁠> a -⁠> b -⁠> c

Curries the given binary function. @@ -1022,7 +1028,7 @@ Curries the given binary function. [10, 100, 1000] ``` -

curry3 :: ((a, b, c) -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d

+

curry3 :: ((a, b, c) -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d

Curries the given ternary function. @@ -1039,7 +1045,7 @@ replaceString 'orange icecream' ``` -

curry4 :: ((a, b, c, d) -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e

+

curry4 :: ((a, b, c, d) -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e

Curries the given quaternary function. @@ -1056,7 +1062,7 @@ createRect {x: 0, y: 0, width: 10, height: 10} ``` -

curry5 :: ((a, b, c, d, e) -⁠> f) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e -⁠> f

+

curry5 :: ((a, b, c, d, e) -⁠> f) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e -⁠> f

Curries the given quinary function. @@ -1077,7 +1083,7 @@ toUrl 'https://example.com:443/foo/bar' ``` -

flip :: (a -⁠> b -⁠> c) -⁠> b -⁠> a -⁠> c

+

flip :: (a -⁠> b -⁠> c) -⁠> b -⁠> a -⁠> c

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

flip_ :: ((a, b) -⁠> c) -⁠> b -⁠> a -⁠> c

- -Variant of [`flip`](#flip) which takes an uncurried binary function. - ### Composition -

compose :: Semigroupoid s => s b c -⁠> s a b -⁠> s a c

+

compose :: Semigroupoid s => s b c -⁠> s a b -⁠> s a c

Curried version of [`Z.compose`][]. @@ -1112,7 +1114,7 @@ See also [`pipe`](#pipe). 10 ``` -

pipe :: [(a -⁠> b), (b -⁠> c), ..., (m -⁠> n)] -⁠> a -⁠> n

+

pipe :: [(a -⁠> b), (b -⁠> c), ..., (m -⁠> n)] -⁠> a -⁠> n

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

on :: (b -⁠> b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> a -⁠> c

+

on :: (b -⁠> b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> a -⁠> c

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

on_ :: ((b, b) -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> a -⁠> c

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

MaybeType :: Type -⁠> Type

+

MaybeType :: Type -⁠> Type

A [`UnaryType`][UnaryType] for use with [sanctuary-def][]. -

Maybe :: TypeRep Maybe

+

Maybe :: TypeRep Maybe

The [type representative](#type-representatives) for the Maybe type. -

Nothing :: Maybe a

+

Nothing :: Maybe a

Nothing. @@ -1169,7 +1165,7 @@ Nothing. Nothing ``` -

Just :: a -⁠> Maybe a

+

Just :: a -⁠> Maybe a

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 :: String

+

Maybe.@@type :: String

Maybe type identifier, `'sanctuary/Maybe'`. -

Maybe.fantasy-land/empty :: () -⁠> Maybe a

+

Maybe.fantasy-land/empty :: () -⁠> Maybe a

Returns Nothing. +It is idiomatic to use [`empty`](#empty) rather than use this function +directly. + ```javascript > S.empty(S.Maybe) Nothing ``` -

Maybe.fantasy-land/of :: a -⁠> Maybe a

+

Maybe.fantasy-land/of :: a -⁠> Maybe a

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

Maybe.fantasy-land/zero :: () -⁠> Maybe a

+

Maybe.fantasy-land/zero :: () -⁠> Maybe a

Returns Nothing. +It is idiomatic to use [`zero`](#zero) rather than use this function +directly. + ```javascript > S.zero(S.Maybe) Nothing ``` -

Maybe#isNothing :: Maybe a ~> Boolean

+

Maybe#isNothing :: Maybe a ~> Boolean

`true` if `this` is Nothing; `false` if `this` is a Just. @@ -1221,7 +1226,7 @@ true false ``` -

Maybe#isJust :: Maybe a ~> Boolean

+

Maybe#isJust :: Maybe a ~> Boolean

`true` if `this` is a Just; `false` if `this` is Nothing. @@ -1233,7 +1238,7 @@ true false ``` -

Maybe#toString :: Maybe a ~> () -⁠> String

+

Maybe#toString :: Maybe a ~> () -⁠> String

Returns the string representation of the Maybe. @@ -1245,7 +1250,7 @@ Returns the string representation of the Maybe. 'Just([1, 2, 3])' ``` -

Maybe#inspect :: Maybe a ~> () -⁠> String

+

Maybe#inspect :: Maybe a ~> () -⁠> String

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])' ``` -

Maybe#fantasy-land/equals :: Setoid a => Maybe a ~> Maybe a -⁠> Boolean

+

Maybe#fantasy-land/equals :: Setoid a => Maybe a ~> Maybe a -⁠> Boolean

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

Maybe#fantasy-land/lte :: Ord a => Maybe a ~> Maybe a -⁠> Boolean

+

Maybe#fantasy-land/lte :: Ord a => Maybe a ~> Maybe a -⁠> Boolean

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

Maybe#fantasy-land/concat :: Semigroup a => Maybe a ~> Maybe a -⁠> Maybe a

+

Maybe#fantasy-land/concat :: Semigroup a => Maybe a ~> Maybe a -⁠> Maybe a

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]) ``` -

Maybe#fantasy-land/map :: Maybe a ~> (a -⁠> b) -⁠> Maybe b

+

Maybe#fantasy-land/map :: Maybe a ~> (a -⁠> b) -⁠> Maybe b

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

Maybe#fantasy-land/ap :: Maybe a ~> Maybe (a -⁠> b) -⁠> Maybe b

+

Maybe#fantasy-land/ap :: Maybe a ~> Maybe (a -⁠> b) -⁠> Maybe b

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

Maybe#fantasy-land/chain :: Maybe a ~> (a -⁠> Maybe b) -⁠> Maybe b

+

Maybe#fantasy-land/chain :: Maybe a ~> (a -⁠> Maybe b) -⁠> Maybe b

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

Maybe#fantasy-land/alt :: Maybe a ~> Maybe a -⁠> Maybe a

+

Maybe#fantasy-land/alt :: Maybe a ~> Maybe a -⁠> Maybe a

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

Maybe#fantasy-land/reduce :: Maybe a ~> ((b, a) -⁠> b, b) -⁠> b

+

Maybe#fantasy-land/reduce :: Maybe a ~> ((b, a) -⁠> b, b) -⁠> b

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

Maybe#fantasy-land/traverse :: Applicative f => Maybe a ~> (TypeRep f, a -⁠> f b) -⁠> f (Maybe b)

+

Maybe#fantasy-land/traverse :: Applicative f => Maybe a ~> (TypeRep f, a -⁠> f b) -⁠> f (Maybe b)

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')] ``` -

Maybe#fantasy-land/extend :: Maybe a ~> (Maybe a -⁠> b) -⁠> Maybe b

+

Maybe#fantasy-land/extend :: Maybe a ~> (Maybe a -⁠> b) -⁠> Maybe b

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

isNothing :: Maybe a -⁠> Boolean

+

isNothing :: Maybe a -⁠> Boolean

Returns `true` if the given Maybe is Nothing; `false` if it is a Just. @@ -1468,7 +1502,7 @@ true false ``` -

isJust :: Maybe a -⁠> Boolean

+

isJust :: Maybe a -⁠> Boolean

Returns `true` if the given Maybe is a Just; `false` if it is Nothing. @@ -1480,7 +1514,7 @@ true false ``` -

fromMaybe :: a -⁠> Maybe a -⁠> a

+

fromMaybe :: a -⁠> Maybe a -⁠> a

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

fromMaybe_ :: (() -⁠> a) -⁠> Maybe a -⁠> a

+

fromMaybe_ :: (() -⁠> a) -⁠> Maybe a -⁠> a

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

maybeToNullable :: Maybe a -⁠> Nullable a

+

maybeToNullable :: Maybe a -⁠> Nullable a

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

toMaybe :: a? -⁠> Maybe a

+

toMaybe :: a? -⁠> Maybe a

Takes a value and returns Nothing if the value is `null` or `undefined`; Just the value otherwise. @@ -1539,7 +1573,7 @@ Nothing Just(42) ``` -

maybe :: b -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b

+

maybe :: b -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b

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

maybe_ :: (() -⁠> b) -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b

+

maybe_ :: (() -⁠> b) -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b

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

justs :: Array (Maybe a) -⁠> Array a

+

justs :: Array (Maybe a) -⁠> Array a

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'] ``` -

mapMaybe :: (a -⁠> Maybe b) -⁠> Array a -⁠> Array b

+

mapMaybe :: (a -⁠> Maybe b) -⁠> Array a -⁠> Array b

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

encase :: (a -⁠> b) -⁠> a -⁠> Maybe b

+

encase :: (a -⁠> b) -⁠> a -⁠> Maybe b

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

encase2 :: (a -⁠> b -⁠> c) -⁠> a -⁠> b -⁠> Maybe c

+

encase2 :: (a -⁠> b -⁠> c) -⁠> a -⁠> b -⁠> Maybe c

Binary version of [`encase`](#encase). -See also [`encase2_`](#encase2_). - -

encase2_ :: ((a, b) -⁠> c) -⁠> a -⁠> b -⁠> Maybe c

- -Variant of [`encase2`](#encase2) which takes an uncurried binary -function. - -

encase3 :: (a -⁠> b -⁠> c -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> Maybe d

+

encase3 :: (a -⁠> b -⁠> c -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> Maybe d

Ternary version of [`encase`](#encase). -See also [`encase3_`](#encase3_). - -

encase3_ :: ((a, b, c) -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> Maybe d

- -Variant of [`encase3`](#encase3) which takes an uncurried ternary -function. - -

maybeToEither :: a -⁠> Maybe b -⁠> Either a b

+

maybeToEither :: a -⁠> Maybe b -⁠> Either a b

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

EitherType :: Type -⁠> Type -⁠> Type

+

EitherType :: Type -⁠> Type -⁠> Type

A [`BinaryType`][BinaryType] for use with [sanctuary-def][]. -

Either :: TypeRep Either

+

Either :: TypeRep Either

The [type representative](#type-representatives) for the Either type. -

Left :: a -⁠> Either a b

+

Left :: a -⁠> Either a b

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') ``` -

Right :: b -⁠> Either a b

+

Right :: b -⁠> Either a b

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 :: String

+

Either.@@type :: String

Either type identifier, `'sanctuary/Either'`. -

Either.fantasy-land/of :: b -⁠> Either a b

+

Either.fantasy-land/of :: b -⁠> Either a b

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

Either#isLeft :: Either a b ~> Boolean

+

Either#isLeft :: Either a b ~> Boolean

`true` if `this` is a Left; `false` if `this` is a Right. @@ -1711,7 +1734,7 @@ true false ``` -

Either#isRight :: Either a b ~> Boolean

+

Either#isRight :: Either a b ~> Boolean

`true` if `this` is a Right; `false` if `this` is a Left. @@ -1723,7 +1746,7 @@ true false ``` -

Either#toString :: Either a b ~> () -⁠> String

+

Either#toString :: Either a b ~> () -⁠> String

Returns the string representation of the Either. @@ -1735,7 +1758,7 @@ Returns the string representation of the Either. 'Right([1, 2, 3])' ``` -

Either#inspect :: Either a b ~> () -⁠> String

+

Either#inspect :: Either a b ~> () -⁠> String

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])' ``` -

Either#fantasy-land/equals :: (Setoid a, Setoid b) => Either a b ~> Either a b -⁠> Boolean

+

Either#fantasy-land/equals :: (Setoid a, Setoid b) => Either a b ~> Either a b -⁠> Boolean

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

Either#fantasy-land/lte :: (Ord a, Ord b) => Either a b ~> Either a b -⁠> Boolean

+

Either#fantasy-land/lte :: (Ord a, Ord b) => Either a b ~> Either a b -⁠> Boolean

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

Either#fantasy-land/concat :: (Semigroup a, Semigroup b) => Either a b ~> Either a b -⁠> Either a b

+

Either#fantasy-land/concat :: (Semigroup a, Semigroup b) => Either a b ~> Either a b -⁠> Either a b

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]) ``` -

Either#fantasy-land/map :: Either a b ~> (b -⁠> c) -⁠> Either a c

+

Either#fantasy-land/map :: Either a b ~> (b -⁠> c) -⁠> Either a c

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

Either#fantasy-land/bimap :: Either a b ~> (a -⁠> c, b -⁠> d) -⁠> Either c d

+

Either#fantasy-land/bimap :: Either a b ~> (a -⁠> c, b -⁠> d) -⁠> Either c d

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

Either#fantasy-land/ap :: Either a b ~> Either a (b -⁠> c) -⁠> Either a c

+

Either#fantasy-land/ap :: Either a b ~> Either a (b -⁠> c) -⁠> Either a c

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

Either#fantasy-land/chain :: Either a b ~> (b -⁠> Either a c) -⁠> Either a c

+

Either#fantasy-land/chain :: Either a b ~> (b -⁠> Either a c) -⁠> Either a c

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

Either#fantasy-land/alt :: Either a b ~> Either a b -⁠> Either a b

+

Either#fantasy-land/alt :: Either a b ~> Either a b -⁠> Either a b

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

Either#fantasy-land/reduce :: Either a b ~> ((c, b) -⁠> c, c) -⁠> c

+

Either#fantasy-land/reduce :: Either a b ~> ((c, b) -⁠> c, c) -⁠> c

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

Either#fantasy-land/traverse :: Applicative f => Either a b ~> (TypeRep f, b -⁠> f c) -⁠> f (Either a c)

+

Either#fantasy-land/traverse :: Applicative f => Either a b ~> (TypeRep f, b -⁠> f c) -⁠> f (Either a c)

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')] ``` -

Either#fantasy-land/extend :: Either a b ~> (Either a b -⁠> c) -⁠> Either a c

+

Either#fantasy-land/extend :: Either a b ~> (Either a b -⁠> c) -⁠> Either a c

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

isLeft :: Either a b -⁠> Boolean

+

isLeft :: Either a b -⁠> Boolean

Returns `true` if the given Either is a Left; `false` if it is a Right. @@ -1976,7 +2031,7 @@ true false ``` -

isRight :: Either a b -⁠> Boolean

+

isRight :: Either a b -⁠> Boolean

Returns `true` if the given Either is a Right; `false` if it is a Left. @@ -1988,7 +2043,7 @@ true false ``` -

fromEither :: b -⁠> Either a b -⁠> b

+

fromEither :: b -⁠> Either a b -⁠> b

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

toEither :: a -⁠> b? -⁠> Either a b

+

toEither :: a -⁠> b? -⁠> Either a b

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:') ``` -

either :: (a -⁠> c) -⁠> (b -⁠> c) -⁠> Either a b -⁠> c

+

either :: (a -⁠> c) -⁠> (b -⁠> c) -⁠> Either a b -⁠> c

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

lefts :: Array (Either a b) -⁠> Array a

+

lefts :: Array (Either a b) -⁠> Array a

Takes an array of Eithers and returns an array containing each Left's value. @@ -2048,7 +2103,7 @@ See also [`rights`](#rights). ['foo', 'bar'] ``` -

rights :: Array (Either a b) -⁠> Array b

+

rights :: Array (Either a b) -⁠> Array b

Takes an array of Eithers and returns an array containing each Right's value. @@ -2060,7 +2115,7 @@ See also [`lefts`](#lefts). [20, 10] ``` -

tagBy :: (a -⁠> Boolean) -⁠> a -⁠> Either a a

+

tagBy :: (a -⁠> Boolean) -⁠> a -⁠> Either a a

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

encaseEither :: (Error -⁠> l) -⁠> (a -⁠> r) -⁠> a -⁠> Either l r

+

encaseEither :: (Error -⁠> l) -⁠> (a -⁠> r) -⁠> a -⁠> Either l r

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') ``` -

encaseEither2 :: (Error -⁠> l) -⁠> (a -⁠> b -⁠> r) -⁠> a -⁠> b -⁠> Either l r

+

encaseEither2 :: (Error -⁠> l) -⁠> (a -⁠> b -⁠> r) -⁠> a -⁠> b -⁠> Either l r

Binary version of [`encaseEither`](#encaseEither). -See also [`encaseEither2_`](#encaseEither2_). - -

encaseEither2_ :: (Error -⁠> l) -⁠> ((a, b) -⁠> r) -⁠> a -⁠> b -⁠> Either l r

- -Variant of [`encaseEither2`](#encaseEither2) which takes an uncurried -binary function. - -

encaseEither3 :: (Error -⁠> l) -⁠> (a -⁠> b -⁠> c -⁠> r) -⁠> a -⁠> b -⁠> c -⁠> Either l r

+

encaseEither3 :: (Error -⁠> l) -⁠> (a -⁠> b -⁠> c -⁠> r) -⁠> a -⁠> b -⁠> c -⁠> Either l r

Ternary version of [`encaseEither`](#encaseEither). -See also [`encaseEither3_`](#encaseEither3_). - -

encaseEither3_ :: (Error -⁠> l) -⁠> ((a, b, c) -⁠> r) -⁠> a -⁠> b -⁠> c -⁠> Either l r

- -Variant of [`encaseEither3`](#encaseEither3) which takes an uncurried -ternary function. - -

eitherToMaybe :: Either a b -⁠> Maybe b

+

eitherToMaybe :: Either a b -⁠> Maybe b

Converts an Either to a Maybe. A Left becomes Nothing; a Right becomes a Just. @@ -2133,7 +2174,7 @@ Just(42) ### Logic -

and :: Boolean -⁠> Boolean -⁠> Boolean

+

and :: Boolean -⁠> Boolean -⁠> Boolean

Boolean "and". @@ -2151,7 +2192,7 @@ false true ``` -

or :: Boolean -⁠> Boolean -⁠> Boolean

+

or :: Boolean -⁠> Boolean -⁠> Boolean

Boolean "or". @@ -2169,7 +2210,7 @@ true true ``` -

not :: Boolean -⁠> Boolean

+

not :: Boolean -⁠> Boolean

Boolean "not". @@ -2183,7 +2224,7 @@ true false ``` -

complement :: (a -⁠> Boolean) -⁠> a -⁠> Boolean

+

complement :: (a -⁠> Boolean) -⁠> a -⁠> Boolean

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

ifElse :: (a -⁠> Boolean) -⁠> (a -⁠> b) -⁠> (a -⁠> b) -⁠> a -⁠> b

+

ifElse :: (a -⁠> Boolean) -⁠> (a -⁠> b) -⁠> (a -⁠> b) -⁠> a -⁠> b

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

when :: (a -⁠> Boolean) -⁠> (a -⁠> a) -⁠> a -⁠> a

+

when :: (a -⁠> Boolean) -⁠> (a -⁠> a) -⁠> a -⁠> a

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

unless :: (a -⁠> Boolean) -⁠> (a -⁠> a) -⁠> a -⁠> a

+

unless :: (a -⁠> Boolean) -⁠> (a -⁠> a) -⁠> a -⁠> a

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

allPass :: Array (a -⁠> Boolean) -⁠> a -⁠> Boolean

+

allPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean

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

anyPass :: Array (a -⁠> Boolean) -⁠> a -⁠> Boolean

+

anyPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean

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

slice :: Integer -⁠> Integer -⁠> List a -⁠> Maybe (List a)

+

slice :: Integer -⁠> Integer -⁠> List a -⁠> Maybe (List a)

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') ``` -

at :: Integer -⁠> List a -⁠> Maybe a

+

at :: Integer -⁠> List a -⁠> Maybe a

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') ``` -

head :: List a -⁠> Maybe a

+

head :: List a -⁠> Maybe a

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

last :: List a -⁠> Maybe a

+

last :: List a -⁠> Maybe a

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

tail :: List a -⁠> Maybe (List a)

+

tail :: List a -⁠> Maybe (List a)

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

init :: List a -⁠> Maybe (List a)

+

init :: List a -⁠> Maybe (List a)

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

take :: Integer -⁠> List a -⁠> Maybe (List a)

+

take :: Integer -⁠> List a -⁠> Maybe (List a)

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

takeLast :: Integer -⁠> List a -⁠> Maybe (List a)

+

takeLast :: Integer -⁠> List a -⁠> Maybe (List a)

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

drop :: Integer -⁠> List a -⁠> Maybe (List a)

+

drop :: Integer -⁠> List a -⁠> Maybe (List a)

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

dropLast :: Integer -⁠> List a -⁠> Maybe (List a)

+

dropLast :: Integer -⁠> List a -⁠> Maybe (List a)

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

reverse :: List a -⁠> List a

- -Returns the elements of the given list in reverse order. - -```javascript -> S.reverse([1, 2, 3]) -[3, 2, 1] - -> S.reverse('abc') -'cba' -``` +### Array -

indexOf :: a -⁠> List a -⁠> Maybe Integer

+

size :: Foldable f => f a -⁠> Integer

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

lastIndexOf :: a -⁠> List a -⁠> Maybe Integer

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

append :: (Applicative f, Semigroup (f a)) => a -⁠> f a -⁠> f a

+

append :: (Applicative f, Semigroup (f a)) => a -⁠> f a -⁠> f a

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]) ``` -

prepend :: (Applicative f, Semigroup (f a)) => a -⁠> f a -⁠> f a

+

prepend :: (Applicative f, Semigroup (f a)) => a -⁠> f a -⁠> f a

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]) ``` -

joinWith :: String -⁠> Array String -⁠> String

+

joinWith :: String -⁠> Array String -⁠> String

Joins the strings of the second argument separated by the first argument. @@ -2578,10 +2580,10 @@ See also [`splitOn`](#splitOn). 'foo:bar:baz' ``` -

elem :: (Setoid a, Foldable f) => a -⁠> f a -⁠> Boolean

+

elem :: (Setoid a, Foldable f) => a -⁠> f a -⁠> Boolean

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

find :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Maybe a

+

find :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Maybe a

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

pluck :: (Accessible a, Functor f) => String -⁠> f a -⁠> f b

+

pluck :: Functor f => String -⁠> f a -⁠> f b

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

unfoldr :: (b -⁠> Maybe (Pair a b)) -⁠> b -⁠> Array a

+

unfoldr :: (b -⁠> Maybe (Pair a b)) -⁠> b -⁠> Array a

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

range :: Integer -⁠> Integer -⁠> Array Integer

+

range :: Integer -⁠> Integer -⁠> Array Integer

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

groupBy :: (a -⁠> a -⁠> Boolean) -⁠> Array a -⁠> Array (Array a)

+

groupBy :: (a -⁠> a -⁠> Boolean) -⁠> Array a -⁠> Array (Array a)

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

groupBy_ :: ((a, a) -⁠> Boolean) -⁠> Array a -⁠> Array (Array a)

+

reverse :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> f a

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

sort :: (Ord a, Applicative m, Foldable m, Monoid (m a)) => m a -⁠> m a

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

sort :: (Ord a, Applicative m, Foldable m, Monoid (m a)) => m a -⁠> m a

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)] ``` -

sortBy :: (Ord b, Applicative m, Foldable m, Monoid (m a)) => (a -⁠> b) -⁠> m a -⁠> m a

+

sortBy :: (Ord b, Applicative m, Foldable m, Monoid (m a)) => (a -⁠> b) -⁠> m a -⁠> m a

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 -

prop :: Accessible a => String -⁠> a -⁠> b

+

prop :: String -⁠> a -⁠> b

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

props :: Accessible a => Array String -⁠> a -⁠> b

+

props :: Array String -⁠> a -⁠> b

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

get :: Accessible a => (b -⁠> Boolean) -⁠> String -⁠> a -⁠> Maybe c

+

get :: (Any -⁠> Boolean) -⁠> String -⁠> a -⁠> Maybe b

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

gets :: Accessible a => (b -⁠> Boolean) -⁠> Array String -⁠> a -⁠> Maybe c

+

gets :: (Any -⁠> Boolean) -⁠> Array String -⁠> a -⁠> Maybe b

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

keys :: StrMap a -⁠> Array String

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

singleton :: String -⁠> a -⁠> StrMap 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} +``` + +

insert :: String -⁠> a -⁠> StrMap a -⁠> StrMap a

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

remove :: String -⁠> StrMap a -⁠> StrMap a

+ +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', {}) +{} +``` + +

keys :: StrMap a -⁠> Array String

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'] ``` -

values :: StrMap a -⁠> Array a

+

values :: StrMap a -⁠> Array a

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

pairs :: StrMap a -⁠> Array (Pair String a)

+

pairs :: StrMap a -⁠> Array (Pair String a)

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

fromPairs :: Foldable f => f (Pair String a) -⁠> StrMap a

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

negate :: ValidNumber -⁠> ValidNumber

+

negate :: ValidNumber -⁠> ValidNumber

Negates its argument. @@ -2863,7 +2946,7 @@ Negates its argument. 42 ``` -

add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

+

add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

Returns the sum of two (finite) numbers. @@ -2872,7 +2955,7 @@ Returns the sum of two (finite) numbers. 2 ``` -

sum :: Foldable f => f FiniteNumber -⁠> FiniteNumber

+

sum :: Foldable f => f FiniteNumber -⁠> FiniteNumber

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

sub :: FiniteNumber -⁠> (FiniteNumber -⁠> FiniteNumber)

+

sub :: FiniteNumber -⁠> (FiniteNumber -⁠> FiniteNumber)

Takes a finite number `n` and returns the _subtract `n`_ function. @@ -2901,7 +2984,7 @@ See also [`sub_`](#sub_). [0, 1, 2] ``` -

sub_ :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

+

sub_ :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

Returns the difference between two (finite) numbers. @@ -2912,7 +2995,7 @@ See also [`sub`](#sub). 2 ``` -

mult :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

+

mult :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

Returns the product of two (finite) numbers. @@ -2921,7 +3004,7 @@ Returns the product of two (finite) numbers. 8 ``` -

product :: Foldable f => f FiniteNumber -⁠> FiniteNumber

+

product :: Foldable f => f FiniteNumber -⁠> FiniteNumber

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

div :: FiniteNumber -⁠> NonZeroFiniteNumber -⁠> FiniteNumber

+

div :: NonZeroFiniteNumber -⁠> (FiniteNumber -⁠> FiniteNumber)

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

div_ :: FiniteNumber -⁠> NonZeroFiniteNumber -⁠> FiniteNumber

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

mean :: Foldable f => f FiniteNumber -⁠> Maybe FiniteNumber

+

pow :: FiniteNumber -⁠> (FiniteNumber -⁠> FiniteNumber)

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

pow_ :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber

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

mean :: Foldable f => f FiniteNumber -⁠> Maybe FiniteNumber

Returns the mean of the given array of (finite) numbers. @@ -2969,7 +3094,7 @@ Nothing ### Integer -

even :: Integer -⁠> Boolean

+

even :: Integer -⁠> Boolean

Returns `true` if the given integer is even; `false` if it is odd. @@ -2981,7 +3106,7 @@ true false ``` -

odd :: Integer -⁠> Boolean

+

odd :: Integer -⁠> Boolean

Returns `true` if the given integer is odd; `false` if it is even. @@ -2995,7 +3120,7 @@ false ### Parse -

parseDate :: String -⁠> Maybe Date

+

parseDate :: String -⁠> Maybe ValidDate

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

parseFloat :: String -⁠> Maybe Number

+

parseFloat :: String -⁠> Maybe Number

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

parseInt :: Integer -⁠> String -⁠> Maybe Integer

+

parseInt :: Radix -⁠> String -⁠> Maybe Integer

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

parseJson :: (a -⁠> Boolean) -⁠> String -⁠> Maybe b

+

parseJson :: (Any -⁠> Boolean) -⁠> String -⁠> Maybe a

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 -

regex :: RegexFlags -⁠> String -⁠> RegExp

+

regex :: RegexFlags -⁠> String -⁠> 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 ``` -

regexEscape :: String -⁠> String

+

regexEscape :: String -⁠> String

Takes a string which may contain regular expression metacharacters, and returns a string with those metacharacters escaped. @@ -3085,10 +3213,10 @@ Properties: '\\-=\\*\\{XYZ\\}\\*=\\-' ``` -

test :: RegExp -⁠> String -⁠> Boolean

+

test :: RegExp -⁠> String -⁠> Boolean

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

match :: NonGlobalRegExp -⁠> String -⁠> Maybe { match :: String, groups :: Array (Maybe String) }

+

match :: NonGlobalRegExp -⁠> String -⁠> Maybe { match :: String, groups :: Array (Maybe String) }

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]}) ``` -

matchAll :: GlobalRegExp -⁠> String -⁠> Array { match :: String, groups :: Array (Maybe String) }

+

matchAll :: GlobalRegExp -⁠> String -⁠> Array { match :: String, groups :: Array (Maybe String) }

Takes a pattern and a string, and returns an array of match records. @@ -3142,7 +3270,7 @@ See also [`match`](#match). ### String -

toUpper :: String -⁠> String

+

toUpper :: String -⁠> String

Returns the upper-case equivalent of its argument. @@ -3153,7 +3281,7 @@ See also [`toLower`](#toLower). 'ABC DEF 123' ``` -

toLower :: String -⁠> String

+

toLower :: String -⁠> String

Returns the lower-case equivalent of its argument. @@ -3164,7 +3292,7 @@ See also [`toUpper`](#toUpper). 'abc def 123' ``` -

trim :: String -⁠> String

+

trim :: String -⁠> String

Strips leading and trailing whitespace characters. @@ -3173,7 +3301,7 @@ Strips leading and trailing whitespace characters. 'foo bar' ``` -

stripPrefix :: String -⁠> String -⁠> Maybe String

+

stripPrefix :: String -⁠> String -⁠> Maybe String

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

stripSuffix :: String -⁠> String -⁠> Maybe String

+

stripSuffix :: String -⁠> String -⁠> Maybe String

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

words :: String -⁠> Array String

+

words :: String -⁠> Array String

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'] ``` -

unwords :: Array String -⁠> String

+

unwords :: Array String -⁠> String

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

lines :: String -⁠> Array String

+

lines :: String -⁠> Array String

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'] ``` -

unlines :: Array String -⁠> String

+

unlines :: Array String -⁠> String

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

splitOn :: String -⁠> String -⁠> Array String

+

splitOn :: String -⁠> String -⁠> Array String

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'] ``` -

splitOnRegex :: GlobalRegExp -⁠> String -⁠> Array String

+

splitOnRegex :: GlobalRegExp -⁠> String -⁠> Array String

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": {