diff --git a/README.md b/README.md index 3ffc85de..e3e2583f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ If `words` is `[]` we'll get a familiar error at run-time: Sanctuary gives us a fighting chance of avoiding such errors. We might write: - R.map(R.toUpper, S.head(words)) + R.map(S.toUpper, S.head(words)) ## Types @@ -101,14 +101,22 @@ silent failures due to type coercion (at worst). For example: ```javascript S.inc('XXX'); -// ! TypeError: ‘inc’ expected a value of type FiniteNumber as its first argument; received "XXX" +// ! TypeError: Invalid value +// +// inc :: FiniteNumber -> FiniteNumber +// ^^^^^^^^^^^^ +// 1 +// +// 1) "XXX" :: String +// +// The value at position 1 is not a member of ‘FiniteNumber’. ``` Compare this to the behaviour of Ramda's unchecked equivalent: ```javascript R.inc('XXX'); -// => '1XXX' +// => NaN ``` There is a performance cost to run-time type checking. One may wish to @@ -134,7 +142,7 @@ const S = process.env.NODE_ENV === 'production' ? ### Classify -

type :: a -> String

+

type :: a -> String

Takes a value, `x`, of any type and returns its type identifier. If `x` has a `'@@type'` property whose value is a string, `x['@@type']` @@ -153,7 +161,7 @@ is defined. 'Array' ``` -

is :: TypeRep a -> b -> Boolean

+

is :: TypeRep a -> b -> Boolean

Takes a [type representative](#type-representatives) and a value of any type and returns `true` if the given value is of the specified @@ -172,7 +180,7 @@ false ### Combinator -

I :: a -> a

+

I :: a -> a

The I combinator. Returns its argument. Equivalent to Haskell's `id` function. @@ -182,7 +190,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. @@ -195,20 +203,20 @@ Haskell's `const` function. [42, 42, 42, 42, 42] ``` -

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

+

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

The A combinator. Takes a function and a value, and returns the result of applying the function to the value. Equivalent to Haskell's `($)` function. ```javascript -> S.A(R.inc, 1) +> S.A(S.inc, 1) 2 -> R.map(S.A(R.__, 100), [R.inc, Math.sqrt]) +> R.map(S.A(R.__, 100), [S.inc, Math.sqrt]) [101, 10] ``` -

C :: (a -> b -> c) -> b -> a -> c

+

C :: (a -> b -> c) -> b -> a -> c

The C combinator. Takes a curried binary function and two values, and returns the result of applying the function to the values in reverse. @@ -226,7 +234,7 @@ functions. [3, 4, 2] ``` -

B :: (b -> c) -> (a -> b) -> a -> c

+

B :: (b -> c) -> (a -> b) -> a -> c

The B combinator. Takes two functions and a value, and returns the result of applying the first function to the result of applying the second to the @@ -237,7 +245,7 @@ value. Equivalent to [`compose`](#compose) and Haskell's `(.)` function. 10 ``` -

S :: (a -> b -> c) -> (a -> b) -> a -> c

+

S :: (a -> b -> c) -> (a -> b) -> a -> c

The S combinator. Takes a curried binary function, a unary function, and a value, and returns the result of applying the binary function to: @@ -246,13 +254,13 @@ and a value, and returns the result of applying the binary function to: - the result of applying the unary function to the value. ```javascript -> S.S(R.add, Math.sqrt, 100) +> S.S(S.add, Math.sqrt, 100) 110 ``` ### Function -

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

+

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

Takes a binary function and two values and returns the result of applying the function - with its argument order reversed - to the @@ -266,7 +274,7 @@ See also [`C`](#C). [1, 4, 9, 16, 25] ``` -

lift :: Functor f => (a -> b) -> f a -> f b

+

lift :: Functor f => (a -> b) -> f a -> f b

Promotes a unary function to a function which operates on a [Functor][]. @@ -278,16 +286,16 @@ Just(3) Nothing() ``` -

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 binary function to a function which operates on two [Apply][]s. ```javascript -> S.lift2(R.add, S.Just(2), S.Just(3)) +> S.lift2(S.add, S.Just(2), S.Just(3)) Just(5) -> S.lift2(R.add, S.Just(2), S.Nothing()) +> S.lift2(S.add, S.Just(2), S.Nothing()) Nothing() > S.lift2(S.and, S.Just(true), S.Just(true)) @@ -297,7 +305,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 ternary function to a function which operates on three [Apply][]s. @@ -312,7 +320,7 @@ Nothing() ### Composition -

compose :: (b -> c) -> (a -> b) -> a -> c

+

compose :: (b -> c) -> (a -> b) -> a -> c

Takes two functions assumed to be unary and a value of any type, and returns the result of applying the first function to the result @@ -328,7 +336,7 @@ See also [`B`](#B) and [`pipe`](#pipe). 10 ``` -

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

+

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

Takes a list of functions assumed to be unary and a value of any type, and returns the result of applying the sequence of transformations to @@ -344,7 +352,7 @@ See also [`meld`](#meld). 9 ``` -

meld :: [** -> *] -> (* -> * -> ... -> *)

+

meld :: [** -> *] -> (* -> * -> ... -> *)

Takes a list of non-nullary functions and returns a curried function whose arity is one greater than the sum of the arities of the given @@ -379,15 +387,15 @@ either a Just whose value is of type `a` or a Nothing (with no value). The Maybe type satisfies the [Monoid][], [Monad][], [Traversable][], and [Extend][] specifications. -

MaybeType :: Type -> Type

+

MaybeType :: Type -> Type

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

Maybe :: TypeRep Maybe

+

Maybe :: TypeRep Maybe

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

Maybe.empty :: -> Maybe a

+

Maybe.empty :: -> Maybe a

Returns a Nothing. @@ -396,7 +404,7 @@ Returns a Nothing. Nothing() ``` -

Maybe.of :: a -> Maybe a

+

Maybe.of :: a -> Maybe a

Takes a value of any type and returns a Just with the given value. @@ -405,11 +413,11 @@ Takes a value of any type and returns a Just with the given value. Just(42) ``` -

Maybe#@@type :: String

+

Maybe#@@type :: String

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

Maybe#isNothing :: Boolean

+

Maybe#isNothing :: Boolean

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

Maybe#isJust :: Boolean

+

Maybe#isJust :: Boolean

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

Maybe#ap :: Maybe (a -> b) ~> Maybe a -> Maybe b

+

Maybe#ap :: Maybe (a -> b) ~> Maybe a -> Maybe b

Takes a value of type `Maybe a` and returns a Nothing unless `this` is a Just *and* the argument is a Just, in which case it returns a @@ -451,7 +459,7 @@ Nothing() Just(43) ``` -

Maybe#chain :: Maybe a ~> (a -> Maybe b) -> Maybe b

+

Maybe#chain :: Maybe a ~> (a -> Maybe b) -> Maybe b

Takes a function and returns `this` if `this` is a Nothing; otherwise it returns the result of applying the function to this Just's value. @@ -467,7 +475,7 @@ Nothing() Just(12.34) ``` -

Maybe#concat :: Semigroup a => Maybe a ~> Maybe a -> Maybe a

+

Maybe#concat :: Semigroup a => Maybe a ~> Maybe a -> Maybe a

Returns the result of concatenating two Maybe values of the same type. `a` must have a [Semigroup][] (indicated by the presence of a `concat` @@ -496,7 +504,7 @@ Just([1, 2, 3]) Just([1, 2, 3]) ``` -

Maybe#empty :: Maybe a ~> Maybe a

+

Maybe#empty :: Maybe a ~> Maybe a

Returns a Nothing. @@ -505,7 +513,7 @@ Returns a Nothing. Nothing() ``` -

Maybe#equals :: Maybe a ~> b -> Boolean

+

Maybe#equals :: Maybe a ~> b -> Boolean

Takes a value of any type and returns `true` if: @@ -531,7 +539,7 @@ false false ``` -

Maybe#extend :: Maybe a ~> (Maybe a -> a) -> Maybe a

+

Maybe#extend :: Maybe a ~> (Maybe a -> a) -> Maybe a

Takes a function and returns `this` if `this` is a Nothing; otherwise it returns a Just whose value is the result of applying the function to @@ -545,7 +553,7 @@ Nothing() Just(43) ``` -

Maybe#filter :: Maybe a ~> (a -> Boolean) -> Maybe a

+

Maybe#filter :: Maybe a ~> (a -> Boolean) -> Maybe a

Takes a predicate and returns `this` if `this` is a Just whose value satisfies the predicate; Nothing otherwise. @@ -558,7 +566,7 @@ Just(42) Nothing() ``` -

Maybe#map :: Maybe a ~> (a -> b) -> Maybe b

+

Maybe#map :: Maybe a ~> (a -> b) -> Maybe b

Takes a function and returns `this` if `this` is a Nothing; otherwise it returns a Just whose value is the result of applying the function to @@ -572,7 +580,7 @@ Nothing() Just(6) ``` -

Maybe#of :: Maybe a ~> b -> Maybe b

+

Maybe#of :: Maybe a ~> b -> Maybe b

Takes a value of any type and returns a Just with the given value. @@ -581,7 +589,7 @@ Takes a value of any type and returns a Just with the given value. Just(42) ``` -

Maybe#reduce :: Maybe a ~> (b -> a -> b) -> b -> b

+

Maybe#reduce :: Maybe a ~> (b -> a -> b) -> b -> b

Takes a function and an initial value of any type, and returns: @@ -598,7 +606,7 @@ Takes a function and an initial value of any type, and returns: 15 ``` -

Maybe#sequence :: Applicative f => Maybe (f a) ~> (a -> f a) -> f (Maybe a)

+

Maybe#sequence :: Applicative f => Maybe (f a) ~> (a -> f a) -> f (Maybe a)

Evaluates an applicative action contained within the Maybe, resulting in: @@ -614,7 +622,7 @@ Right(Nothing()) Right(Just(42)) ``` -

Maybe#toBoolean :: Maybe a ~> Boolean

+

Maybe#toBoolean :: Maybe a ~> Boolean

Returns `false` if `this` is a Nothing; `true` if `this` is a Just. @@ -626,7 +634,7 @@ false true ``` -

Maybe#toString :: Maybe a ~> String

+

Maybe#toString :: Maybe a ~> String

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

Maybe#inspect :: Maybe a ~> String

+

Maybe#inspect :: Maybe a ~> String

Returns the string representation of the Maybe. This method is used by `util.inspect` and the REPL to format a Maybe for display. @@ -653,7 +661,7 @@ See also [`Maybe#toString`](#Maybe.prototype.toString). 'Just([1, 2, 3])' ``` -

Nothing :: -> Maybe a

+

Nothing :: -> Maybe a

Returns a Nothing. Though this is a constructor function the `new` keyword needn't be used. @@ -663,7 +671,7 @@ keyword needn't be used. Nothing() ``` -

Just :: a -> Maybe a

+

Just :: a -> Maybe a

Takes a value of any type and returns a Just with the given value. Though this is a constructor function the `new` keyword needn't be @@ -674,7 +682,7 @@ used. Just(42) ``` -

isNothing :: Maybe a -> Boolean

+

isNothing :: Maybe a -> Boolean

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

isJust :: Maybe a -> Boolean

+

isJust :: Maybe a -> Boolean

Returns `true` if the given Maybe is a Just; `false` if it is a Nothing. @@ -698,7 +706,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. @@ -711,7 +719,7 @@ if the Maybe is a Just; the default value otherwise. 0 ``` -

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. @@ -724,7 +732,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 @@ -738,7 +746,7 @@ the Just's value. Otherwise, the first argument is returned. 0 ``` -

catMaybes :: [Maybe a] -> [a]

+

catMaybes :: [Maybe a] -> [a]

Takes a list of Maybes and returns a list containing each Just's value. @@ -747,7 +755,7 @@ Takes a list of Maybes and returns a list containing each Just's value. ['foo', 'baz'] ``` -

mapMaybe :: (a -> Maybe b) -> [a] -> [b]

+

mapMaybe :: (a -> Maybe b) -> [a] -> [b]

Takes a function and a list, applies the function to each element of the list, and returns a list of "successful" results. If the result of @@ -762,7 +770,7 @@ In general terms, `mapMaybe` filters a list while mapping over it. [1, 4] ``` -

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

+

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

Takes a unary function `f` which may throw and a value `x` of any type, and applies `f` to `x` inside a `try` block. If an exception is caught, @@ -779,11 +787,11 @@ 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). @@ -796,15 +804,15 @@ value is of type `b`. The Either type satisfies the [Semigroup][], [Monad][], and [Extend][] specifications. -

EitherType :: Type -> Type -> Type

+

EitherType :: Type -> Type -> Type

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

Either :: TypeRep Either

+

Either :: TypeRep Either

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

Either.of :: b -> Either a b

+

Either.of :: b -> Either a b

Takes a value of any type and returns a Right with the given value. @@ -813,11 +821,11 @@ Takes a value of any type and returns a Right with the given value. Right(42) ``` -

Either#@@type :: String

+

Either#@@type :: String

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

Either#isLeft :: Boolean

+

Either#isLeft :: Boolean

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

Either#isRight :: Boolean

+

Either#isRight :: Boolean

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

Either#ap :: Either a (b -> c) ~> Either a b -> Either a c

+

Either#ap :: Either a (b -> c) ~> Either a b -> Either a c

Takes a value of type `Either a b` and returns a Left unless `this` is a Right *and* the argument is a Right, in which case it returns @@ -859,7 +867,7 @@ Left('Cannot divide by zero') Right(43) ``` -

Either#chain :: Either a b ~> (b -> Either a c) -> Either a c

+

Either#chain :: Either a b ~> (b -> Either a c) -> Either a c

Takes a function and returns `this` if `this` is a Left; otherwise it returns the result of applying the function to this Right's value. @@ -880,7 +888,7 @@ Left('Cannot represent square root of negative number') Right(5) ``` -

Either#concat :: (Semigroup a, Semigroup b) => Either a b ~> Either a b -> Either a b

+

Either#concat :: (Semigroup a, Semigroup b) => Either a b ~> Either a b -> Either a b

Returns the result of concatenating two Either values of the same type. `a` must have a [Semigroup][] (indicated by the presence of a `concat` @@ -910,7 +918,7 @@ Right([1, 2, 3]) Right([1, 2, 3]) ``` -

Either#equals :: Either a b ~> c -> Boolean

+

Either#equals :: Either a b ~> c -> Boolean

Takes a value of any type and returns `true` if: @@ -931,7 +939,7 @@ false false ``` -

Either#extend :: Either a b ~> (Either a b -> b) -> Either a b

+

Either#extend :: Either a b ~> (Either a b -> b) -> Either a b

Takes a function and returns `this` if `this` is a Left; otherwise it returns a Right whose value is the result of applying the function to @@ -945,7 +953,7 @@ Left('Cannot divide by zero') Right(43) ``` -

Either#map :: Either a b ~> (b -> c) -> Either a c

+

Either#map :: Either a b ~> (b -> c) -> Either a c

Takes a function and returns `this` if `this` is a Left; otherwise it returns a Right whose value is the result of applying the function to @@ -959,7 +967,7 @@ Left('Cannot divide by zero') Right(6) ``` -

Either#of :: Either a b ~> c -> Either a c

+

Either#of :: Either a b ~> c -> Either a c

Takes a value of any type and returns a Right with the given value. @@ -968,7 +976,7 @@ Takes a value of any type and returns a Right with the given value. Right(42) ``` -

Either#toBoolean :: Either a b ~> Boolean

+

Either#toBoolean :: Either a b ~> Boolean

Returns `false` if `this` is a Left; `true` if `this` is a Right. @@ -980,7 +988,7 @@ false true ``` -

Either#toString :: Either a b ~> String

+

Either#toString :: Either a b ~> String

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

Either#inspect :: Either a b ~> String

+

Either#inspect :: Either a b ~> String

Returns the string representation of the Either. This method is used by `util.inspect` and the REPL to format a Either for display. @@ -1007,7 +1015,7 @@ See also [`Either#toString`](#Either.prototype.toString). 'Right([1, 2, 3])' ``` -

Left :: a -> Either a b

+

Left :: a -> Either a b

Takes a value of any type and returns a Left with the given value. Though this is a constructor function the `new` keyword needn't be @@ -1018,7 +1026,7 @@ used. Left('Cannot divide by zero') ``` -

Right :: b -> Either a b

+

Right :: b -> Either a b

Takes a value of any type and returns a Right with the given value. Though this is a constructor function the `new` keyword needn't be @@ -1029,7 +1037,7 @@ used. 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. @@ -1041,7 +1049,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. @@ -1053,7 +1061,7 @@ true false ``` -

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 @@ -1068,7 +1076,7 @@ Right's value, if the Either is a Right. '42' ``` -

lefts :: [Either a b] -> [a]

+

lefts :: [Either a b] -> [a]

Takes a list of Eithers and returns a list containing each Left's value. @@ -1079,7 +1087,7 @@ See also [`rights`](#rights). ['foo', 'bar'] ``` -

rights :: [Either a b] -> [b]

+

rights :: [Either a b] -> [b]

Takes a list of Eithers and returns a list containing each Right's value. @@ -1090,7 +1098,7 @@ See also [`lefts`](#lefts). [20, 10] ``` -

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. @@ -1111,15 +1119,15 @@ Left(new SyntaxError('Unexpected end of input')) Left('Unexpected end of 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). -

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

+

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

Takes a value of any type and a Maybe, and returns an Either. If the second argument is a Nothing, a Left containing the first @@ -1136,7 +1144,7 @@ Right(42) ### Alternative -

and :: Alternative a => a -> a -> a

+

and :: Alternative a => a -> a -> a

Takes two values of the same type and returns the second value if the first is "true"; the first value otherwise. An array is @@ -1152,7 +1160,7 @@ Just(2) Nothing() ``` -

or :: Alternative a => a -> a -> a

+

or :: Alternative a => a -> a -> a

Takes two values of the same type and returns the first value if it is "true"; the second value otherwise. An array is considered "true" @@ -1167,7 +1175,7 @@ Just(1) Just(3) ``` -

xor :: (Alternative a, Monoid a) => a -> a -> a

+

xor :: (Alternative a, Monoid a) => a -> a -> a

Takes two values of the same type and returns the "true" value if one value is "true" and the other is "false"; otherwise it @@ -1186,7 +1194,7 @@ Nothing() ### Logic -

not :: Boolean -> Boolean

+

not :: Boolean -> Boolean

Takes a Boolean and returns the negation of that value (`false` for `true`; `true` for `false`). @@ -1199,7 +1207,7 @@ false true ``` -

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 @@ -1215,7 +1223,7 @@ value otherwise. 4 ``` -

allPass :: [a -> Boolean] -> a -> Boolean

+

allPass :: [a -> Boolean] -> a -> Boolean

Takes an array of unary predicates and a value of any type and returns `true` if all the predicates pass; `false` otherwise. @@ -1230,7 +1238,7 @@ true false ``` -

anyPass :: [a -> Boolean] -> a -> Boolean

+

anyPass :: [a -> Boolean] -> a -> Boolean

Takes an array of unary predicates and a value of any type and returns `true` if any of the predicates pass; `false` otherwise. @@ -1247,7 +1255,7 @@ false ### List -

slice :: Integer -> Integer -> [a] -> Maybe [a]

+

slice :: Integer -> Integer -> [a] -> Maybe [a]

Returns Just a list containing the elements from the supplied list from a beginning index (inclusive) to an end index (exclusive). @@ -1276,7 +1284,7 @@ Nothing() Just('nana') ``` -

at :: Integer -> [a] -> Maybe a

+

at :: Integer -> [a] -> Maybe a

Takes an index and a list and returns Just the element of the list at the index if the index is within the list's bounds; Nothing otherwise. @@ -1293,7 +1301,7 @@ Nothing() Just('d') ``` -

head :: [a] -> Maybe a

+

head :: [a] -> Maybe a

Takes a list and returns Just the first element of the list if the list contains at least one element; Nothing if the list is empty. @@ -1306,7 +1314,7 @@ Just(1) Nothing() ``` -

last :: [a] -> Maybe a

+

last :: [a] -> Maybe a

Takes a list and returns Just the last element of the list if the list contains at least one element; Nothing if the list is empty. @@ -1319,7 +1327,7 @@ Just(3) Nothing() ``` -

tail :: [a] -> Maybe [a]

+

tail :: [a] -> Maybe [a]

Takes a list and returns Just a list containing all but the first of the list's elements if the list contains at least one element; @@ -1333,7 +1341,7 @@ Just([2, 3]) Nothing() ``` -

init :: [a] -> Maybe [a]

+

init :: [a] -> Maybe [a]

Takes a list and returns Just a list containing all but the last of the list's elements if the list contains at least one element; @@ -1347,7 +1355,7 @@ Just([1, 2]) Nothing() ``` -

take :: Integer -> [a] -> Maybe [a]

+

take :: Integer -> [a] -> Maybe [a]

Returns Just the first N elements of the given collection if N is greater than or equal to zero and less than or equal to the length @@ -1365,7 +1373,7 @@ Just('abcd') Nothing() ``` -

takeLast :: Integer -> [a] -> Maybe [a]

+

takeLast :: Integer -> [a] -> Maybe [a]

Returns Just the last N elements of the given collection if N is greater than or equal to zero and less than or equal to the length @@ -1383,7 +1391,7 @@ Just('defg') Nothing() ``` -

drop :: Integer -> [a] -> Maybe [a]

+

drop :: Integer -> [a] -> Maybe [a]

Returns Just all but the first N elements of the given collection if N is greater than or equal to zero and less than or equal to the @@ -1401,7 +1409,7 @@ Just('efg') Nothing() ``` -

dropLast :: Integer -> [a] -> Maybe [a]

+

dropLast :: Integer -> [a] -> Maybe [a]

Returns Just all but the last N elements of the given collection if N is greater than or equal to zero and less than or equal to the @@ -1419,7 +1427,7 @@ Just('abc') Nothing() ``` -

find :: (a -> Boolean) -> [a] -> Maybe a

+

find :: (a -> Boolean) -> [a] -> Maybe a

Takes a predicate and a list and returns Just the leftmost element of the list which satisfies the predicate; Nothing if none of the list's @@ -1433,7 +1441,7 @@ Just(-2) Nothing() ``` -

indexOf :: a -> [a] -> Maybe Integer

+

indexOf :: a -> [a] -> Maybe Integer

Takes a value of any type and a list, and returns Just the index of the first occurrence of the value in the list, if applicable; @@ -1457,7 +1465,7 @@ Just(1) Nothing() ``` -

lastIndexOf :: a -> [a] -> Maybe Integer

+

lastIndexOf :: a -> [a] -> Maybe Integer

Takes a value of any type and a list, and returns Just the index of the last occurrence of the value in the list, if applicable; @@ -1481,7 +1489,7 @@ Just(3) Nothing() ``` -

pluck :: Accessible a => TypeRep b -> String -> [a] -> [Maybe b]

+

pluck :: Accessible a => TypeRep b -> String -> [a] -> [Maybe b]

Takes a [type representative](#type-representatives), a property name, and a list of objects and returns a list of equal length. Each element @@ -1496,7 +1504,7 @@ See also [`get`](#get). [Just(1), Just(2), Nothing(), Nothing(), Nothing()] ``` -

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

+

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

Takes a binary function, an initial value, and a [Foldable][], and applies the function to the initial value and the Foldable's first @@ -1514,7 +1522,7 @@ otherwise. [5, 4, 3, 2, 1] ``` -

unfoldr :: (b -> Maybe (a, b)) -> b -> [a]

+

unfoldr :: (b -> Maybe (a, b)) -> b -> [a]

Takes a function and a seed value, and returns a list generated by applying the function repeatedly. The list is initially empty. The @@ -1533,7 +1541,7 @@ of the function should result in either: ### Object -

get :: Accessible a => TypeRep b -> String -> a -> Maybe b

+

get :: Accessible a => TypeRep b -> String -> a -> Maybe b

Takes a [type representative](#type-representatives), a property name, and an object and returns Just the value of the specified object @@ -1556,7 +1564,7 @@ Nothing() Nothing() ``` -

gets :: Accessible a => TypeRep b -> [String] -> a -> Maybe b

+

gets :: Accessible a => TypeRep b -> [String] -> a -> Maybe b

Takes a [type representative](#type-representatives), a list of property names, and an object and returns Just the value at the path specified by @@ -1578,7 +1586,7 @@ Nothing() ### Number -

negate :: ValidNumber -> ValidNumber

+

negate :: ValidNumber -> ValidNumber

Negates its argument. @@ -1590,7 +1598,7 @@ Negates its argument. 42 ``` -

add :: FiniteNumber -> FiniteNumber -> FiniteNumber

+

add :: FiniteNumber -> FiniteNumber -> FiniteNumber

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

sub :: FiniteNumber -> FiniteNumber -> FiniteNumber

+

sub :: FiniteNumber -> FiniteNumber -> FiniteNumber

Returns the difference between two (finite) numbers. @@ -1608,7 +1616,7 @@ Returns the difference between two (finite) numbers. 2 ``` -

inc :: FiniteNumber -> FiniteNumber

+

inc :: FiniteNumber -> FiniteNumber

Increments a (finite) number by one. @@ -1617,7 +1625,7 @@ Increments a (finite) number by one. 2 ``` -

dec :: FiniteNumber -> FiniteNumber

+

dec :: FiniteNumber -> FiniteNumber

Decrements a (finite) number by one. @@ -1626,7 +1634,7 @@ Decrements a (finite) number by one. 1 ``` -

mult :: FiniteNumber -> FiniteNumber -> FiniteNumber

+

mult :: FiniteNumber -> FiniteNumber -> FiniteNumber

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

div :: FiniteNumber -> NonZeroFiniteNumber -> FiniteNumber

+

div :: FiniteNumber -> NonZeroFiniteNumber -> FiniteNumber

Returns the result of dividing its first argument (a finite number) by its second argument (a non-zero finite number). @@ -1645,7 +1653,7 @@ its second argument (a non-zero finite number). 3.5 ``` -

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

+

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

Returns the smaller of its two arguments. @@ -1666,7 +1674,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. @@ -1689,7 +1697,7 @@ new Date('2000-01-01') ### Integer -

even :: Integer -> Boolean

+

even :: Integer -> Boolean

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

odd :: Integer -> Boolean

+

odd :: Integer -> Boolean

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

parseDate :: String -> Maybe Date

+

parseDate :: String -> Maybe Date

Takes a string and returns Just the date represented by the string if it does in fact represent a date; Nothing otherwise. @@ -1728,7 +1736,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. @@ -1741,7 +1749,7 @@ Just(-123.45) Nothing() ``` -

parseInt :: Integer -> String -> Maybe Integer

+

parseInt :: Integer -> 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 @@ -1763,7 +1771,7 @@ Just(255) Nothing() ``` -

parseJson :: String -> Maybe Any

+

parseJson :: String -> Maybe Any

Takes a string which may or may not be valid JSON, and returns Just the result of applying `JSON.parse` to the string if valid; Nothing @@ -1779,7 +1787,7 @@ Nothing() ### RegExp -

regex :: RegexFlags -> String -> RegExp

+

regex :: RegexFlags -> String -> RegExp

Takes a [RegexFlags][] and a pattern, and returns a RegExp. @@ -1788,7 +1796,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. @@ -1802,7 +1810,7 @@ Properties: '\\-=\\*\\{XYZ\\}\\*=\\-' ``` -

test :: RegExp -> String -> Boolean

+

test :: RegExp -> String -> Boolean

Takes a pattern and a string, and returns `true` if the pattern matches the string; `false` otherwise. @@ -1815,7 +1823,7 @@ true false ``` -

match :: RegExp -> String -> Maybe [Maybe String]

+

match :: RegExp -> String -> Maybe [Maybe String]

Takes a pattern and a string, and returns Just a list of matches if the pattern matches the string; Nothing otherwise. Each match @@ -1832,7 +1840,7 @@ Just([Just('bye'), Nothing()]) ### String -

toUpper :: String -> String

+

toUpper :: String -> String

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

toLower :: String -> String

+

toLower :: String -> String

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

words :: String -> [String]

+

words :: String -> [String]

Takes a string and returns the list of words the string contains (words are delimited by whitespace characters). @@ -1866,7 +1874,7 @@ See also [`unwords`](#unwords). ['foo', 'bar', 'baz'] ``` -

unwords :: [String] -> String

+

unwords :: [String] -> String

Takes a list of words and returns the result of joining the words with separating spaces. @@ -1878,7 +1886,7 @@ See also [`words`](#words). 'foo bar baz' ``` -

lines :: String -> [String]

+

lines :: String -> [String]

Takes a string and returns the list of lines the string contains (lines are delimited by newlines: `'\n'` or `'\r\n'` or `'\r'`). @@ -1891,7 +1899,7 @@ See also [`unlines`](#unlines). ['foo', 'bar', 'baz'] ``` -

unlines :: [String] -> String

+

unlines :: [String] -> String

Takes a list of lines and returns the result of joining the lines after appending a terminating line feed (`'\n'`) to each. diff --git a/bower.json b/bower.json index 40cd5a1e..c11f442e 100644 --- a/bower.json +++ b/bower.json @@ -1,6 +1,6 @@ { "name": "sanctuary", - "version": "0.9.1", + "version": "0.10.0", "description": "Refuge from unsafe JavaScript", "license": "MIT", "repository": { diff --git a/package.json b/package.json index ae35e02e..3f71f961 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sanctuary", - "version": "0.9.1", + "version": "0.10.0", "description": "Refuge from unsafe JavaScript", "license": "MIT", "repository": {