diff --git a/.travis.yml b/.travis.yml index 791313a3..2c1768ec 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,8 @@ language: node_js sudo: false node_js: - - 0.10 + - 4 + - 5 env: - PATH=$HOME/purescript:$PATH install: diff --git a/docs/Data/Array.md b/docs/Data/Array.md index 664477d4..4e4a3d9c 100644 --- a/docs/Data/Array.md +++ b/docs/Data/Array.md @@ -8,12 +8,36 @@ use cases. This module is useful when integrating with JavaScript libraries which use arrays, but immutable arrays are not a practical data structure for many use cases due to their poor asymptotics. +In addition to the functions in this module, Arrays have a number of +useful instances: + +* `Functor`, which provides `map :: forall a b. (a -> b) -> Array a -> + Array b` +* `Apply`, which provides `(<*>) :: forall a b. Array (a -> b) -> Array a + -> Array b`. This function works a bit like a Cartesian product; the + result array is constructed by applying each function in the first + array to each value in the second, so that the result array ends up with + a length equal to the product of the two arguments' lengths. +* `Bind`, which provides `(>>=) :: forall a b. (a -> Array b) -> Array a + -> Array b` (this is the same as `concatMap`). +* `Semigroup`, which provides `(<>) :: forall a. Array a -> Array a -> + Array a`, for concatenating arrays. +* `Foldable`, which provides a slew of functions for *folding* (also known + as *reducing*) arrays down to one value. For example, + `Data.Foldable.any` tests whether an array of `Boolean` values contains + at least one `true`. +* `Traversable`, which provides the PureScript version of a for-loop, + allowing you to iterate over an array and accumulate effects. + + #### `singleton` ``` purescript singleton :: forall a. a -> Array a ``` +Create an array of one element + #### `range` ``` purescript @@ -453,7 +477,7 @@ specified equivalence relation to detemine equality. nub :: forall a. (Eq a) => Array a -> Array a ``` -Special case of `nubBy`: `nubBy eq` +Remove the duplicates from an array, creating a new array. #### `nubBy` @@ -462,8 +486,7 @@ nubBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a ``` Remove the duplicates from an array, where element equality is determined -by the specified equivalence relation, creating a new array. The first -occurence of an element is always the one that is kept. +by the specified equivalence relation, creating a new array. #### `union` @@ -537,6 +560,17 @@ relation to compare elements, creating a new array. zipWith :: forall a b c. (a -> b -> c) -> Array a -> Array b -> Array c ``` +Apply a function to pairs of elements at the same index in two arrays, +collecting the results in a new array. + +If one array is longer, elements will be discarded from the longer array. + +For example + +```purescript +zipWith (*) [1, 2, 3] [4, 5, 6, 7] == [4, 10, 18] +``` + #### `zipWithA` ``` purescript @@ -569,3 +603,7 @@ second components. ``` purescript foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> Array b -> m a ``` + +Perform a fold using a monadic step function. + + diff --git a/docs/Data/Array/ST.md b/docs/Data/Array/ST.md index 40b33aeb..381c19da 100644 --- a/docs/Data/Array/ST.md +++ b/docs/Data/Array/ST.md @@ -15,7 +15,7 @@ A reference to a mutable array. The first type parameter represents the memory region which the array belongs to. The second type parameter defines the type of elements of the mutable array. -The runtime representation of a value of type `STArray h a` is the same as that of `[a]`, +The runtime representation of a value of type `STArray h a` is the same as that of `Array a`, except that mutation is allowed. #### `Assoc` @@ -24,7 +24,7 @@ except that mutation is allowed. type Assoc a = { value :: a, index :: Int } ``` -An element and its index +An element and its index. #### `runSTArray` diff --git a/src/Data/Array.purs b/src/Data/Array.purs index 42d1eb01..78c39167 100644 --- a/src/Data/Array.purs +++ b/src/Data/Array.purs @@ -5,6 +5,28 @@ -- | use cases. This module is useful when integrating with JavaScript libraries -- | which use arrays, but immutable arrays are not a practical data structure -- | for many use cases due to their poor asymptotics. +-- | +-- | In addition to the functions in this module, Arrays have a number of +-- | useful instances: +-- | +-- | * `Functor`, which provides `map :: forall a b. (a -> b) -> Array a -> +-- | Array b` +-- | * `Apply`, which provides `(<*>) :: forall a b. Array (a -> b) -> Array a +-- | -> Array b`. This function works a bit like a Cartesian product; the +-- | result array is constructed by applying each function in the first +-- | array to each value in the second, so that the result array ends up with +-- | a length equal to the product of the two arguments' lengths. +-- | * `Bind`, which provides `(>>=) :: forall a b. (a -> Array b) -> Array a +-- | -> Array b` (this is the same as `concatMap`). +-- | * `Semigroup`, which provides `(<>) :: forall a. Array a -> Array a -> +-- | Array a`, for concatenating arrays. +-- | * `Foldable`, which provides a slew of functions for *folding* (also known +-- | as *reducing*) arrays down to one value. For example, +-- | `Data.Foldable.any` tests whether an array of `Boolean` values contains +-- | at least one `true`. +-- | * `Traversable`, which provides the PureScript version of a for-loop, +-- | allowing you to iterate over an array and accumulate effects. +-- | module Data.Array ( singleton , (..), range @@ -94,10 +116,6 @@ import Data.Traversable (sequence) import Data.Tuple (Tuple(..)) import qualified Data.Maybe.Unsafe as U --------------------------------------------------------------------------------- --- Array creation -------------------------------------------------------------- --------------------------------------------------------------------------------- - -- | Create an array of one element singleton :: forall a. a -> Array a singleton a = [a] @@ -464,10 +482,6 @@ groupBy op = go [] in go ((o.head : sp.init) : acc) sp.rest Nothing -> reverse acc --------------------------------------------------------------------------------- --- Set-like operations --------------------------------------------------------- --------------------------------------------------------------------------------- - -- | Remove the duplicates from an array, creating a new array. nub :: forall a. (Eq a) => Array a -> Array a nub = nubBy eq @@ -519,10 +533,6 @@ intersect = intersectBy eq intersectBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a -> Array a intersectBy eq xs ys = filter (\x -> isJust (findIndex (eq x) ys)) xs --------------------------------------------------------------------------------- --- Zipping --------------------------------------------------------------------- --------------------------------------------------------------------------------- - -- | Apply a function to pairs of elements at the same index in two arrays, -- | collecting the results in a new array. -- | @@ -551,10 +561,6 @@ unzip :: forall a b. Array (Tuple a b) -> Tuple (Array a) (Array b) unzip = uncons' (\_ -> Tuple [] []) \(Tuple a b) ts -> case unzip ts of Tuple as bs -> Tuple (a : as) (b : bs) --------------------------------------------------------------------------------- --- Folding --------------------------------------------------------------------- --------------------------------------------------------------------------------- - -- | Perform a fold using a monadic step function. foldM :: forall m a b. (Monad m) => (a -> b -> m a) -> a -> Array b -> m a foldM f a = uncons' (\_ -> return a) (\b bs -> f a b >>= \a' -> foldM f a' bs) diff --git a/src/Data/Array/ST.purs b/src/Data/Array/ST.purs index f570187e..264c661e 100644 --- a/src/Data/Array/ST.purs +++ b/src/Data/Array/ST.purs @@ -28,11 +28,11 @@ import Data.Maybe (Maybe(..)) -- | The first type parameter represents the memory region which the array belongs to. -- | The second type parameter defines the type of elements of the mutable array. -- | --- | The runtime representation of a value of type `STArray h a` is the same as that of `[a]`, +-- | The runtime representation of a value of type `STArray h a` is the same as that of `Array a`, -- | except that mutation is allowed. foreign import data STArray :: * -> * -> * --- | An element and its index +-- | An element and its index. type Assoc a = { value :: a, index :: Int } -- | Freeze a mutable array, creating an immutable array. Use this function as you would use