Search results

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 STAI.iterate over an array and accumulate effects.

Helper functions for working with mutable arrays using the ST effect.

This module can be used when performance is important and mutation is a local effect.

Some specialized functions can be found here.

Partial helper functions for working with immutable arrays.

Partial functions for working with mutable arrays using the ST effect.

This module is particularly helpful when performance is very important.

DataView represents unaligned memory of unknown endianness.

ArrayView represents arrays of aligned elements of local-machine endianness. For the cases of Int8Array, Uint8Array, Uint8ClampedArray, the elements are single bytes, so they are always aligned and they have no endianness. Therefore in those cases we can freely cast back and forth to DataView.

Functions that find the last matching element based on a predicate and then do something with the array.

This module represents the functional bindings to JavaScript's TypedArray and other objects. See MDN's spec for details.

Creation

• whole, remainder, and part are functions for building a typed array accessible interface on top of an existing ArrayBuffer
• empty and fromArray are functions for creating pure typed arrays

Modification

• fill, set, and setTyped are functions for assigning values from external sources
• map and traverse allow you to create a new array from the existing values in another
• copyWithin allows you to set values to the array that exist in other parts of the array
• filter creates a new array without the values that don't pass a predicate
• reverse modifies an existing array in-place, with all values reversed
• sort modifies an existing array in-place, with all values sorted

Access

• elem, all, and any are functions for testing the contents of an array
• unsafeAt, hasIndex, and at are used to get values from an array, with an index
• foldr, foldrM, foldr1, foldr1M, foldl, foldlM, foldl1, foldl1M all can reduce an array
• find and findIndex are searching functions via a predicate
• indexOf and lastIndexOf are searching functions via equality
• slice returns a new typed array with a new copied underlying ArrayBuffer
• subArray returns a new typed array view of the same ArrayBuffer
• toString prints to a CSV, join allows you to supply the delimiter
• toArray returns an array of numeric values

Functions that find the first matching element based on a predicate and then do something with the array.

Functions that insert an element when it can not be found in the array.

Unsafe but faster functions due to no out of bounds checking.

This module provides a Builder monoid and a PutM monad for serializing Data.ArrayBuffer.Types.ArrayBuffers. See the package README for usage examples.

Writing to an ArrayBuffer is an Effectful activity, so most functions in this module must be run in a MonadEffect context.

For other operations for working with ArrayBuffer, see module Data.ArrayBuffer.ArrayBuffer in package arraybuffer.

This module represents the functional bindings to JavaScript's DataView objects. See MDN's spec for details.

Functions for generating typed arrays and values.

This module exports the NonEmptyArray constructor.

It is NOT intended for public use and is NOT versioned.

Its content may change in any way, at any time and without notice.

This module represents the functional bindings to JavaScript's ArrayBuffer objects. See MDN's spec for details.

Newtypes for the various bit-level numeric types.

This module represents type-level mappings between ArrayViewTypes and meaningful data.

Internal module.

You probably don’t want to import anything from this module.

Implementation Details

We want our Builder to be a data structure with

• O(1) monoid append
• O(n) fold

Our Builder implementation is an unbalanced binary tree.

For monoid append, what we actually get is O(1) when either the left or right tree is a singleton. If that's not true, then in the unlikely worst case append might be O(n).

Builder is optimized for what we consider to be normal usage, that is, snocing singleton elements to the end of the Builder.

If a Builder is built entirely by snocing, it will look like a left-only binary tree, a.k.a. a linked list.

           ④
          ╱
         ③
        ╱
       ②
      ╱
     ①

If two of these snoc-built trees are appended, then the new tree will look like

           ④
          ╱  ╲
         ③  ⑧
        ╱   ╱
       ②  ⑦
      ╱   ╱
     ①  ⑥
        ╱
       ⑤

This is all similar to bytestring-tree-builder , except that the Tree structure in bytestring-tree-builder only carries values in its leaves, which is how it achieves consistent O(1) appending, at the cost of a higher coefficient time factor on the fold.

We hope that this implementation is fairly fast, since it is similar to bytestring-tree-builder which “according to the benchmarks … beats all the alternatives.” However, we haven’t chosen this implementation because it’s fast, we've chosen this implementation because it’s simple. If someone wants to create a fast PureScript ArrayBuffer serialization library, then they can benchmark against this one to prove that the new one is fast.

One relatively cheap and simple performance improvement for this library would be to remove the Null constructor of Builder and instead use Javascript nulls?

In the longer term, it might make sense to try to change the Builder so that it works like the https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html . That’s the approach taken by https://pursuit.purescript.org/packages/purescript-dynamic-buffers .

Here are some benchmarks of different Haskell ByteString builders https://github.com/haskell-perf/strict-bytestring-builders

We've tried to design the API for this library with minimal assumptions, so that if we want to change the Builder implementation later then we can.