Streamly.Data.MutArray

An unboxed mutable array. An array is created with a given length and capacity. Length is the number of valid elements in the array. Capacity is the maximum number of elements that the array can be expanded to without having to reallocate the memory.

The elements in the array can be mutated in-place without changing the reference (constructor). However, the length of the array cannot be mutated in-place. A new array reference is generated when the length changes. When the length is increased (upto the maximum reserved capacity of the array), the array is not reallocated and the new reference uses the same underlying memory as the old one.

Several routines in this module allow the programmer to control the capacity of the array. The programmer can control the trade-off between memory usage and performance impact due to reallocations when growing or shrinking the array.

Allocates an unpinned array of zero length but growable to the specified capacity without reallocation.

Allocates a pinned array of zero length but growable to the specified capacity without reallocation.

Create a MutArray from the first N elements of a list. The array is allocated to size N, if the list terminates before N elements then the array may hold less than N elements.

Create a MutArray from a list. The list must be of finite size.

createOf n folds a maximum of n elements from the input stream to an MutArray.

The array capacity is guranteed to be at least n.

>>> createOf = MutArray.createWithOf MutArray.emptyOf>>> createOf n = Fold.take n (MutArray.unsafeCreateOf n)>>> createOf n = MutArray.appendMax n MutArray.empty

Fold the whole input to a single array.

Same as 'createMinOf using an initial array size of arrayChunkBytes bytes rounded up to the element size. If the array is expected to be smaller than arrayChunkBytes then use createMinOf to avoid wasting memory.

Caution! Do not use this on infinite streams.

Return a copy of the array in pinned memory if unpinned, else return the original array.

Return a copy of the array in unpinned memory if pinned, else return the original array.

Return True if the array is allocated in pinned memory.

The array is mutated to append an additional element to it. If there is no reserved space available in the array then it is reallocated to double the original size and aligned to a power of 2.

This is useful to reduce allocations when appending unknown number of elements.

Note that the returned array may be a mutated version of the original array.

Performs only O(n * log n) copies to grow, but is liberal with memory allocation compared to snocGrowBy.

Append n elements to an existing array. Any free space left in the array after appending n elements is lost.

>>> appendN n initial = Fold.take n (MutArray.unsafeAppendN n initial)

Fold append2 arr mutates the array arr to append the input stream. If there is no reserved space available in the array it is reallocated to double the size and aligned to power of 2.

Note that the returned array may be a mutated version of original array.

>>> append2 arr = Fold.foldlM' MutArray.snoc (pure arr)

O(1) Write the given element at the given index in the array. Performs in-place mutation of the array.

>>> putIndex ix arr val = MutArray.modifyIndex ix arr (const (val, ()))>>> f = MutArray.putIndices>>> putIndex ix arr val = Stream.fold (f arr) (Stream.fromPure (ix, val))

Write the given element to the given index of the array. Does not check if the index is out of bounds of the array.

Pre-release

Modify a given index of an array using a modifier function.

Pre-release

Modify a given index of an array using a modifier function.

Unsafe because it does not check the bounds of the array.

Pre-release

Modify each element of an array using the supplied modifier function.

This is an in-place equivalent of an immutable map operation.

Pre-release

O(1) Lookup the element at the given index. Index starts from 0.

Return the element at the specified index without checking the bounds.

Unsafe because it does not check the bounds of the array.

Convert a MutArray into a list.

Convert a MutArray into a stream.

>>> read = Stream.unfold MutArray.reader

Convert a MutArray into a stream in reverse order.

>>> readRev = Stream.unfold MutArray.readerRev

Unfold an array into a stream.

Unfold an array into a stream in reverse order.

chunksOf n stream groups the elements in the input stream into arrays of n elements each.

Same as the following but may be more efficient:

>>> chunksOf n = Stream.foldMany (MutArray.createOf n)

Pre-release

Cast an array having elements of type a into an array having elements of type b. The length of the array should be a multiple of the size of the target element otherwise Nothing is returned.

Cast an MutArray a into an MutArray Word8.

O(1) Get the used length of the array i.e. the number of elements in the array.

Note that byteLength is less expensive than this operation, as length involves a costly division operation.

The Unbox type class provides operations for serialization (unboxing) and deserialization (boxing) of fixed-length, non-recursive Haskell data types to and from their byte stream representation.

Unbox uses fixed size encoding, therefore, size is independent of the value, it must be determined solely by the type. This restriction makes types with Unbox instances suitable for storing in arrays. Note that sum types may have multiple constructors of different sizes, the size of a sum type is computed as the maximum required by any constructor.

The peekAt operation reads as many bytes from the mutable byte array as the size of the data type and builds a Haskell data type from these bytes. pokeAt operation converts a Haskell data type to its binary representation which consists of size bytes and then stores these bytes into the mutable byte array. These operations do not check the bounds of the array, the user of the type class is expected to check the bounds before peeking or poking.

IMPORTANT: The serialized data's byte ordering remains the same as the host machine's byte order. Therefore, it can not be deserialized from host machines with a different byte ordering.

Instances can be derived via Generics, Template Haskell, or written manually. Note that the data type must be non-recursive. WARNING! Generic and Template Haskell deriving, both hang for recursive data types. Deriving via Generics is more convenient but Template Haskell should be preferred over Generics for the following reasons:

1. Instances derived via Template Haskell provide better and more reliable performance.

2. Generic deriving allows only 256 fields or constructor tags whereas template Haskell has no limit.

Here is an example, for deriving an instance of this type class using generics:

>>> import GHC.Generics (Generic)>>> :{data Object = Object    { _int0 :: Int    , _int1 :: Int    } deriving Generic:}

>>> import Streamly.Data.MutByteArray (Unbox(..))>>> instance Unbox Object

To derive the instance via Template Haskell:

import Streamly.Data.MutByteArray (deriveUnbox)
$(deriveUnbox [d|instance Unbox Object|])

See Streamly.Data.MutByteArray.deriveUnbox for more information on deriving using Template Haskell.

If you want to write the instance manually:

>>> :{instance Unbox Object where    sizeOf _ = 16    peekAt i arr = do       -- Check the array bounds        x0 <- peekAt i arr        x1 <- peekAt (i + 8) arr        return $ Object x0 x1    pokeAt i arr (Object x0 x1) = do       -- Check the array bounds        pokeAt i arr x0        pokeAt (i + 8) arr x1:}

Allocates a pinned array of zero length but growable to the specified capacity without reallocation.

Write the given element to the given index of the array. Does not check if the index is out of bounds of the array.

Pre-release

Modify a given index of an array using a modifier function.

Unsafe because it does not check the bounds of the array.

Pre-release

Return the element at the specified index without checking the bounds.

Unsafe because it does not check the bounds of the array.

append action mutates the array generated by action to append the input stream. If there is no reserved space available in the array it is reallocated to double the size and aligned to power of 2.

Note that the returned array may be a mutated version of original array.

>>> append = Fold.foldlM' MutArray.snoc