4.17. MutableArray

4.17.1. Mutable arrays

The mutable array section of the API provides the following operations:

-- mutable arrays: newArray :: Ix ix -> (ix,ix) -> elt -> ST s (MutableArray s ix elt) boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix) readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s () freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt) thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt) unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt) unsafeThawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)

Remarks:

• The freezeArray action converts a mutable array into an immutable one by copying, whereas unsafeFreezeArray returns an immutable array that is effectively just the type cast version of the mutable array. Should you write to the mutable array after it has been (unsafely) frozen, you'll side-effect the immutable array in the process. Please don't :-)

• The operation thawArray goes the other way, converting an immutable Array into a mutable one. This is done by copying. The operation unsafeThawArray is also provided, which places the same kind of proof obligation on the programmer as unsafeFreezeArray does.

4.17.2. Mutable byte arrays

-- creators: newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newWordArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) newStablePtrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix) boundsOfMutableByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix) readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double readStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s (StablePtr a) readWord8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word8 readWord16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word16 readWord32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word32 readWord64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word64 readInt8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int8 readInt16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int16 readInt32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int32 readInt64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int64 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s () writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s () writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s () writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s () writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s () writeStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> StablePtr a -> ST s () writeWord8Array :: Ix ix => MutableByteArray s ix -> ix -> Word8 -> ST s () writeWord16Array :: Ix ix => MutableByteArray s ix -> ix -> Word16 -> ST s () writeWord32Array :: Ix ix => MutableByteArray s ix -> ix -> Word32 -> ST s () writeWord64Array :: Ix ix => MutableByteArray s ix -> ix -> Word64 -> ST s () writeInt8Array :: Ix ix => MutableByteArray s ix -> ix -> Int8 -> ST s () writeInt16Array :: Ix ix => MutableByteArray s ix -> ix -> Int16 -> ST s () writeInt32Array :: Ix ix => MutableByteArray s ix -> ix -> Int32 -> ST s () writeInt64Array :: Ix ix => MutableByteArray s ix -> ix -> Int64 -> ST s () freezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix) unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix) sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int thawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix) unsafeThawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix)

Remarks:

• A Mutable byte array is created by specifying its size in units of some basic type. For example,

  mkPair :: ST s (MutableByteArray s Int) mkPair = newIntArray (0,1)

  creates a mutable array capable of storing two Ints. Notice that the range size is not in bytes, but in units of the basic type.

• A mutable byte array is not parameterised over the kind of values it contains. A consequence of this is that it is possible to have byte arrays containing a mix of basic types, or even read a value from the array at a different type from which it was written, e.g.,

  isLitteEndian :: IO Bool isLitteEndian = stToIO $ do x <- newIntArray (0,1) writeIntArray x 1 v <- readCharArray x 0 return (v == chr 1)

  It's left as an exercise for the reader to determine whether having byte arrays not be parameterised over the type of values they contain is a bug or a feature..

• As for mutable arrays, operations for turning mutable byte arrays into immutable byte arrays are also provided by the freeze* class of actions. There's also the non-copying unsafeFreezeByteArray.

• Operations for going the other way, where an immutable byte array is 'thawed' are also provided. thawByteArray does this by copying, whereas unsafeThawByteArray does not

• The operation sizeofMutableByteArray returns the size of the array, in bytes.