Streamly.Data.MutArray

This module provides a mutable version of Streamly.Data.Array. The contents of a mutable array can be modified in-place. For general documentation, please refer to the original module.

Please refer to Streamly.Internal.Data.Array.Mut for functions that have not yet been released.

For mutable arrays that work on boxed types, not requiring the Unbox constraint, please refer to Streamly.Data.MutArray.Generic.

Setup

To execute the code examples provided in this module in ghci, please run the following commands first.

>>> :m
>>> import qualified Streamly.Data.Fold as Fold
>>> import qualified Streamly.Data.MutArray as MutArray
>>> import qualified Streamly.Data.Stream as Stream

For APIs that have not been released yet.

>>> import Streamly.Internal.Data.Array.Mut as MutArray

Mutable Array Type

data MutArray a

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.

Construction

new :: (MonadIO m, Unbox a) => Int -> m (MutArray a)

Allocates an empty unpinned array that can hold count items. The memory of the array is uninitialized.

newPinned :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a)

Allocates an empty pinned array that can hold count items. The memory of the array is uninitialized and the allocation is aligned as per the Unboxed instance of the type.

fromListN :: (MonadIO m, Unbox a) => Int -> [a] -> m (MutArray a)

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.

fromList :: (MonadIO m, Unbox a) => [a] -> m (MutArray a)

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

writeN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)

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

>>> writeN = MutArray.writeNWith MutArray.newPinned
>>> writeN n = Fold.take n (MutArray.writeNUnsafe n)
>>> writeN n = MutArray.writeAppendN n (MutArray.newPinned n)

write :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)

Fold the whole input to a single array.

Same as writeWith using an initial array size of arrayChunkBytes bytes rounded up to the element size.

Caution! Do not use this on infinite streams.

Appending elements

snoc :: forall m a. (MonadIO m, Unbox a) => MutArray a -> a -> m (MutArray a)

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.

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.

>>> snoc = MutArray.snocWith (* 2)

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

Appending streams

writeAppendN :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a) -> Fold m a (MutArray a)

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

>>> writeAppendN n initial = Fold.take n (MutArray.writeAppendNUnsafe n initial)

writeAppend :: forall m a. (MonadIO m, Unbox a) => m (MutArray a) -> Fold m a (MutArray a)

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.

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

>>> writeAppend = MutArray.writeAppendWith (* 2)

Inplace mutation

putIndex :: forall m a. (MonadIO m, Unbox a) => Int -> MutArray a -> a -> m ()

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))

Random access

getIndex :: forall m a. (MonadIO m, Unbox a) => Int -> MutArray a -> m a

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

Conversion

toList :: forall m a. (MonadIO m, Unbox a) => MutArray a -> m [a]

Convert a MutArray into a list.

Unfolds

reader :: forall m a. (MonadIO m, Unbox a) => Unfold m (MutArray a) a

Unfold an array into a stream.

readerRev :: forall m a. (MonadIO m, Unbox a) => Unfold m (MutArray a) a

Unfold an array into a stream in reverse order.

Casting

cast :: forall a b. Unbox b => MutArray a -> Maybe (MutArray b)

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.

asBytes :: MutArray a -> MutArray Word8

Cast an MutArray a into an MutArray Word8.

Size

length :: forall a. Unbox a => MutArray a -> Int

O(1) Get the 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.

Unbox Type Class

class Unbox a where

A type implementing the Unbox interface supplies operations for reading and writing the type from and to a mutable byte array (an unboxed representation of the type) in memory. The read operation peekByteIndex deserializes the boxed type from the mutable byte array. The write operation pokeByteIndex serializes the boxed type to the mutable byte array.

Instances can be derived via Generic. Note that the data type must be non-recursive. Here is an example, for deriving an instance of this type class.

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

WARNING! Generic deriving hangs for recursive data types.

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

If you want to write the instance manually:

>>> :{
instance Unbox Object where
    sizeOf _ = 16
    peekByteIndex i arr = do
        x0 <- peekByteIndex i arr
        x1 <- peekByteIndex (i + 8) arr
        return $ Object x0 x1
    pokeByteIndex i arr (Object x0 x1) = do
        pokeByteIndex i arr x0
        pokeByteIndex (i + 8) arr x1
:}

Minimal complete definition

Nothing

Methods

sizeOf :: Proxy a -> Int

Get the size. Size cannot be zero.

default sizeOf :: SizeOfRep (Rep a) => Proxy a -> Int

peekByteIndex :: Int -> MutableByteArray -> IO a

Read an element of type "a" from a MutableByteArray given the byte index.

IMPORTANT: The implementation of this interface may not check the bounds of the array, the caller must not assume that.

default peekByteIndex :: (Generic a, PeekRep (Rep a)) => Int -> MutableByteArray -> IO a

pokeByteIndex :: Int -> MutableByteArray -> a -> IO ()

Write an element of type "a" to a MutableByteArray given the byte index.

IMPORTANT: The implementation of this interface may not check the bounds of the array, the caller must not assume that.

default pokeByteIndex :: (Generic a, PokeRep (Rep a)) => Int -> MutableByteArray -> a -> IO ()

Instances

Unbox IntPtr

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy IntPtr -> Int

peekByteIndex :: Int -> MutableByteArray -> IO IntPtr

pokeByteIndex :: Int -> MutableByteArray -> IntPtr -> IO ()

Unbox WordPtr

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy WordPtr -> Int

peekByteIndex :: Int -> MutableByteArray -> IO WordPtr

pokeByteIndex :: Int -> MutableByteArray -> WordPtr -> IO ()

Unbox Fingerprint

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Fingerprint -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Fingerprint

pokeByteIndex :: Int -> MutableByteArray -> Fingerprint -> IO ()

Unbox Int16

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Int16 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Int16

pokeByteIndex :: Int -> MutableByteArray -> Int16 -> IO ()

Unbox Int32

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Int32 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Int32

pokeByteIndex :: Int -> MutableByteArray -> Int32 -> IO ()

Unbox Int64

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Int64 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Int64

pokeByteIndex :: Int -> MutableByteArray -> Int64 -> IO ()

Unbox Int8

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Int8 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Int8

pokeByteIndex :: Int -> MutableByteArray -> Int8 -> IO ()

Unbox IoSubSystem

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy IoSubSystem -> Int

peekByteIndex :: Int -> MutableByteArray -> IO IoSubSystem

pokeByteIndex :: Int -> MutableByteArray -> IoSubSystem -> IO ()

Unbox Word16

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Word16 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Word16

pokeByteIndex :: Int -> MutableByteArray -> Word16 -> IO ()

Unbox Word32

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Word32 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Word32

pokeByteIndex :: Int -> MutableByteArray -> Word32 -> IO ()

Unbox Word64

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Word64 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Word64

pokeByteIndex :: Int -> MutableByteArray -> Word64 -> IO ()

Unbox Word8

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Word8 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Word8

pokeByteIndex :: Int -> MutableByteArray -> Word8 -> IO ()

Unbox MicroSecond64

Defined in Streamly.Internal.Data.Time.Units

Methods

sizeOf :: Proxy MicroSecond64 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO MicroSecond64

pokeByteIndex :: Int -> MutableByteArray -> MicroSecond64 -> IO ()

Unbox MilliSecond64

Defined in Streamly.Internal.Data.Time.Units

Methods

sizeOf :: Proxy MilliSecond64 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO MilliSecond64

pokeByteIndex :: Int -> MutableByteArray -> MilliSecond64 -> IO ()

Unbox NanoSecond64

Defined in Streamly.Internal.Data.Time.Units

Methods

sizeOf :: Proxy NanoSecond64 -> Int

peekByteIndex :: Int -> MutableByteArray -> IO NanoSecond64

pokeByteIndex :: Int -> MutableByteArray -> NanoSecond64 -> IO ()

Unbox ()

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy () -> Int

peekByteIndex :: Int -> MutableByteArray -> IO ()

pokeByteIndex :: Int -> MutableByteArray -> () -> IO ()

Unbox Bool

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Bool -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Bool

pokeByteIndex :: Int -> MutableByteArray -> Bool -> IO ()

Unbox Char

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Char -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Char

pokeByteIndex :: Int -> MutableByteArray -> Char -> IO ()

Unbox Double

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Double -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Double

pokeByteIndex :: Int -> MutableByteArray -> Double -> IO ()

Unbox Float

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Float -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Float

pokeByteIndex :: Int -> MutableByteArray -> Float -> IO ()

Unbox Int

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Int -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Int

pokeByteIndex :: Int -> MutableByteArray -> Int -> IO ()

Unbox Word

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy Word -> Int

peekByteIndex :: Int -> MutableByteArray -> IO Word

pokeByteIndex :: Int -> MutableByteArray -> Word -> IO ()

Unbox a => Unbox (Complex a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Complex a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Complex a)

pokeByteIndex :: Int -> MutableByteArray -> Complex a -> IO ()

Unbox a => Unbox (Identity a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Identity a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Identity a)

pokeByteIndex :: Int -> MutableByteArray -> Identity a -> IO ()

Unbox a => Unbox (Down a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Down a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Down a)

pokeByteIndex :: Int -> MutableByteArray -> Down a -> IO ()

Unbox (FunPtr a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (FunPtr a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (FunPtr a)

pokeByteIndex :: Int -> MutableByteArray -> FunPtr a -> IO ()

Unbox (Ptr a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Ptr a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Ptr a)

pokeByteIndex :: Int -> MutableByteArray -> Ptr a -> IO ()

Unbox a => Unbox (Ratio a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Ratio a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Ratio a)

pokeByteIndex :: Int -> MutableByteArray -> Ratio a -> IO ()

Unbox (StablePtr a)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (StablePtr a) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (StablePtr a)

pokeByteIndex :: Int -> MutableByteArray -> StablePtr a -> IO ()

Unbox a => Unbox (Const a b)

Defined in Streamly.Internal.Data.Unboxed

Methods

sizeOf :: Proxy (Const a b) -> Int

peekByteIndex :: Int -> MutableByteArray -> IO (Const a b)

pokeByteIndex :: Int -> MutableByteArray -> Const a b -> IO ()