From 69cd5c94aa9399c9153450afc7e99489df3b672f Mon Sep 17 00:00:00 2001 From: David Chambers Date: Sun, 17 Feb 2019 09:59:58 +0100 Subject: [PATCH] Version 0.15.1 --- LICENSE | 2 +- README.md | 358 ++++++++++++++++++++++++++------------------------- package.json | 2 +- 3 files changed, 187 insertions(+), 175 deletions(-) diff --git a/LICENSE b/LICENSE index ffd105b7..5e1249c8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2018 Sanctuary +Copyright (c) 2019 Sanctuary Copyright (c) 2016 Plaid Technologies, Inc. Permission is hereby granted, free of charge, to any person diff --git a/README.md b/README.md index 23608244..43f1e839 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,14 @@ write: Sanctuary is designed to work in Node.js and in ES5-compatible browsers. +## Folktale + +[Folktale][], like Sanctuary, is a standard library for functional +programming in JavaScript. It is well designed and well documented. +Whereas Sanctuary treats JavaScript as a member of the ML language +family, Folktale embraces JavaScript's object-oriented programming +model. Programming with Folktale resembles programming with Scala. + ## Ramda [Ramda][] provides several functions which return problematic values @@ -85,7 +93,7 @@ Sanctuary performs rigorous [type checking][] of inputs and outputs, and throws a descriptive error if a type error is encountered. This allows bugs to be caught and fixed early in the development cycle. -Ramda operates on the [garbage in, garbage out][GIGO] principal. Functions +Ramda operates on the [garbage in, garbage out][GIGO] principle. Functions are documented to take arguments of particular types, but these invariants are not enforced. The problem with this approach in a language as permissive as JavaScript is that there's no guarantee that garbage input @@ -335,7 +343,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 @@ -388,7 +396,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). @@ -428,7 +436,7 @@ is a reference to `env`). Useful in conjunction with [`create`](#create). . $.ValidNumber ] ``` -#### `unchecked :: Module` +#### `unchecked :: Module` A complete Sanctuary module which performs no type checking. This is useful as it permits operations which Sanctuary's type checking would @@ -450,7 +458,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. @@ -462,7 +470,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. @@ -477,7 +485,7 @@ false ### Showable -#### `show :: Any -⁠> String` +#### `show :: Any -⁠> String` Alias of [`show`][]. @@ -499,7 +507,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`][] which requires two arguments of the same type. @@ -522,7 +530,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`][]. @@ -532,7 +540,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`][]. @@ -542,7 +550,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`][]. @@ -552,7 +560,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`][]. @@ -562,7 +570,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`][]). @@ -579,7 +587,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`][]). @@ -596,7 +604,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`][]. @@ -605,7 +613,7 @@ new Date ('2000-01-01') 42 ``` -#### `concat :: Semigroup a => a -⁠> a -⁠> a` +#### `concat :: Semigroup a => a -⁠> a -⁠> a` Curried version of [`Z.concat`][]. @@ -626,7 +634,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`][]. @@ -644,7 +652,7 @@ Sum (42) Sum (0) ``` -#### `invert :: Group g => g -⁠> g` +#### `invert :: Group g => g -⁠> g` [Type-safe][sanctuary-def] version of [`Z.invert`][]. @@ -653,7 +661,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 which does not satisfy the predicate. @@ -677,7 +685,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 which satisfies the predicate. @@ -701,7 +709,7 @@ Just (0) Nothing ``` -#### `takeWhile :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` +#### `takeWhile :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` Curried version of [`Z.takeWhile`][]. Discards the first element which does not satisfy the predicate, and all subsequent elements. @@ -716,7 +724,7 @@ See also [`dropWhile`](#dropWhile). [] ``` -#### `dropWhile :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` +#### `dropWhile :: Filterable f => (a -⁠> Boolean) -⁠> f a -⁠> f a` Curried version of [`Z.dropWhile`][]. Retains the first element which does not satisfy the predicate, and all subsequent elements. @@ -731,7 +739,7 @@ See also [`takeWhile`](#takeWhile). [3, 3, 3, 7, 6, 3, 5, 4] ``` -#### `map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b` +#### `map :: Functor f => (a -⁠> b) -⁠> f a -⁠> f b` Curried version of [`Z.map`][]. @@ -767,7 +775,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. @@ -796,7 +804,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`][]. @@ -811,7 +819,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. @@ -827,7 +835,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`][]. @@ -836,7 +844,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`][]. @@ -854,7 +862,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`][]. @@ -869,7 +877,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 @@ -887,7 +895,7 @@ otherwise. [5, 4, 3, 2, 1] ``` -#### `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`][]. @@ -911,7 +919,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)`. @@ -933,7 +941,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`][]. @@ -963,7 +971,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. @@ -982,7 +990,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. @@ -995,7 +1003,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 `(<*)` @@ -1011,7 +1019,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 `(*>)` @@ -1027,7 +1035,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`][]. @@ -1045,7 +1053,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`][]. @@ -1063,7 +1071,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. @@ -1094,7 +1102,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 @@ -1108,7 +1116,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`][]. @@ -1120,7 +1128,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. @@ -1139,7 +1147,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`][]. @@ -1148,7 +1156,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`][]. @@ -1159,7 +1167,7 @@ Just (Just (1)) ### Combinator -#### `I :: a -⁠> a` +#### `I :: a -⁠> a` The I combinator. Returns its argument. Equivalent to Haskell's `id` function. @@ -1169,7 +1177,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. @@ -1182,7 +1190,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 @@ -1198,7 +1206,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. @@ -1207,7 +1215,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. @@ -1220,7 +1228,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. @@ -1233,7 +1241,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. @@ -1252,7 +1260,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`][]. @@ -1269,7 +1277,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 @@ -1283,7 +1291,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 which return values with a [Chain][], and a value of that Chain, and returns the result @@ -1298,7 +1306,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))`. @@ -1317,11 +1325,11 @@ contains exactly two values: one of type `a`; one of type `b`. The implementation is provided by [sanctuary-pair][]. -#### `PairType :: Type -⁠> Type -⁠> Type` +#### `PairType :: Type -⁠> Type -⁠> Type` A [`BinaryType`][BinaryType] for use with [sanctuary-def][]. -#### `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][]. @@ -1331,7 +1339,7 @@ Pair [type representative][]. Pair ('foo') (42) ``` -#### `fst :: Pair a b -⁠> a` +#### `fst :: Pair a b -⁠> a` `fst (Pair (x) (y))` is equivalent to `x`. @@ -1340,7 +1348,7 @@ Pair ('foo') (42) 'foo' ``` -#### `snd :: Pair a b -⁠> b` +#### `snd :: Pair a b -⁠> b` `snd (Pair (x) (y))` is equivalent to `y`. @@ -1349,7 +1357,7 @@ Pair ('foo') (42) 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)`. @@ -1365,15 +1373,15 @@ either Nothing (the empty value) or a Just whose value is of type `a`. The implementation is provided by [sanctuary-maybe][]. -#### `MaybeType :: Type -⁠> Type` +#### `MaybeType :: Type -⁠> Type` A [`UnaryType`][UnaryType] for use with [sanctuary-def][]. -#### `Maybe :: TypeRep Maybe` +#### `Maybe :: TypeRep Maybe` Maybe [type representative][]. -#### `Nothing :: Maybe a` +#### `Nothing :: Maybe a` The empty value of type `Maybe a`. @@ -1382,7 +1390,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`. @@ -1391,7 +1399,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. @@ -1403,7 +1411,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. @@ -1415,7 +1423,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. @@ -1431,7 +1439,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. @@ -1446,7 +1454,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][]. @@ -1461,7 +1469,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. @@ -1474,7 +1482,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 @@ -1490,7 +1498,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. @@ -1505,7 +1513,7 @@ is only computed if required. 832040 ``` -#### `justs :: (Filterable f, Functor f) => f (Maybe a) -⁠> f a` +#### `justs :: (Filterable f, Functor f) => f (Maybe a) -⁠> f a` Discards each element which is Nothing, and unwraps each element which is a Just. Related to Haskell's `catMaybes` function. @@ -1517,7 +1525,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 @@ -1532,7 +1540,7 @@ if the result is a Just, the Just's value is included. {x: 1, z: 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, @@ -1549,15 +1557,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). -#### `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). -#### `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. @@ -1580,15 +1588,15 @@ value is of type `b`. The implementation is provided by [sanctuary-either][]. -#### `EitherType :: Type -⁠> Type -⁠> Type` +#### `EitherType :: Type -⁠> Type -⁠> Type` A [`BinaryType`][BinaryType] for use with [sanctuary-def][]. -#### `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`. @@ -1597,7 +1605,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`. @@ -1606,7 +1614,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. @@ -1618,7 +1626,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. @@ -1630,7 +1638,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. @@ -1643,7 +1651,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 @@ -1667,7 +1675,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 @@ -1682,7 +1690,7 @@ Right's value, if the Either is a Right. '42' ``` -#### `lefts :: (Filterable f, Functor f) => f (Either a b) -⁠> f a` +#### `lefts :: (Filterable f, Functor f) => f (Either a b) -⁠> f a` Discards each element which is a Right, and unwraps each element which is a Left. @@ -1694,7 +1702,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 which is a Left, and unwraps each element which is a Right. @@ -1706,7 +1714,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. @@ -1719,7 +1727,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. @@ -1740,15 +1748,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). -#### `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). -#### `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. @@ -1765,7 +1773,7 @@ Just (42) ### Logic -#### `and :: Boolean -⁠> Boolean -⁠> Boolean` +#### `and :: Boolean -⁠> Boolean -⁠> Boolean` Boolean "and". @@ -1783,7 +1791,7 @@ false true ``` -#### `or :: Boolean -⁠> Boolean -⁠> Boolean` +#### `or :: Boolean -⁠> Boolean -⁠> Boolean` Boolean "or". @@ -1801,7 +1809,7 @@ true true ``` -#### `not :: Boolean -⁠> Boolean` +#### `not :: Boolean -⁠> Boolean` Boolean "not". @@ -1815,7 +1823,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. @@ -1830,7 +1838,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 @@ -1848,7 +1856,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 @@ -1864,7 +1872,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 @@ -1880,7 +1888,7 @@ See also [`when`](#when) and [`ifElse`](#ifElse). -1 ``` -#### `allPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean` +#### `allPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean` Takes a structure containing zero or more predicates, and a value of any type. Returns `true` [iff][] the value satisfies all of the @@ -1895,7 +1903,7 @@ true false ``` -#### `anyPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean` +#### `anyPass :: Foldable f => f (a -⁠> Boolean) -⁠> a -⁠> Boolean` Takes a structure containing zero or more predicates, and a value of any type. Returns `true` [iff][] the value satisfies any of the @@ -1912,7 +1920,7 @@ false ### Array -#### `slice :: Integer -⁠> Integer -⁠> Array a -⁠> Maybe (Array a)` +#### `slice :: Integer -⁠> Integer -⁠> Array a -⁠> Maybe (Array a)` Takes a start index `i`, an end index `j`, and an array, and returns Just the `[i,j)` slice of the array if possible; Nothing otherwise. @@ -1932,7 +1940,7 @@ Just (['c', 'd']) Nothing ``` -#### `at :: Integer -⁠> Array a -⁠> Maybe a` +#### `at :: Integer -⁠> Array a -⁠> Maybe a` Returns Just the element of the given array at the specified index if the index is within the array's bounds; Nothing otherwise. A negative @@ -1949,7 +1957,7 @@ Nothing Just ('d') ``` -#### `head :: Array a -⁠> Maybe a` +#### `head :: Array a -⁠> Maybe a` Returns Just the first element of the given array if the array contains at least one element; Nothing otherwise. @@ -1962,7 +1970,7 @@ Just (1) Nothing ``` -#### `last :: Array a -⁠> Maybe a` +#### `last :: Array a -⁠> Maybe a` Returns Just the last element of the given array if the array contains at least one element; Nothing otherwise. @@ -1975,7 +1983,7 @@ Just (3) Nothing ``` -#### `tail :: Array a -⁠> Maybe (Array a)` +#### `tail :: Array a -⁠> Maybe (Array a)` Returns Just all but the first of the given array's elements if the array contains at least one element; Nothing otherwise. @@ -1988,7 +1996,7 @@ Just ([2, 3]) Nothing ``` -#### `init :: Array a -⁠> Maybe (Array a)` +#### `init :: Array a -⁠> Maybe (Array a)` Returns Just all but the last of the given array's elements if the array contains at least one element; Nothing otherwise. @@ -2001,7 +2009,7 @@ Just ([1, 2]) Nothing ``` -#### `take :: Integer -⁠> Array a -⁠> Maybe (Array a)` +#### `take :: Integer -⁠> Array a -⁠> Maybe (Array a)` Returns Just the first N elements of the given array if N is greater than or equal to zero and less than or equal to the length of the array; @@ -2018,7 +2026,7 @@ Just (['a', 'b', 'c', 'd', 'e']) Nothing ``` -#### `takeLast :: Integer -⁠> Array a -⁠> Maybe (Array a)` +#### `takeLast :: Integer -⁠> Array a -⁠> Maybe (Array a)` Returns Just the last N elements of the given array if N is greater than or equal to zero and less than or equal to the length of the array; @@ -2035,7 +2043,7 @@ Just (['a', 'b', 'c', 'd', 'e']) Nothing ``` -#### `drop :: Integer -⁠> Array a -⁠> Maybe (Array a)` +#### `drop :: Integer -⁠> Array a -⁠> Maybe (Array a)` Returns Just all but the first N elements of the given array if N is greater than or equal to zero and less than or equal to the length of @@ -2052,7 +2060,7 @@ Just ([]) Nothing ``` -#### `dropLast :: Integer -⁠> Array a -⁠> Maybe (Array a)` +#### `dropLast :: Integer -⁠> Array a -⁠> Maybe (Array a)` Returns Just all but the last N elements of the given array if N is greater than or equal to zero and less than or equal to the length of @@ -2069,7 +2077,7 @@ Just ([]) Nothing ``` -#### `size :: Foldable f => f a -⁠> Integer` +#### `size :: Foldable f => f a -⁠> Integer` Returns the number of elements of the given structure. @@ -2096,7 +2104,7 @@ Returns the number of elements of the given structure. 1 ``` -#### `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. @@ -2116,7 +2124,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. @@ -2136,7 +2144,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. @@ -2152,7 +2160,7 @@ 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` [iff][] the value is an element of the structure. @@ -2182,7 +2190,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 @@ -2198,7 +2206,7 @@ Just (-2) Nothing ``` -#### `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. @@ -2206,9 +2214,12 @@ every element to a monoid and concatenating the results. ```javascript > S.foldMap (String) (f => f.name) ([Math.sin, Math.cos, Math.tan]) 'sincostan' + +> S.foldMap (Array) (x => [x + 1, x + 2]) ([10, 20, 30]) +[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 @@ -2221,11 +2232,11 @@ of the function should result in either: the array and the function is applied to the second element. ```javascript -> S.unfoldr (n => n < 5 ? S.Just (S.Pair (n) (n + 1)) : S.Nothing) (1) -[1, 2, 3, 4] +> S.unfoldr (n => n < 1000 ? S.Just (S.Pair (n) (2 * n)) : S.Nothing) (1) +[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 @@ -2242,7 +2253,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 @@ -2263,7 +2274,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. @@ -2278,7 +2289,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. @@ -2297,7 +2308,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 @@ -2340,7 +2351,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 @@ -2356,7 +2367,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 @@ -2374,7 +2385,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 @@ -2387,7 +2398,7 @@ For accessing properties of uncertain objects, use [`get`](#get) 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 @@ -2401,7 +2412,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 @@ -2426,7 +2437,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 @@ -2453,7 +2464,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`. -#### `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). @@ -2463,7 +2474,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 @@ -2480,7 +2491,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 @@ -2497,7 +2508,7 @@ function. {} ``` -#### `keys :: StrMap a -⁠> Array String` +#### `keys :: StrMap a -⁠> Array String` Returns the keys of the given string map, in arbitrary order. @@ -2506,7 +2517,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. @@ -2515,7 +2526,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. @@ -2524,7 +2535,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 @@ -2540,7 +2551,7 @@ pair takes precedence. ### Number -#### `negate :: ValidNumber -⁠> ValidNumber` +#### `negate :: ValidNumber -⁠> ValidNumber` Negates its argument. @@ -2552,7 +2563,7 @@ Negates its argument. 42 ``` -#### `add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` +#### `add :: FiniteNumber -⁠> FiniteNumber -⁠> FiniteNumber` Returns the sum of two (finite) numbers. @@ -2561,7 +2572,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. @@ -2579,7 +2590,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. @@ -2588,7 +2599,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. @@ -2597,7 +2608,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. @@ -2615,7 +2626,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. @@ -2625,7 +2636,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. @@ -2637,7 +2648,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. @@ -2657,7 +2668,7 @@ Nothing ### Integer -#### `even :: Integer -⁠> Boolean` +#### `even :: Integer -⁠> Boolean` Returns `true` if the given integer is even; `false` if it is odd. @@ -2669,7 +2680,7 @@ true false ``` -#### `odd :: Integer -⁠> Boolean` +#### `odd :: Integer -⁠> Boolean` Returns `true` if the given integer is odd; `false` if it is even. @@ -2683,7 +2694,7 @@ false ### Parse -#### `parseDate :: String -⁠> Maybe ValidDate` +#### `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. @@ -2696,7 +2707,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. @@ -2709,7 +2720,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 @@ -2731,7 +2742,7 @@ Just (255) Nothing ``` -#### `parseJson :: (Any -⁠> Boolean) -⁠> String -⁠> Maybe a` +#### `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 @@ -2753,7 +2764,7 @@ Just ([1, 2, 3]) ### RegExp -#### `regex :: RegexFlags -⁠> String -⁠> RegExp` +#### `regex :: RegexFlags -⁠> String -⁠> RegExp` Takes a [RegexFlags][] and a pattern, and returns a RegExp. @@ -2762,7 +2773,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. @@ -2777,7 +2788,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. @@ -2790,7 +2801,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. @@ -2814,7 +2825,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. @@ -2835,7 +2846,7 @@ See also [`match`](#match). ### String -#### `toUpper :: String -⁠> String` +#### `toUpper :: String -⁠> String` Returns the upper-case equivalent of its argument. @@ -2846,7 +2857,7 @@ See also [`toLower`](#toLower). 'ABC DEF 123' ``` -#### `toLower :: String -⁠> String` +#### `toLower :: String -⁠> String` Returns the lower-case equivalent of its argument. @@ -2857,7 +2868,7 @@ See also [`toUpper`](#toUpper). 'abc def 123' ``` -#### `trim :: String -⁠> String` +#### `trim :: String -⁠> String` Strips leading and trailing whitespace characters. @@ -2866,7 +2877,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 @@ -2882,7 +2893,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 @@ -2898,7 +2909,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). @@ -2910,7 +2921,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. @@ -2922,7 +2933,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'`). @@ -2935,7 +2946,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. @@ -2947,7 +2958,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. @@ -2959,7 +2970,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. @@ -2988,6 +2999,7 @@ See also [`splitOn`](#splitOn). [Either]: #either-type [Fantasy Land]: https://github.com/fantasyland/fantasy-land/tree/v3.5.0 [Foldable]: https://github.com/fantasyland/fantasy-land/tree/v3.5.0#foldable +[Folktale]: https://folktale.origamitower.com/ [GIGO]: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out [Haskell]: https://www.haskell.org/ [Kleisli]: https://en.wikipedia.org/wiki/Kleisli_category diff --git a/package.json b/package.json index d9b12327..0ae69800 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sanctuary", - "version": "0.15.0", + "version": "0.15.1", "description": "Refuge from unsafe JavaScript", "license": "MIT", "repository": {