Module

Data.Array

Package: purescript-arrays
Repository: purescript/purescript-arrays

Helper functions for working with immutable Javascript arrays.

Note: Depending on your use-case, you may prefer to use Data.List or Data.Sequence instead, which might give better performance for certain 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.or tests whether an array of Boolean values contains at least one true value.
Traversable, which provides the PureScript version of a for-loop, allowing you to iterate over an array and accumulate effects.

#toUnfoldable Source

toUnfoldable :: forall f. Unfoldable f => Array ~> f

Convert an Array into an Unfoldable structure.

#fromFoldable Source

fromFoldable :: forall f. Foldable f => f ~> Array

Convert a Foldable structure into an Array.

#singleton Source

singleton :: forall a. a -> Array a

Create an array of one element

#range Source

range :: Int -> Int -> Array Int

Create an array containing a range of integers, including both endpoints.

#replicate Source

replicate :: forall a. Int -> a -> Array a

Create an array containing a value repeated the specified number of times.

#(..) Source

Operator alias for Data.Array.range (non-associative / precedence 8)

An infix synonym for range.

#some Source

some :: forall a f. Alternative f => Lazy (f (Array a)) => f a -> f (Array a)

Attempt a computation multiple times, requiring at least one success.

The Lazy constraint is used to generate the result lazily, to ensure termination.

#many Source

many :: forall a f. Alternative f => Lazy (f (Array a)) => f a -> f (Array a)

Attempt a computation multiple times, returning as many successful results as possible (possibly zero).

The Lazy constraint is used to generate the result lazily, to ensure termination.

#null Source

null :: forall a. Array a -> Boolean

Test whether an array is empty.

#length Source

length :: forall a. Array a -> Int

Get the number of elements in an array.

#cons Source

cons :: forall a. a -> Array a -> Array a

Attaches an element to the front of an array, creating a new array.

cons 1 [2, 3, 4] = [1, 2, 3, 4]

Note, the running time of this function is O(n).

#(:) Source

Operator alias for Data.Array.cons (right-associative / precedence 6)

An infix alias for cons.

Note, the running time of this function is O(n).

#snoc Source

snoc :: forall a. Array a -> a -> Array a

Append an element to the end of an array, creating a new array.

#insert Source

insert :: forall a. Ord a => a -> Array a -> Array a

Insert an element into a sorted array.

#insertBy Source

insertBy :: forall a. (a -> a -> Ordering) -> a -> Array a -> Array a

Insert an element into a sorted array, using the specified function to determine the ordering of elements.

#head Source

head :: forall a. Array a -> Maybe a

Get the first element in an array, or Nothing if the array is empty

Running time: O(1).

#last Source

last :: forall a. Array a -> Maybe a

Get the last element in an array, or Nothing if the array is empty

Running time: O(1).

#tail Source

tail :: forall a. Array a -> Maybe (Array a)

Get all but the first element of an array, creating a new array, or Nothing if the array is empty

Running time: O(n) where n is the length of the array

#init Source

init :: forall a. Array a -> Maybe (Array a)

Get all but the last element of an array, creating a new array, or Nothing if the array is empty.

Running time: O(n) where n is the length of the array

#uncons Source

uncons :: forall a. Array a -> Maybe { head :: a, tail :: Array a }

Break an array into its first element and remaining elements.

Using uncons provides a way of writing code that would use cons patterns in Haskell or pre-PureScript 0.7:

f (x : xs) = something
f [] = somethingElse

Becomes:

f arr = case uncons arr of
  Just { head: x, tail: xs } -> something
  Nothing -> somethingElse

#unsnoc Source

unsnoc :: forall a. Array a -> Maybe { init :: Array a, last :: a }

Break an array into its last element and all preceding elements.

Running time: O(n) where n is the length of the array

#index Source

index :: forall a. Array a -> Int -> Maybe a

This function provides a safe way to read a value at a particular index from an array.

#(!!) Source

Operator alias for Data.Array.index (left-associative / precedence 8)

An infix version of index.

#elemIndex Source

elemIndex :: forall a. Eq a => a -> Array a -> Maybe Int

Find the index of the first element equal to the specified element.

#elemLastIndex Source

elemLastIndex :: forall a. Eq a => a -> Array a -> Maybe Int

Find the index of the last element equal to the specified element.

#findIndex Source

findIndex :: forall a. (a -> Boolean) -> Array a -> Maybe Int

Find the first index for which a predicate holds.

#findLastIndex Source

findLastIndex :: forall a. (a -> Boolean) -> Array a -> Maybe Int

Find the last index for which a predicate holds.

#insertAt Source

insertAt :: forall a. Int -> a -> Array a -> Maybe (Array a)

Insert an element at the specified index, creating a new array, or returning Nothing if the index is out of bounds.

#deleteAt Source

deleteAt :: forall a. Int -> Array a -> Maybe (Array a)

Delete the element at the specified index, creating a new array, or returning Nothing if the index is out of bounds.

#updateAt Source

updateAt :: forall a. Int -> a -> Array a -> Maybe (Array a)

Change the element at the specified index, creating a new array, or returning Nothing if the index is out of bounds.

#modifyAt Source

modifyAt :: forall a. Int -> (a -> a) -> Array a -> Maybe (Array a)

Apply a function to the element at the specified index, creating a new array, or returning Nothing if the index is out of bounds.

#alterAt Source

alterAt :: forall a. Int -> (a -> Maybe a) -> Array a -> Maybe (Array a)

Update or delete the element at the specified index by applying a function to the current value, returning a new array or Nothing if the index is out-of-bounds.

#reverse Source

reverse :: forall a. Array a -> Array a

Reverse an array, creating a new array.

#concat Source

concat :: forall a. Array (Array a) -> Array a

Flatten an array of arrays, creating a new array.

#concatMap Source

concatMap :: forall b a. (a -> Array b) -> Array a -> Array b

Apply a function to each element in an array, and flatten the results into a single, new array.

#filter Source

filter :: forall a. (a -> Boolean) -> Array a -> Array a

Filter an array, keeping the elements which satisfy a predicate function, creating a new array.

#partition Source

partition :: forall a. (a -> Boolean) -> Array a -> { no :: Array a, yes :: Array a }

Partition an array using a predicate function, creating a set of new arrays. One for the values satisfying the predicate function and one for values that don't.

#filterA Source

filterA :: forall f a. Applicative f => (a -> f Boolean) -> Array a -> f (Array a)

Filter where the predicate returns a Boolean in some Applicative.

powerSet :: forall a. Array a -> Array (Array a)
powerSet = filterA (const [true, false])

#mapMaybe Source

mapMaybe :: forall b a. (a -> Maybe b) -> Array a -> Array b

Apply a function to each element in an array, keeping only the results which contain a value, creating a new array.

#catMaybes Source

catMaybes :: forall a. Array (Maybe a) -> Array a

Filter an array of optional values, keeping only the elements which contain a value, creating a new array.

#mapWithIndex Source

mapWithIndex :: forall b a. (Int -> a -> b) -> Array a -> Array b

Apply a function to each element in an array, supplying a generated zero-based index integer along with the element, creating an array with the new elements.

#sort Source

sort :: forall a. Ord a => Array a -> Array a

Sort the elements of an array in increasing order, creating a new array.

#sortBy Source

sortBy :: forall a. (a -> a -> Ordering) -> Array a -> Array a

Sort the elements of an array in increasing order, where elements are compared using the specified partial ordering, creating a new array.

#sortWith Source

sortWith :: forall b a. Ord b => (a -> b) -> Array a -> Array a

Sort the elements of an array in increasing order, where elements are sorted based on a projection

#slice Source

slice :: forall a. Int -> Int -> Array a -> Array a

Extract a subarray by a start and end index.

#take Source

take :: forall a. Int -> Array a -> Array a

Keep only a number of elements from the start of an array, creating a new array.

#takeWhile Source

takeWhile :: forall a. (a -> Boolean) -> Array a -> Array a

Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new array.

#drop Source

drop :: forall a. Int -> Array a -> Array a

Drop a number of elements from the start of an array, creating a new array.

#dropWhile Source

dropWhile :: forall a. (a -> Boolean) -> Array a -> Array a

Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new array.

#span Source

span :: forall a. (a -> Boolean) -> Array a -> { init :: Array a, rest :: Array a }

Split an array into two parts:

the longest initial subarray for which all elements satisfy the specified predicate
the remaining elements

span (\n -> n % 2 == 1) [1,3,2,4,5] == { init: [1,3], rest: [2,4,5] }

Running time: O(n).

#group Source

group :: forall a. Eq a => Array a -> Array (NonEmpty Array a)

Group equal, consecutive elements of an array into arrays.

group [1,1,2,2,1] == [[1,1],[2,2],[1]]

#group' Source

group' :: forall a. Ord a => Array a -> Array (NonEmpty Array a)

Sort and then group the elements of an array into arrays.

group' [1,1,2,2,1] == [[1,1,1],[2,2]]

#groupBy Source

groupBy :: forall a. (a -> a -> Boolean) -> Array a -> Array (NonEmpty Array a)

Group equal, consecutive elements of an array into arrays, using the specified equivalence relation to detemine equality.

#nub Source

nub :: forall a. Eq a => Array a -> Array a

Remove the duplicates from an array, creating a new array.

#nubBy Source

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.

#union Source

union :: forall a. Eq a => Array a -> Array a -> Array a

Calculate the union of two arrays. Note that duplicates in the first array are preserved while duplicates in the second array are removed.

Running time: O(n^2)

#unionBy Source

unionBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a -> Array a

Calculate the union of two arrays, using the specified function to determine equality of elements. Note that duplicates in the first array are preserved while duplicates in the second array are removed.

#delete Source

delete :: forall a. Eq a => a -> Array a -> Array a

Delete the first element of an array which is equal to the specified value, creating a new array.

Running time: O(n)

#deleteBy Source

deleteBy :: forall a. (a -> a -> Boolean) -> a -> Array a -> Array a

Delete the first element of an array which matches the specified value, under the equivalence relation provided in the first argument, creating a new array.

#difference Source

difference :: forall a. Eq a => Array a -> Array a -> Array a

Delete the first occurrence of each element in the second array from the first array, creating a new array.

Running time: O(n*m), where n is the length of the first array, and m is the length of the second.

#(\\) Source

Operator alias for Data.Array.difference (non-associative / precedence 5)

#intersect Source

intersect :: forall a. Eq a => Array a -> Array a -> Array a

Calculate the intersection of two arrays, creating a new array. Note that duplicates in the first array are preserved while duplicates in the second array are removed.

#intersectBy Source

intersectBy :: forall a. (a -> a -> Boolean) -> Array a -> Array a -> Array a

Calculate the intersection of two arrays, using the specified equivalence relation to compare elements, creating a new array. Note that duplicates in the first array are preserved while duplicates in the second array are removed.

#zipWith Source

zipWith :: forall c b a. (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

zipWith (*) [1, 2, 3] [4, 5, 6, 7] == [4, 10, 18]

#zipWithA Source

zipWithA :: forall c b a m. Applicative m => (a -> b -> m c) -> Array a -> Array b -> m (Array c)

A generalization of zipWith which accumulates results in some Applicative functor.

#zip Source

zip :: forall b a. Array a -> Array b -> Array (Tuple a b)

Rakes two lists and returns a list of corresponding pairs. If one input list is short, excess elements of the longer list are discarded.

#unzip Source

unzip :: forall b a. Array (Tuple a b) -> Tuple (Array a) (Array b)

Transforms a list of pairs into a list of first components and a list of second components.

#foldM Source

foldM :: forall b a m. Monad m => (a -> b -> m a) -> a -> Array b -> m a

Perform a fold using a monadic step function.

#foldRecM Source

foldRecM :: forall b a m. MonadRec m => (a -> b -> m a) -> a -> Array b -> m a

#unsafeIndex Source

unsafeIndex :: forall a. Partial => Array a -> Int -> a

Find the element of an array at the specified index.

Re-exports from Data.Foldable

#foldMap

foldMap :: forall f m a. Foldable f => Monoid m => (a -> m) -> f a -> m

#foldl

foldl :: forall f b a. Foldable f => (b -> a -> b) -> b -> f a -> b

#foldr

foldr :: forall f b a. Foldable f => (a -> b -> b) -> b -> f a -> b

#notElem Source

notElem :: forall f a. Foldable f => Eq a => a -> f a -> Boolean

Test whether a value is not an element of a data structure.

#intercalate Source

intercalate :: forall m f. Foldable f => Monoid m => m -> f m -> m

Fold a data structure, accumulating values in some Monoid, combining adjacent elements using the specified separator.

#fold Source

fold :: forall m f. Foldable f => Monoid m => f m -> m

Fold a data structure, accumulating values in some Monoid.

#findMap Source

findMap :: forall f b a. Foldable f => (a -> Maybe b) -> f a -> Maybe b

Try to find an element in a data structure which satisfies a predicate mapping.

#find Source

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

Try to find an element in a data structure which satisfies a predicate.

#elem Source

elem :: forall f a. Foldable f => Eq a => a -> f a -> Boolean

Test whether a value is an element of a data structure.

#any Source

any :: forall f b a. Foldable f => HeytingAlgebra b => (a -> b) -> f a -> b

any f is the same as or <<< map f; map a function over the structure, and then get the disjunction of the results.

#all Source

all :: forall f b a. Foldable f => HeytingAlgebra b => (a -> b) -> f a -> b

all f is the same as and <<< map f; map a function over the structure, and then get the conjunction of the results.

Re-exports from Data.Traversable

#scanr Source

scanr :: forall f b a. Traversable f => (a -> b -> b) -> b -> f a -> f b

Fold a data structure from the right, keeping all intermediate results instead of only the final result. Note that the initial value does not appear in the result (unlike Haskell's Prelude.scanr).

scanr (+) 0  [1,2,3] = [1,3,6]
scanr (flip (-)) 10 [1,2,3] = [4,5,7]

#scanl Source

scanl :: forall f b a. Traversable f => (b -> a -> b) -> b -> f a -> f b

Fold a data structure from the left, keeping all intermediate results instead of only the final result. Note that the initial value does not appear in the result (unlike Haskell's Prelude.scanl).

scanl (+) 0  [1,2,3] = [1,3,6]
scanl (-) 10 [1,2,3] = [9,7,4]

Modules: Data.Array; Data.Array.Partial; Data.Array.ST; Data.Array.ST.Iterator