From 71f138cbe02382f9b3f46bdd387919cfa8bc2f39 Mon Sep 17 00:00:00 2001 From: David Chambers Date: Sun, 9 Aug 2020 12:40:59 +0200 Subject: [PATCH] Version 3.1.0 --- README.md | 503 +++++++++++++++++++++++++++---------------------- dist/bundle.js | 300 ++++++++++++++++++----------- package.json | 2 +- 3 files changed, 470 insertions(+), 335 deletions(-) diff --git a/README.md b/README.md index 5f97345b..687d5b9c 100644 --- a/README.md +++ b/README.md @@ -280,7 +280,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.21.1#FiniteNumber for information about the FiniteNumber type. +// See https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0#FiniteNumber for information about the FiniteNumber type. ``` Compare this to the behaviour of Ramda's unchecked equivalent: @@ -310,17 +310,11 @@ via selective use of [`unchecked`](#unchecked) functions. `npm install sanctuary` will install Sanctuary for use in Node.js. -To add Sanctuary to a website, first run the following command, replacing -`X.Y.Z` with a version number greater than or equal to `2.0.2`: - -```console -$ curl https://raw.githubusercontent.com/sanctuary-js/sanctuary/vX.Y.Z/dist/bundle.js >vendor/sanctuary-bundle.js -``` - -Then reference the bundle from __index.html__: +To add Sanctuary to a website, add the following ` + ``` Optionally, define aliases for various modules: @@ -335,7 +329,7 @@ const $ = window.sanctuaryDef; ### ❑ Configure -#### `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 @@ -390,7 +384,7 @@ S.map (S.sub (1)) (Identity (43)); See also [`env`](#env). -#### `env :: Array Type` +#### `env :: Array Type` The Sanctuary module's environment (`(S.create ({checkTypes, env})).env` is a reference to `env`). Useful in conjunction with [`create`](#create). @@ -402,6 +396,7 @@ is a reference to `env`). Useful in conjunction with [`create`](#create). . $.Array ($.Unknown), . $.Array2 ($.Unknown) ($.Unknown), . $.Boolean, +. $.Buffer, . $.Date, . $.Descending ($.Unknown), . $.Either ($.Unknown) ($.Unknown), @@ -426,7 +421,7 @@ is a reference to `env`). Useful in conjunction with [`create`](#create). . $.Undefined ] ``` -#### `unchecked :: Module` +#### `unchecked :: Module` A complete Sanctuary module that performs no type checking. This is useful as it permits operations that Sanctuary's type checking would @@ -448,7 +443,7 @@ Opting out of type checking may cause type errors to go unnoticed. ### ❑ Classify -#### `type :: Any -⁠> { namespace :: Maybe String, name :: String, version :: NonNegativeInteger }` +#### `type :: Any -⁠> { namespace :: Maybe String, name :: String, version :: NonNegativeInteger }` Returns the result of parsing the [type identifier][] of the given value. @@ -460,7 +455,7 @@ Returns the result of parsing the [type identifier][] of the given value. {namespace: Nothing, name: 'Array', version: 0} ``` -#### `is :: Type -⁠> Any -⁠> Boolean` +#### `is :: Type -⁠> Any -⁠> Boolean` Returns `true` [iff][] the given value is a member of the specified type. See [`$.test`][] for details. @@ -475,7 +470,7 @@ false ### ❑ Showable -#### `show :: Any -⁠> String` +#### `show :: Any -⁠> String` Alias of [`show`][]. @@ -497,7 +492,7 @@ Alias of [`show`][]. 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`][] that requires two arguments of the same type. @@ -520,7 +515,7 @@ true false ``` -#### `lt :: Ord a => a -⁠> a -⁠> Boolean` +#### `lt :: Ord a => a -⁠> a -⁠> Boolean` Returns `true` [iff][] the *second* argument is less than the first according to [`Z.lt`][]. @@ -530,7 +525,7 @@ according to [`Z.lt`][]. [1, 2] ``` -#### `lte :: Ord a => a -⁠> a -⁠> Boolean` +#### `lte :: Ord a => a -⁠> a -⁠> Boolean` Returns `true` [iff][] the *second* argument is less than or equal to the first according to [`Z.lte`][]. @@ -540,7 +535,7 @@ the first according to [`Z.lte`][]. [1, 2, 3] ``` -#### `gt :: Ord a => a -⁠> a -⁠> Boolean` +#### `gt :: Ord a => a -⁠> a -⁠> Boolean` Returns `true` [iff][] the *second* argument is greater than the first according to [`Z.gt`][]. @@ -550,7 +545,7 @@ according to [`Z.gt`][]. [4, 5] ``` -#### `gte :: Ord a => a -⁠> a -⁠> Boolean` +#### `gte :: Ord a => a -⁠> a -⁠> Boolean` Returns `true` [iff][] the *second* argument is greater than or equal to the first according to [`Z.gte`][]. @@ -560,7 +555,7 @@ to the first according to [`Z.gte`][]. [3, 4, 5] ``` -#### `min :: Ord a => a -⁠> a -⁠> a` +#### `min :: Ord a => a -⁠> a -⁠> a` Returns the smaller of its two arguments (according to [`Z.lte`][]). @@ -577,7 +572,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`][]). @@ -594,7 +589,7 @@ new Date ('2000-01-01') '2' ``` -#### `clamp :: Ord a => a -⁠> a -⁠> a -⁠> a` +#### `clamp :: Ord a => a -⁠> a -⁠> a -⁠> a` Takes a lower bound, an upper bound, and a value of the same type. Returns the value if it is within the bounds; the nearer bound otherwise. @@ -612,7 +607,7 @@ See also [`min`](#min) and [`max`](#max). 'Z' ``` -#### `id :: Category c => TypeRep c -⁠> c` +#### `id :: Category c => TypeRep c -⁠> c` [Type-safe][sanctuary-def] version of [`Z.id`][]. @@ -621,7 +616,7 @@ See also [`min`](#min) and [`max`](#max). 42 ``` -#### `concat :: Semigroup a => a -⁠> a -⁠> a` +#### `concat :: Semigroup a => a -⁠> a -⁠> a` Curried version of [`Z.concat`][]. @@ -642,7 +637,7 @@ Just ([1, 2, 3, 4, 5, 6]) Sum (42) ``` -#### `empty :: Monoid a => TypeRep a -⁠> a` +#### `empty :: Monoid a => TypeRep a -⁠> a` [Type-safe][sanctuary-def] version of [`Z.empty`][]. @@ -660,7 +655,7 @@ Sum (42) Sum (0) ``` -#### `invert :: Group g => g -⁠> g` +#### `invert :: Group g => g -⁠> g` [Type-safe][sanctuary-def] version of [`Z.invert`][]. @@ -669,7 +664,7 @@ Sum (0) Sum (-5) ``` -#### `filter :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` +#### `filter :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` Curried version of [`Z.filter`][]. Discards every element that does not satisfy the predicate. @@ -693,7 +688,7 @@ Nothing Just (1) ``` -#### `reject :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` +#### `reject :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` Curried version of [`Z.reject`][]. Discards every element that satisfies the predicate. @@ -717,7 +712,7 @@ Just (0) Nothing ``` -#### `map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b` +#### `map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b` Curried version of [`Z.map`][]. @@ -753,7 +748,7 @@ from combinatory logic (i.e. [`compose`](#compose)): 10 ``` -#### `flip :: Functor f => f (a -⁠> b) -⁠> a -⁠> f b` +#### `flip :: Functor f => f (a -⁠> b) -⁠> a -⁠> f b` Curried version of [`Z.flip`][]. Maps over the given functions, applying each to the given value. @@ -782,7 +777,7 @@ from combinatory logic: Cons (1) (Cons (2) (Nil)) ``` -#### `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`][]. @@ -797,7 +792,7 @@ Left ('FOO') Right (8) ``` -#### `mapLeft :: Bifunctor f => (a -⁠> b) -⁠> f a c -⁠> f b c` +#### `mapLeft :: Bifunctor f => (a -⁠> b) -⁠> f a c -⁠> f b c` Curried version of [`Z.mapLeft`][]. Maps the given function over the left side of a Bifunctor. @@ -813,7 +808,7 @@ Left ('FOO') Right (64) ``` -#### `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`][]. @@ -822,7 +817,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`][] with arguments flipped to facilitate partial application. @@ -841,7 +836,7 @@ Right (0) Right (1) ``` -#### `zero :: Plus f => TypeRep f -⁠> f a` +#### `zero :: Plus f => TypeRep f -⁠> f a` [Type-safe][sanctuary-def] version of [`Z.zero`][]. @@ -856,7 +851,7 @@ Right (1) 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 @@ -866,6 +861,8 @@ 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 @@ -874,7 +871,20 @@ otherwise. [5, 4, 3, 2, 1] ``` -#### `traverse :: (Applicative f, Traversable t) => TypeRep f -⁠> (a -⁠> f b) -⁠> t a -⁠> f (t b)` +#### `reduce_ :: Foldable f => (a -⁠> b -⁠> b) -⁠> b -⁠> f a -⁠> b` + +Variant of [`reduce`](#reduce) that takes a reducing function with +arguments flipped. + +```javascript +> S.reduce_ (S.append) ([]) (Cons (1) (Cons (2) (Cons (3) (Nil)))) +[1, 2, 3] + +> S.reduce_ (S.prepend) ([]) (Cons (1) (Cons (2) (Cons (3) (Nil)))) +[3, 2, 1] +``` + +#### `traverse :: (Applicative f, Traversable t) => TypeRep f -⁠> (a -⁠> f b) -⁠> t a -⁠> f (t b)` Curried version of [`Z.traverse`][]. @@ -898,7 +908,7 @@ 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`][]. Inverts the given `t (f a)` to produce an `f (t a)`. @@ -920,7 +930,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`][]. @@ -950,7 +960,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 that operates on two [Apply][]s. @@ -969,7 +979,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 that operates on three [Apply][]s. @@ -982,7 +992,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 `(<*)` @@ -998,7 +1008,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 `(*>)` @@ -1014,7 +1024,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`][]. @@ -1032,7 +1042,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`][]. @@ -1050,7 +1060,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. @@ -1081,7 +1091,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 @@ -1095,7 +1105,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`][]. @@ -1107,7 +1117,7 @@ Curried version of [`Z.extend`][]. [4, 3, 2, 1] ``` -#### `duplicate :: Extend w => w a -⁠> w (w a)` +#### `duplicate :: Extend w => w a -⁠> w (w a)` [Type-safe][sanctuary-def] version of [`Z.duplicate`][]. Adds one level of nesting to a comonadic structure. @@ -1126,7 +1136,7 @@ Just (Just (1)) [4, 3, 2, 1] ``` -#### `extract :: Comonad w => w a -⁠> a` +#### `extract :: Comonad w => w a -⁠> a` [Type-safe][sanctuary-def] version of [`Z.extract`][]. @@ -1135,7 +1145,7 @@ Just (Just (1)) 'bar' ``` -#### `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`][]. @@ -1146,7 +1156,7 @@ Just (Just (1)) ### ❑ Combinator -#### `I :: a -⁠> a` +#### `I :: a -⁠> a` The I combinator. Returns its argument. Equivalent to Haskell's `id` function. @@ -1156,7 +1166,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. @@ -1169,7 +1179,7 @@ Haskell's `const` function. [42, 42, 42, 42, 42] ``` -#### `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 @@ -1185,7 +1195,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. @@ -1194,7 +1204,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. @@ -1207,7 +1217,7 @@ Curries the given ternary function. '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. @@ -1220,7 +1230,7 @@ Curries the given quaternary function. {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. @@ -1239,7 +1249,7 @@ Curries the given quinary 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`][]. @@ -1256,7 +1266,7 @@ See also [`pipe`](#pipe). 10 ``` -#### `pipe :: Foldable f => f (Any -⁠> Any) -⁠> a -⁠> b` +#### `pipe :: Foldable f => f (Any -⁠> Any) -⁠> a -⁠> b` Takes a sequence of functions assumed to be unary and a value of any type, and returns the result of applying the sequence of transformations @@ -1270,7 +1280,7 @@ of functions. `pipe ([f, g, h]) (x)` is equivalent to `h (g (f (x)))`. 9 ``` -#### `pipeK :: (Foldable f, Chain m) => f (Any -⁠> m Any) -⁠> m a -⁠> m b` +#### `pipeK :: (Foldable f, Chain m) => f (Any -⁠> m Any) -⁠> m a -⁠> m b` Takes a sequence of functions assumed to be unary that return values with a [Chain][], and a value of that Chain, and returns the result @@ -1285,7 +1295,7 @@ of an sequence of functions. `pipeK ([f, g, h]) (x)` is equivalent to Just (3) ``` -#### `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))`. @@ -1304,7 +1314,7 @@ contains exactly two values: one of type `a`; one of type `b`. The implementation is provided by [sanctuary-pair][]. -#### `Pair :: a -⁠> b -⁠> Pair a b` +#### `Pair :: a -⁠> b -⁠> Pair a b` Pair's sole data constructor. Additionally, it serves as the Pair [type representative][]. @@ -1314,7 +1324,7 @@ Pair [type representative][]. Pair ('foo') (42) ``` -#### `pair :: (a -⁠> b -⁠> c) -⁠> Pair a b -⁠> c` +#### `pair :: (a -⁠> b -⁠> c) -⁠> Pair a b -⁠> c` Case analysis for the `Pair a b` type. @@ -1323,7 +1333,7 @@ Case analysis for the `Pair a b` type. 'foobar' ``` -#### `fst :: Pair a b -⁠> a` +#### `fst :: Pair a b -⁠> a` `fst (Pair (x) (y))` is equivalent to `x`. @@ -1332,7 +1342,7 @@ Case analysis for the `Pair a b` type. 'foo' ``` -#### `snd :: Pair a b -⁠> b` +#### `snd :: Pair a b -⁠> b` `snd (Pair (x) (y))` is equivalent to `y`. @@ -1341,7 +1351,7 @@ Case analysis for the `Pair a b` type. 42 ``` -#### `swap :: Pair a b -⁠> Pair b a` +#### `swap :: Pair a b -⁠> Pair b a` `swap (Pair (x) (y))` is equivalent to `Pair (y) (x)`. @@ -1357,11 +1367,11 @@ either Nothing (the empty value) or a Just whose value is of type `a`. The implementation is provided by [sanctuary-maybe][]. -#### `Maybe :: TypeRep Maybe` +#### `Maybe :: TypeRep Maybe` Maybe [type representative][]. -#### `Nothing :: Maybe a` +#### `Nothing :: Maybe a` The empty value of type `Maybe a`. @@ -1370,7 +1380,7 @@ The empty value of type `Maybe a`. Nothing ``` -#### `Just :: a -⁠> Maybe a` +#### `Just :: a -⁠> Maybe a` Constructs a value of type `Maybe a` from a value of type `a`. @@ -1379,7 +1389,7 @@ Constructs a value of type `Maybe a` from a value of type `a`. Just (42) ``` -#### `isNothing :: Maybe a -⁠> Boolean` +#### `isNothing :: Maybe a -⁠> Boolean` Returns `true` if the given Maybe is Nothing; `false` if it is a Just. @@ -1391,7 +1401,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. @@ -1403,84 +1413,69 @@ true false ``` -#### `fromMaybe :: a -⁠> Maybe a -⁠> a` +#### `maybe :: b -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b` -Takes a default value and a Maybe, and returns the Maybe's value -if the Maybe is a Just; the default value otherwise. +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 +the Just's value. Otherwise, the first argument is returned. -See also [`fromMaybe_`](#fromMaybe_) and -[`maybeToNullable`](#maybeToNullable). +See also [`maybe_`](#maybe_) and [`fromMaybe`](#fromMaybe). ```javascript -> S.fromMaybe (0) (S.Just (42)) -42 +> S.maybe (0) (S.prop ('length')) (S.Just ('refuge')) +6 -> S.fromMaybe (0) (S.Nothing) +> S.maybe (0) (S.prop ('length')) (S.Nothing) 0 ``` -#### `fromMaybe_ :: (() -⁠> a) -⁠> Maybe a -⁠> a` +#### `maybe_ :: (() -⁠> b) -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b` -Variant of [`fromMaybe`](#fromMaybe) that takes a thunk so the default -value is only computed if required. +Variant of [`maybe`](#maybe) that takes a thunk so the default value +is only computed if required. ```javascript > function fib(n) { return n <= 1 ? n : fib (n - 2) + fib (n - 1); } -> S.fromMaybe_ (() => fib (30)) (S.Just (1000000)) -1000000 +> S.maybe_ (() => fib (30)) (Math.sqrt) (S.Just (1000000)) +1000 -> S.fromMaybe_ (() => fib (30)) (S.Nothing) +> S.maybe_ (() => fib (30)) (Math.sqrt) (S.Nothing) 832040 ``` -#### `maybeToNullable :: Maybe a -⁠> Nullable a` +#### `fromMaybe :: a -⁠> Maybe a -⁠> a` -Returns the given Maybe's value if the Maybe is a Just; `null` otherwise. -[Nullable][] is defined in [sanctuary-def][]. +Takes a default value and a Maybe, and returns the Maybe's value +if the Maybe is a Just; the default value otherwise. -See also [`fromMaybe`](#fromMaybe). +See also [`maybe`](#maybe), [`fromMaybe_`](#fromMaybe_), and +[`maybeToNullable`](#maybeToNullable). ```javascript -> S.maybeToNullable (S.Just (42)) +> S.fromMaybe (0) (S.Just (42)) 42 -> S.maybeToNullable (S.Nothing) -null -``` - -#### `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 -the Just's value. Otherwise, the first argument is returned. - -See also [`maybe_`](#maybe_). - -```javascript -> S.maybe (0) (S.prop ('length')) (S.Just ('refuge')) -6 - -> S.maybe (0) (S.prop ('length')) (S.Nothing) +> S.fromMaybe (0) (S.Nothing) 0 ``` -#### `maybe_ :: (() -⁠> b) -⁠> (a -⁠> b) -⁠> Maybe a -⁠> b` +#### `fromMaybe_ :: (() -⁠> a) -⁠> Maybe a -⁠> a` -Variant of [`maybe`](#maybe) that takes a thunk so the default value -is only computed if required. +Variant of [`fromMaybe`](#fromMaybe) that takes a thunk so the default +value is only computed if required. ```javascript > function fib(n) { return n <= 1 ? n : fib (n - 2) + fib (n - 1); } -> S.maybe_ (() => fib (30)) (Math.sqrt) (S.Just (1000000)) -1000 +> S.fromMaybe_ (() => fib (30)) (S.Just (1000000)) +1000000 -> S.maybe_ (() => fib (30)) (Math.sqrt) (S.Nothing) +> S.fromMaybe_ (() => fib (30)) (S.Nothing) 832040 ``` -#### `justs :: (Filterable f, Functor f) => f (Maybe a) -⁠> f a` +#### `justs :: (Filterable f, Functor f) => f (Maybe a) -⁠> f a` Discards each element that is Nothing, and unwraps each element that is a Just. Related to Haskell's `catMaybes` function. @@ -1492,7 +1487,7 @@ See also [`lefts`](#lefts) and [`rights`](#rights). ['foo', 'baz'] ``` -#### `mapMaybe :: (Filterable f, Functor f) => (a -⁠> Maybe b) -⁠> f a -⁠> f b` +#### `mapMaybe :: (Filterable f, Functor f) => (a -⁠> Maybe b) -⁠> f a -⁠> f b` Takes a function and a structure, applies the function to each element of the structure, and returns the "successful" results. If the result of @@ -1507,7 +1502,22 @@ if the result is a Just, the Just's value is included. {x: 1, z: 4} ``` -#### `maybeToEither :: a -⁠> Maybe b -⁠> Either a b` +#### `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][]. + +See also [`fromMaybe`](#fromMaybe). + +```javascript +> S.maybeToNullable (S.Just (42)) +42 + +> S.maybeToNullable (S.Nothing) +null +``` + +#### `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. @@ -1530,11 +1540,11 @@ value is of type `b`. The implementation is provided by [sanctuary-either][]. -#### `Either :: TypeRep Either` +#### `Either :: TypeRep Either` Either [type representative][]. -#### `Left :: a -⁠> Either a b` +#### `Left :: a -⁠> Either a b` Constructs a value of type `Either a b` from a value of type `a`. @@ -1543,7 +1553,7 @@ Constructs a value of type `Either a b` from a value of type `a`. Left ('Cannot divide by zero') ``` -#### `Right :: b -⁠> Either a b` +#### `Right :: b -⁠> Either a b` Constructs a value of type `Either a b` from a value of type `b`. @@ -1552,7 +1562,7 @@ Constructs a value of type `Either a b` from a value of type `b`. Right (42) ``` -#### `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. @@ -1564,7 +1574,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. @@ -1576,26 +1586,15 @@ true false ``` -#### `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. - -```javascript -> S.fromEither (0) (S.Right (42)) -42 - -> S.fromEither (0) (S.Left (42)) -0 -``` - -#### `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 is a Left, or the result of applying the second function to the Right's value, if the Either is a Right. +See also [`fromLeft`](#fromLeft) and [`fromRight`](#fromRight). + ```javascript > S.either (S.toUpper) (S.show) (S.Left ('Cannot divide by zero')) 'CANNOT DIVIDE BY ZERO' @@ -1604,7 +1603,53 @@ Right's value, if the Either is a Right. '42' ``` -#### `lefts :: (Filterable f, Functor f) => f (Either a b) -⁠> f a` +#### `fromLeft :: a -⁠> Either a b -⁠> a` + +Takes a default value and an Either, and returns the Left value +if the Either is a Left; the default value otherwise. + +See also [`either`](#either) and [`fromRight`](#fromRight). + +```javascript +> S.fromLeft ('abc') (S.Left ('xyz')) +'xyz' + +> S.fromLeft ('abc') (S.Right (123)) +'abc' +``` + +#### `fromRight :: 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. + +See also [`either`](#either) and [`fromLeft`](#fromLeft). + +```javascript +> S.fromRight (123) (S.Right (789)) +789 + +> S.fromRight (123) (S.Left ('abc')) +123 +``` + +#### `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. + +The behaviour of `fromEither` is likely to change in a future release. +Please use [`fromRight`](#fromRight) instead. + +```javascript +> S.fromEither (0) (S.Right (42)) +42 + +> S.fromEither (0) (S.Left (42)) +0 +``` + +#### `lefts :: (Filterable f, Functor f) => f (Either a b) -⁠> f a` Discards each element that is a Right, and unwraps each element that is a Left. @@ -1616,7 +1661,7 @@ See also [`rights`](#rights). ['foo', 'bar'] ``` -#### `rights :: (Filterable f, Functor f) => f (Either a b) -⁠> f b` +#### `rights :: (Filterable f, Functor f) => f (Either a b) -⁠> f b` Discards each element that is a Left, and unwraps each element that is a Right. @@ -1628,7 +1673,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. @@ -1641,7 +1686,7 @@ Left (0) Right (1) ``` -#### `encase :: Throwing e a b -⁠> a -⁠> Either e b` +#### `encase :: Throwing e a b -⁠> a -⁠> Either e b` Takes a function that may throw and returns a pure function. @@ -1653,7 +1698,7 @@ Right (['foo', 'bar', 'baz']) Left (new SyntaxError ('Unexpected end of JSON input')) ``` -#### `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. @@ -1670,7 +1715,7 @@ Just (42) ### ❑ Logic -#### `and :: Boolean -⁠> Boolean -⁠> Boolean` +#### `and :: Boolean -⁠> Boolean -⁠> Boolean` Boolean "and". @@ -1688,7 +1733,7 @@ false true ``` -#### `or :: Boolean -⁠> Boolean -⁠> Boolean` +#### `or :: Boolean -⁠> Boolean -⁠> Boolean` Boolean "or". @@ -1706,7 +1751,7 @@ true true ``` -#### `not :: Boolean -⁠> Boolean` +#### `not :: Boolean -⁠> Boolean` Boolean "not". @@ -1720,7 +1765,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. @@ -1735,7 +1780,7 @@ true false ``` -#### `boolean :: a -⁠> a -⁠> Boolean -⁠> a` +#### `boolean :: a -⁠> a -⁠> Boolean -⁠> a` Case analysis for the `Boolean` type. `boolean (x) (y) (b)` evaluates to `x` if `b` is `false`; to `y` if `b` is `true`. @@ -1748,7 +1793,7 @@ to `x` if `b` is `false`; to `y` if `b` is `true`. 'yes' ``` -#### `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 @@ -1766,7 +1811,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 @@ -1782,7 +1827,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 @@ -1800,7 +1845,7 @@ See also [`when`](#when) and [`ifElse`](#ifElse). ### ❑ Array -#### `array :: b -⁠> (a -⁠> Array a -⁠> b) -⁠> Array a -⁠> b` +#### `array :: b -⁠> (a -⁠> Array a -⁠> b) -⁠> Array a -⁠> b` Case analysis for the `Array a` type. @@ -1818,7 +1863,7 @@ Nothing Just ([2, 3]) ``` -#### `head :: Foldable f => f a -⁠> Maybe a` +#### `head :: Foldable f => f a -⁠> Maybe a` Returns Just the first element of the given structure if the structure contains at least one element; Nothing otherwise. @@ -1837,7 +1882,7 @@ Just (1) Nothing ``` -#### `last :: Foldable f => f a -⁠> Maybe a` +#### `last :: Foldable f => f a -⁠> Maybe a` Returns Just the last element of the given structure if the structure contains at least one element; Nothing otherwise. @@ -1856,7 +1901,7 @@ Just (3) Nothing ``` -#### `tail :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> Maybe (f a)` +#### `tail :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> Maybe (f a)` Returns Just all but the first of the given structure's elements if the structure contains at least one element; Nothing otherwise. @@ -1875,7 +1920,7 @@ Just (Cons (2) (Cons (3) (Nil))) Nothing ``` -#### `init :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> Maybe (f a)` +#### `init :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> Maybe (f a)` Returns Just all but the last of the given structure's elements if the structure contains at least one element; Nothing otherwise. @@ -1894,7 +1939,7 @@ Just (Cons (1) (Cons (2) (Nil))) Nothing ``` -#### `take :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` +#### `take :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` Returns Just the first N elements of the given structure if N is non-negative and less than or equal to the size of the structure; @@ -1917,7 +1962,7 @@ Nothing Just (Cons (1) (Cons (2) (Cons (3) (Nil)))) ``` -#### `drop :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` +#### `drop :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` Returns Just all but the first N elements of the given structure if N is non-negative and less than or equal to the size of the structure; @@ -1940,7 +1985,7 @@ Nothing Just (Cons (4) (Cons (5) (Nil))) ``` -#### `takeLast :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` +#### `takeLast :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` Returns Just the last N elements of the given structure if N is non-negative and less than or equal to the size of the structure; @@ -1963,7 +2008,7 @@ Nothing Just (Cons (2) (Cons (3) (Cons (4) (Nil)))) ``` -#### `dropLast :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` +#### `dropLast :: (Applicative f, Foldable f, Monoid (f a)) => Integer -⁠> f a -⁠> Maybe (f a)` Returns Just all but the last N elements of the given structure if N is non-negative and less than or equal to the size of the structure; @@ -1986,7 +2031,7 @@ Nothing Just (Cons (1) (Nil)) ``` -#### `takeWhile :: (a -⁠> Boolean) -⁠> Array a -⁠> Array a` +#### `takeWhile :: (a -⁠> Boolean) -⁠> Array a -⁠> Array a` Discards the first element that does not satisfy the predicate, and all subsequent elements. @@ -2001,7 +2046,7 @@ See also [`dropWhile`](#dropWhile). [] ``` -#### `dropWhile :: (a -⁠> Boolean) -⁠> Array a -⁠> Array a` +#### `dropWhile :: (a -⁠> Boolean) -⁠> Array a -⁠> Array a` Retains the first element that does not satisfy the predicate, and all subsequent elements. @@ -2016,7 +2061,7 @@ See also [`takeWhile`](#takeWhile). [3, 3, 3, 7, 6, 3, 5, 4] ``` -#### `size :: Foldable f => f a -⁠> NonNegativeInteger` +#### `size :: Foldable f => f a -⁠> NonNegativeInteger` Returns the number of elements of the given structure. @@ -2043,7 +2088,7 @@ Returns the number of elements of the given structure. 1 ``` -#### `all :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` +#### `all :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` Returns `true` [iff][] all the elements of the structure satisfy the predicate. @@ -2061,7 +2106,7 @@ true false ``` -#### `any :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` +#### `any :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` Returns `true` [iff][] any element of the structure satisfies the predicate. @@ -2079,7 +2124,7 @@ false true ``` -#### `none :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` +#### `none :: Foldable f => (a -⁠> Boolean) -⁠> f a -⁠> Boolean` Returns `true` [iff][] none of the elements of the structure satisfies the predicate. @@ -2105,7 +2150,7 @@ true false ``` -#### `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. @@ -2125,7 +2170,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. @@ -2145,7 +2190,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. @@ -2161,7 +2206,7 @@ See also [`splitOn`](#splitOn) and [`intercalate`](#intercalate). '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` [iff][] the value is an element of the structure. @@ -2191,7 +2236,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 that satisfies the predicate; Nothing if there is no @@ -2207,7 +2252,7 @@ Just (-2) Nothing ``` -#### `intercalate :: (Monoid m, Foldable f) => m -⁠> f m -⁠> m` +#### `intercalate :: (Monoid m, Foldable f) => m -⁠> f m -⁠> m` Curried version of [`Z.intercalate`][]. Concatenates the elements of the given structure, separating each pair of adjacent elements with @@ -2235,7 +2280,7 @@ See also [`joinWith`](#joinWith). [1, 0, 0, 0, 2, 3, 0, 0, 0, 4, 5, 6, 0, 0, 0, 7, 8, 0, 0, 0, 9] ``` -#### `foldMap :: (Monoid m, Foldable f) => TypeRep m -⁠> (a -⁠> m) -⁠> f a -⁠> m` +#### `foldMap :: (Monoid m, Foldable f) => TypeRep m -⁠> (a -⁠> m) -⁠> f a -⁠> m` Curried version of [`Z.foldMap`][]. Deconstructs a foldable by mapping every element to a monoid and concatenating the results. @@ -2248,7 +2293,7 @@ every element to a monoid and concatenating the results. [11, 12, 21, 22, 31, 32] ``` -#### `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 @@ -2265,7 +2310,7 @@ of the function should result in either: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512] ``` -#### `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 @@ -2282,7 +2327,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 @@ -2303,7 +2348,7 @@ Properties: [[2], [-3, 3, 3, 3], [4, -4], [4]] ``` -#### `reverse :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> f a` +#### `reverse :: (Applicative f, Foldable f, Monoid (f a)) => f a -⁠> f a` Reverses the elements of the given structure. @@ -2318,7 +2363,7 @@ Cons (3) (Cons (2) (Cons (1) (Nil))) 'cba' ``` -#### `sort :: (Ord a, Applicative m, Foldable m, Monoid (m a)) => m a -⁠> m a` +#### `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. @@ -2337,7 +2382,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 @@ -2380,7 +2425,7 @@ If descending order is desired, one may use [`Descending`][]: [121, 117, 116, 114, 110, 99, 97, 97, 83] ``` -#### `zip :: Array a -⁠> Array b -⁠> Array (Pair a b)` +#### `zip :: Array a -⁠> Array b -⁠> Array (Pair a b)` Returns an array of pairs of corresponding elements from the given arrays. The length of the resulting array is equal to the length of @@ -2396,7 +2441,7 @@ See also [`zipWith`](#zipWith). [Pair (1) (2), Pair (3) (4)] ``` -#### `zipWith :: (a -⁠> b -⁠> c) -⁠> Array a -⁠> Array b -⁠> Array c` +#### `zipWith :: (a -⁠> b -⁠> c) -⁠> Array a -⁠> Array b -⁠> Array c` Returns the result of combining, pairwise, the given arrays using the given binary function. The length of the resulting array is equal to the @@ -2414,7 +2459,7 @@ See also [`zip`](#zip). ### ❑ Object -#### `prop :: 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 @@ -2428,7 +2473,7 @@ For accessing string map values by key, use [`value`](#value) instead. 1 ``` -#### `props :: 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 @@ -2442,7 +2487,7 @@ instead. 1 ``` -#### `get :: (Any -⁠> Boolean) -⁠> String -⁠> a -⁠> Maybe b` +#### `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 @@ -2467,7 +2512,7 @@ Just ([1, 2, 3]) Nothing ``` -#### `gets :: (Any -⁠> Boolean) -⁠> Array String -⁠> a -⁠> Maybe b` +#### `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 @@ -2494,7 +2539,7 @@ 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`. -#### `value :: String -⁠> StrMap a -⁠> Maybe a` +#### `value :: String -⁠> StrMap a -⁠> Maybe a` Retrieve the value associated with the given key in the given string map. @@ -2514,7 +2559,7 @@ Just (2) Nothing ``` -#### `singleton :: String -⁠> a -⁠> StrMap 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). @@ -2524,7 +2569,7 @@ a single entry (mapping the key to the value). {foo: 42} ``` -#### `insert :: String -⁠> a -⁠> StrMap a -⁠> StrMap a` +#### `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 @@ -2541,7 +2586,7 @@ function. {a: 4, b: 2} ``` -#### `remove :: String -⁠> StrMap a -⁠> StrMap a` +#### `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 @@ -2558,7 +2603,7 @@ function. {} ``` -#### `keys :: StrMap a -⁠> Array String` +#### `keys :: StrMap a -⁠> Array String` Returns the keys of the given string map, in arbitrary order. @@ -2567,7 +2612,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. @@ -2576,7 +2621,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. @@ -2585,7 +2630,7 @@ Returns the key–value pairs of the given string map, in arbitrary order. [Pair ('a') (1), Pair ('b') (2), Pair ('c') (3)] ``` -#### `fromPairs :: Foldable f => f (Pair String a) -⁠> StrMap a` +#### `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 @@ -2601,7 +2646,7 @@ pair takes precedence. ### ❑ Number -#### `negate :: ValidNumber -⁠> ValidNumber` +#### `negate :: ValidNumber -⁠> ValidNumber` Negates its argument. @@ -2613,7 +2658,7 @@ Negates its argument. 42 ``` -#### `add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` +#### `add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` Returns the sum of two (finite) numbers. @@ -2622,7 +2667,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. @@ -2640,7 +2685,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. @@ -2649,7 +2694,7 @@ Takes a finite number `n` and returns the _subtract `n`_ function. [0, 1, 2] ``` -#### `mult :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` +#### `mult :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` Returns the product of two (finite) numbers. @@ -2658,7 +2703,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. @@ -2676,7 +2721,7 @@ Returns the product of the given array of (finite) numbers. 1 ``` -#### `div :: NonZeroFiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` +#### `div :: NonZeroFiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` Takes a non-zero finite number `n` and returns the _divide by `n`_ function. @@ -2686,7 +2731,7 @@ function. [0, 0.5, 1, 1.5] ``` -#### `pow :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` +#### `pow :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` Takes a finite number `n` and returns the _power of `n`_ function. @@ -2698,7 +2743,7 @@ Takes a finite number `n` and returns the _power of `n`_ function. [1, 2, 3, 4, 5] ``` -#### `mean :: Foldable f => f FiniteNumber -⁠> Maybe FiniteNumber` +#### `mean :: Foldable f => f FiniteNumber -⁠> Maybe FiniteNumber` Returns the mean of the given array of (finite) numbers. @@ -2718,7 +2763,7 @@ Nothing ### ❑ Integer -#### `even :: Integer -⁠> Boolean` +#### `even :: Integer -⁠> Boolean` Returns `true` if the given integer is even; `false` if it is odd. @@ -2730,7 +2775,7 @@ true false ``` -#### `odd :: Integer -⁠> Boolean` +#### `odd :: Integer -⁠> Boolean` Returns `true` if the given integer is odd; `false` if it is even. @@ -2744,7 +2789,7 @@ false ### ❑ Parse -#### `parseDate :: String -⁠> Maybe ValidDate` +#### `parseDate :: String -⁠> Maybe ValidDate` Takes a string `s` and returns `Just (new Date (s))` if `new Date (s)` evaluates to a [`ValidDate`][ValidDate] value; Nothing otherwise. @@ -2767,7 +2812,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. @@ -2780,7 +2825,7 @@ Just (-123.45) Nothing ``` -#### `parseInt :: Radix -⁠> 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 @@ -2802,7 +2847,7 @@ Just (255) Nothing ``` -#### `parseJson :: (Any -⁠> Boolean) -⁠> String -⁠> Maybe a` +#### `parseJson :: (Any -⁠> Boolean) -⁠> String -⁠> Maybe a` Takes a predicate and a string that may or may not be valid JSON, and returns Just the result of applying `JSON.parse` to the string *if* the @@ -2824,7 +2869,7 @@ Just ([1, 2, 3]) ### ❑ RegExp -#### `regex :: RegexFlags -⁠> String -⁠> RegExp` +#### `regex :: RegexFlags -⁠> String -⁠> RegExp` Takes a [RegexFlags][] and a pattern, and returns a RegExp. @@ -2833,7 +2878,7 @@ Takes a [RegexFlags][] and a pattern, and returns a RegExp. /:\d+:/g ``` -#### `regexEscape :: String -⁠> String` +#### `regexEscape :: String -⁠> String` Takes a string that may contain regular expression metacharacters, and returns a string with those metacharacters escaped. @@ -2848,7 +2893,7 @@ Properties: '\\-=\\*\\{XYZ\\}\\*=\\-' ``` -#### `test :: RegExp -⁠> String -⁠> Boolean` +#### `test :: RegExp -⁠> String -⁠> Boolean` Takes a pattern and a string, and returns `true` [iff][] the pattern matches the string. @@ -2861,7 +2906,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. @@ -2885,7 +2930,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. @@ -2906,7 +2951,7 @@ See also [`match`](#match). ### ❑ String -#### `toUpper :: String -⁠> String` +#### `toUpper :: String -⁠> String` Returns the upper-case equivalent of its argument. @@ -2917,7 +2962,7 @@ See also [`toLower`](#toLower). 'ABC DEF 123' ``` -#### `toLower :: String -⁠> String` +#### `toLower :: String -⁠> String` Returns the lower-case equivalent of its argument. @@ -2928,7 +2973,7 @@ See also [`toUpper`](#toUpper). 'abc def 123' ``` -#### `trim :: String -⁠> String` +#### `trim :: String -⁠> String` Strips leading and trailing whitespace characters. @@ -2937,7 +2982,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 @@ -2953,7 +2998,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 @@ -2969,7 +3014,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). @@ -2981,7 +3026,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. @@ -2993,7 +3038,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'`). @@ -3006,7 +3051,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. @@ -3018,7 +3063,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. @@ -3030,7 +3075,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. @@ -3064,13 +3109,13 @@ See also [`splitOn`](#splitOn). [Haskell]: https://www.haskell.org/ [Kleisli]: https://en.wikipedia.org/wiki/Kleisli_category [Maybe]: #section:maybe -[Nullable]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.21.1#Nullable +[Nullable]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0#Nullable [PureScript]: http://www.purescript.org/ [Ramda]: https://ramdajs.com/ -[RegexFlags]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.21.1#RegexFlags +[RegexFlags]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0#RegexFlags [Semigroupoid]: https://github.com/fantasyland/fantasy-land/tree/v4.0.1#semigroupoid -[ValidDate]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.21.1#ValidDate -[`$.test`]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.21.1#test +[ValidDate]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0#ValidDate +[`$.test`]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0#test [`Descending`]: https://github.com/sanctuary-js/sanctuary-descending/tree/v2.1.0#Descending [`R.__`]: https://ramdajs.com/docs/#__ [`R.bind`]: https://ramdajs.com/docs/#bind @@ -3118,7 +3163,7 @@ See also [`splitOn`](#splitOn). [ramda/ramda#683]: https://github.com/ramda/ramda/issues/683 [ramda/ramda#1413]: https://github.com/ramda/ramda/issues/1413 [ramda/ramda#1419]: https://github.com/ramda/ramda/pull/1419 -[sanctuary-def]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.21.1 +[sanctuary-def]: https://github.com/sanctuary-js/sanctuary-def/tree/v0.22.0 [sanctuary-either]: https://github.com/sanctuary-js/sanctuary-either/tree/v2.1.0 [sanctuary-maybe]: https://github.com/sanctuary-js/sanctuary-maybe/tree/v2.1.0 [sanctuary-pair]: https://github.com/sanctuary-js/sanctuary-pair/tree/v2.1.0 diff --git a/dist/bundle.js b/dist/bundle.js index 9aeda6a5..6197a59e 100644 --- a/dist/bundle.js +++ b/dist/bundle.js @@ -1,4 +1,4 @@ -// sanctuary@3.0.0 with bundled dependencies: +// sanctuary@3.1.0 with bundled dependencies: // // - sanctuary-show@2.0.0 // - sanctuary-type-identifiers@3.0.0 @@ -6,7 +6,7 @@ // - sanctuary-either@2.1.0 // - sanctuary-maybe@2.1.0 // - sanctuary-pair@2.1.0 -// - sanctuary-def@0.21.1 +// - sanctuary-def@0.22.0 //. # sanctuary-show //. @@ -4296,9 +4296,11 @@ //. const env = $.env.concat ([List ($.Unknown)]); //. ``` //. -//. The next step is to define a `def` function for the environment: +//. The next step is to define a `def` function for the environment using +//. `$.create`: //. //. ```javascript +//. // def :: String -> StrMap (Array TypeClass) -> Array Type -> Function -> Function //. const def = $.create ({checkTypes: true, env}); //. ``` //. @@ -4307,6 +4309,7 @@ //. during development. For example: //. //. ```javascript +//. // def :: String -> StrMap (Array TypeClass) -> Array Type -> Function -> Function //. const def = $.create ({ //. checkTypes: process.env.NODE_ENV === 'development', //. env, @@ -4318,10 +4321,10 @@ //. ```javascript //. // add :: Number -> Number -> Number //. const add = -//. def ('add') -//. ({}) -//. ([$.Number, $.Number, $.Number]) -//. (x => y => x + y); +//. def ('add') // name +//. ({}) // type-class constraints +//. ([$.Number, $.Number, $.Number]) // input and output types +//. (x => y => x + y); // implementation //. ``` //. //. `[$.Number, $.Number, $.Number]` specifies that `add` takes two arguments @@ -4732,7 +4735,7 @@ // functionUrl :: String -> String function functionUrl(name) { - var version = '0.21.1'; // updated programmatically + var version = '0.22.0'; // updated programmatically return 'https://github.com/sanctuary-js/sanctuary-def/tree/v' + version + '#' + name; } @@ -4847,6 +4850,18 @@ ([]) (typeofEq ('boolean')); + //# Buffer :: Type + //. + //. Type comprising every [Buffer][] object. + var Buffer_ = NullaryTypeWithUrl + ('Buffer') + ([]) + (function(x) { + return typeof Buffer !== 'undefined' && + // eslint-disable-next-line no-undef + Buffer.isBuffer (x); + }); + //# Date :: Type //. //. Type comprising every Date value. @@ -5286,6 +5301,7 @@ //. - [Array](#Array) ([Unknown][]) //. - [Array2](#Array2) ([Unknown][]) ([Unknown][]) //. - [Boolean](#Boolean) + //. - [Buffer](#Buffer) //. - [Date](#Date) //. - [Descending](#Descending) ([Unknown][]) //. - [Either](#Either) ([Unknown][]) ([Unknown][]) @@ -5314,6 +5330,7 @@ Array_ (Unknown), Array2 (Unknown) (Unknown), Boolean_, + Buffer_, Date_, Descending (Unknown), Either_ (Unknown) (Unknown), @@ -7055,6 +7072,7 @@ Array1: fromUncheckedUnaryType (Array1), Array2: fromUncheckedBinaryType (Array2), Boolean: Boolean_, + Buffer: Buffer_, Date: Date_, ValidDate: ValidDate, Descending: fromUncheckedUnaryType (Descending), @@ -7206,6 +7224,7 @@ })); +//. [Buffer]: https://nodejs.org/api/buffer.html#buffer_buffer //. [Descending]: v:sanctuary-js/sanctuary-descending //. [Either]: v:sanctuary-js/sanctuary-either //. [FL:Semigroup]: https://github.com/fantasyland/fantasy-land#semigroup @@ -7569,17 +7588,11 @@ //. //. `npm install sanctuary` will install Sanctuary for use in Node.js. //. -//. To add Sanctuary to a website, first run the following command, replacing -//. `X.Y.Z` with a version number greater than or equal to `2.0.2`: -//. -//. ```console -//. $ curl https://raw.githubusercontent.com/sanctuary-js/sanctuary/vX.Y.Z/dist/bundle.js >vendor/sanctuary-bundle.js -//. ``` -//. -//. Then reference the bundle from __index.html__: +//. To add Sanctuary to a website, add the following ` +//. //. ``` //. //. Optionally, define aliases for various modules: @@ -7846,6 +7859,7 @@ //. . $.Array ($.Unknown), //. . $.Array2 ($.Unknown) ($.Unknown), //. . $.Boolean, + //. . $.Buffer, //. . $.Date, //. . $.Descending ($.Unknown), //. . $.Either ($.Unknown) ($.Unknown), @@ -8358,10 +8372,15 @@ //. > S.flip (Cons (Math.floor) (Cons (Math.ceil) (Nil))) (1.5) //. Cons (1) (Cons (2) (Nil)) //. ``` + function flip(functor) { + return function(x) { + return Z.flip (functor, x); + }; + } _.flip = { consts: {f: [Z.Functor]}, types: [f ($.Fn (a) (b)), a, f (b)], - impl: curry2 (Z.flip) + impl: flip }; //# bimap :: Bifunctor f => (a -> b) -> (c -> d) -> f a c -> f b d @@ -8478,6 +8497,8 @@ //. 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 @@ -8496,10 +8517,28 @@ } _.reduce = { consts: {f: [Z.Foldable]}, - types: [$.Fn (a) ($.Fn (b) (a)), a, f (b), a], + types: [$.Fn (b) ($.Fn (a) (b)), b, f (a), b], impl: reduce }; + //# reduce_ :: Foldable f => (a -> b -> b) -> b -> f a -> b + //. + //. Variant of [`reduce`](#reduce) that takes a reducing function with + //. arguments flipped. + //. + //. ```javascript + //. > S.reduce_ (S.append) ([]) (Cons (1) (Cons (2) (Cons (3) (Nil)))) + //. [1, 2, 3] + //. + //. > S.reduce_ (S.prepend) ([]) (Cons (1) (Cons (2) (Cons (3) (Nil)))) + //. [3, 2, 1] + //. ``` + _.reduce_ = { + consts: {f: [Z.Foldable]}, + types: [$.Fn (a) ($.Fn (b) (b)), b, f (a), b], + impl: B (reduce) (flip) + }; + //# traverse :: (Applicative f, Traversable t) => TypeRep f -> (a -> f b) -> t a -> f (t b) //. //. Curried version of [`Z.traverse`][]. @@ -9297,77 +9336,13 @@ impl: isJust }; - //# 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. - //. - //. See also [`fromMaybe_`](#fromMaybe_) and - //. [`maybeToNullable`](#maybeToNullable). - //. - //. ```javascript - //. > S.fromMaybe (0) (S.Just (42)) - //. 42 - //. - //. > S.fromMaybe (0) (S.Nothing) - //. 0 - //. ``` - _.fromMaybe = { - consts: {}, - types: [a, $.Maybe (a), a], - impl: C (maybe) (I) - }; - - //# fromMaybe_ :: (() -> a) -> Maybe a -> a - //. - //. Variant of [`fromMaybe`](#fromMaybe) that takes a thunk so the default - //. value is only computed if required. - //. - //. ```javascript - //. > function fib(n) { return n <= 1 ? n : fib (n - 2) + fib (n - 1); } - //. - //. > S.fromMaybe_ (() => fib (30)) (S.Just (1000000)) - //. 1000000 - //. - //. > S.fromMaybe_ (() => fib (30)) (S.Nothing) - //. 832040 - //. ``` - _.fromMaybe_ = { - consts: {}, - types: [$.Thunk (a), $.Maybe (a), a], - impl: C (maybe_) (I) - }; - - //# 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][]. - //. - //. See also [`fromMaybe`](#fromMaybe). - //. - //. ```javascript - //. > S.maybeToNullable (S.Just (42)) - //. 42 - //. - //. > S.maybeToNullable (S.Nothing) - //. null - //. ``` - function maybeToNullable(maybe) { - return maybe.isJust ? maybe.value : null; - } - _.maybeToNullable = { - consts: {}, - types: [$.Maybe (a), $.Nullable (a)], - impl: maybeToNullable - }; - //# 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 //. the Just's value. Otherwise, the first argument is returned. //. - //. See also [`maybe_`](#maybe_). + //. See also [`maybe_`](#maybe_) and [`fromMaybe`](#fromMaybe). //. //. ```javascript //. > S.maybe (0) (S.prop ('length')) (S.Just ('refuge')) @@ -9416,6 +9391,47 @@ impl: maybe_ }; + //# 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. + //. + //. See also [`maybe`](#maybe), [`fromMaybe_`](#fromMaybe_), and + //. [`maybeToNullable`](#maybeToNullable). + //. + //. ```javascript + //. > S.fromMaybe (0) (S.Just (42)) + //. 42 + //. + //. > S.fromMaybe (0) (S.Nothing) + //. 0 + //. ``` + _.fromMaybe = { + consts: {}, + types: [a, $.Maybe (a), a], + impl: C (maybe) (I) + }; + + //# fromMaybe_ :: (() -> a) -> Maybe a -> a + //. + //. Variant of [`fromMaybe`](#fromMaybe) that takes a thunk so the default + //. value is only computed if required. + //. + //. ```javascript + //. > function fib(n) { return n <= 1 ? n : fib (n - 2) + fib (n - 1); } + //. + //. > S.fromMaybe_ (() => fib (30)) (S.Just (1000000)) + //. 1000000 + //. + //. > S.fromMaybe_ (() => fib (30)) (S.Nothing) + //. 832040 + //. ``` + _.fromMaybe_ = { + consts: {}, + types: [$.Thunk (a), $.Maybe (a), a], + impl: C (maybe_) (I) + }; + //# justs :: (Filterable f, Functor f) => f (Maybe a) -> f a //. //. Discards each element that is Nothing, and unwraps each element that is @@ -9456,6 +9472,29 @@ impl: B (B (justs)) (map) }; + //# 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][]. + //. + //. See also [`fromMaybe`](#fromMaybe). + //. + //. ```javascript + //. > S.maybeToNullable (S.Just (42)) + //. 42 + //. + //. > S.maybeToNullable (S.Nothing) + //. null + //. ``` + function maybeToNullable(maybe) { + return maybe.isJust ? maybe.value : null; + } + _.maybeToNullable = { + consts: {}, + types: [$.Maybe (a), $.Nullable (a)], + impl: maybeToNullable + }; + //# maybeToEither :: a -> Maybe b -> Either a b //. //. Converts a Maybe to an Either. Nothing becomes a Left (containing the @@ -9559,27 +9598,6 @@ impl: isRight }; - //# 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. - //. - //. ```javascript - //. > S.fromEither (0) (S.Right (42)) - //. 42 - //. - //. > S.fromEither (0) (S.Left (42)) - //. 0 - //. ``` - function fromEither(x) { - return either (K (x)) (I); - } - _.fromEither = { - consts: {}, - types: [b, $.Either (a) (b), b], - impl: fromEither - }; - //# either :: (a -> c) -> (b -> c) -> Either a b -> c //. //. Takes two functions and an Either, and returns the result of @@ -9587,6 +9605,8 @@ //. is a Left, or the result of applying the second function to the //. Right's value, if the Either is a Right. //. + //. See also [`fromLeft`](#fromLeft) and [`fromRight`](#fromRight). + //. //. ```javascript //. > S.either (S.toUpper) (S.show) (S.Left ('Cannot divide by zero')) //. 'CANNOT DIVIDE BY ZERO' @@ -9607,6 +9627,76 @@ impl: either }; + //# fromLeft :: a -> Either a b -> a + //. + //. Takes a default value and an Either, and returns the Left value + //. if the Either is a Left; the default value otherwise. + //. + //. See also [`either`](#either) and [`fromRight`](#fromRight). + //. + //. ```javascript + //. > S.fromLeft ('abc') (S.Left ('xyz')) + //. 'xyz' + //. + //. > S.fromLeft ('abc') (S.Right (123)) + //. 'abc' + //. ``` + function fromLeft(x) { + return either (I) (K (x)); + } + _.fromLeft = { + consts: {}, + types: [a, $.Either (a) (b), a], + impl: fromLeft + }; + + //# fromRight :: 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. + //. + //. See also [`either`](#either) and [`fromLeft`](#fromLeft). + //. + //. ```javascript + //. > S.fromRight (123) (S.Right (789)) + //. 789 + //. + //. > S.fromRight (123) (S.Left ('abc')) + //. 123 + //. ``` + function fromRight(x) { + return either (K (x)) (I); + } + _.fromRight = { + consts: {}, + types: [b, $.Either (a) (b), b], + impl: fromRight + }; + + //# 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. + //. + //. The behaviour of `fromEither` is likely to change in a future release. + //. Please use [`fromRight`](#fromRight) instead. + //. + //. ```javascript + //. > S.fromEither (0) (S.Right (42)) + //. 42 + //. + //. > S.fromEither (0) (S.Left (42)) + //. 0 + //. ``` + function fromEither(x) { + return either (K (x)) (I); + } + _.fromEither = { + consts: {}, + types: [b, $.Either (a) (b), b], + impl: fromEither + }; + //# lefts :: (Filterable f, Functor f) => f (Either a b) -> f a //. //. Discards each element that is a Right, and unwraps each element that is diff --git a/package.json b/package.json index 57286e67..5d8f53d8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sanctuary", - "version": "3.0.0", + "version": "3.1.0", "description": "Refuge from unsafe JavaScript", "license": "MIT", "repository": {