ghc/docs/users_guide/MutableArray.sgml

   1 <sect2> <idx/MutableArray/
   2 <label id="sec:MutableArray">
   3 <p>
   4
   5 The <tt/MutableArray/ interface provide operations for reading and
   6 writing values to mutable arrays. There's two kinds of
   7 mutable arrays, the mutatable version of Haskell <tt/Array/s
   8 and <em/mutable byte arrays/, chunks of memory containing
   9 values of some basic type.
  10
  11 <sect3> <idx/Mutable arrays/
  12 <label id="sec:MutableArray:mutable-arrays">
  13 <p>
  14
  15 The mutable array section of the API provides the following
  16 operations:
  17
  18 <tscreen><code>
  19
  20 -- mutable arrays:
  21 newArray      :: Ix ix -> (ix,ix) -> elt -> ST s (MutableArray s ix elt)
  22 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
  23 readArray     :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
  24 writeArray    :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
  25 freezeArray   :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
  26 thawArray     :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
  27
  28 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
  29 </code></tscreen>
  30 <nidx>newArray</nidx>
  31 <nidx>boundsOfArray</nidx>
  32 <nidx>readArray</nidx>
  33 <nidx>writeArray</nidx>
  34 <nidx>freezeArray</nidx>
  35 <nidx>thawArray</nidx>
  36 <nidx>unsafeFreezeArray</nidx>
  37
  38 <bf/Remarks:/
  39
  40 <itemize>
  41 <item>
  42 The <tt/freezeArray/ action converts a mutable array into an
  43 immutable one by copying, whereas <tt/unsafeFreezeArray/ returns
  44 an immutable array that is effectively just the type cast version
  45 of the mutable array. Should you write to the mutable array after
  46 it has been (unsafely) frozen, you'll side-effect the immutable
  47 array in the process. Please don't :-)
  48
  49 <item>
  50 The operation <tt/thawArray/ goes the other way, converting
  51 an immutable <tt/Array/ into a mutable one. This is done by
  52 copying. The operation <tt/unsafeThawArray/ is not provided
  53 (allthough it conceivably could be.)
  54 </itemize>
  55
  56 <sect3> <idx/Mutable byte arrays/
  57 <label id="sec:MutableArray:mutable-byte-arrays">
  58 <p>
  59
  60 <tscreen><code>
  61 -- creators:
  62 newCharArray      :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  63 newAddrArray      :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  64 newIntArray       :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  65 newWordArray      :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  66 newFloatArray     :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  67 newDoubleArray    :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  68 newStablePtrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  69
  70 boundsOfMutableByteArray
  71                    :: Ix ix => MutableByteArray s ix -> (ix, ix)
  72
  73 readCharArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
  74 readIntArray       :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
  75 readAddrArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
  76 readFloatArray     :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
  77 readDoubleArray    :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
  78 readStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s (StablePtr a)
  79 readWord8Array     :: Ix ix => MutableByteArray s ix -> Int -> ST s Word8
  80 readWord16Array    :: Ix ix => MutableByteArray s ix -> Int -> ST s Word16
  81 readWord32Array    :: Ix ix => MutableByteArray s ix -> Int -> ST s Word32
  82 readWord64Array    :: Ix ix => MutableByteArray s ix -> Int -> ST s Word64
  83 readInt8Array      :: Ix ix => MutableByteArray s ix -> Int -> ST s Int8
  84 readInt16Array     :: Ix ix => MutableByteArray s ix -> Int -> ST s Int16
  85 readInt32Array     :: Ix ix => MutableByteArray s ix -> Int -> ST s Int32
  86 readInt64Array     :: Ix ix => MutableByteArray s ix -> Int -> ST s Int64
  87
  88 writeCharArray        :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
  89 writeIntArray         :: Ix ix => MutableByteArray s ix -> ix -> Int  -> ST s ()
  90 writeAddrArray        :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
  91 writeFloatArray       :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
  92 writeDoubleArray      :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
  93 writeStablePtrArray   :: Ix ix => MutableByteArray s ix -> ix -> StablePtr a -> ST s ()
  94 writeWord8Array       :: Ix ix => MutableByteArray s ix -> Int -> Word8  -> ST s ()
  95 writeWord16Array      :: Ix ix => MutableByteArray s ix -> Int -> Word16 -> ST s ()
  96 writeWord32Array      :: Ix ix => MutableByteArray s ix -> Int -> Word32 -> ST s ()
  97 writeWord64Array      :: Ix ix => MutableByteArray s ix -> Int -> Word64 -> ST s ()
  98 writeInt8Array        :: Ix ix => MutableByteArray s ix -> Int -> Int8  -> ST s ()
  99 writeInt16Array       :: Ix ix => MutableByteArray s ix -> Int -> Int16 -> ST s ()
 100 writeInt32Array       :: Ix ix => MutableByteArray s ix -> Int -> Int32 -> ST s ()
 101 writeInt64Array       :: Ix ix => MutableByteArray s ix -> Int -> Int64 -> ST s ()
 102
 103 freezeCharArray       :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 104 freezeIntArray        :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 105 freezeAddrArray       :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 106 freezeFloatArray      :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 107 freezeDoubleArray     :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 108 freezeStablePtrArray  :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 109
 110 unsafeFreezeByteArray  :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 111
 112 sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int
 113
 114 </code></tscreen>
 115 <nidx>newCharArray</nidx>
 116 <nidx>newAddrArray</nidx>
 117 <nidx>newIntArray</nidx>
 118 <nidx>newFloatArray</nidx>
 119 <nidx>newDoubleArray</nidx>
 120 <nidx>boundsOfMutableByteArray</nidx>
 121 <nidx>readCharArray</nidx>
 122 <nidx>readIntArray</nidx>
 123 <nidx>readAddrArray</nidx>
 124 <nidx>readFloatArray</nidx>
 125 <nidx>readDoubleArray</nidx>
 126 <nidx>readWord8Array</nidx>
 127 <nidx>readWord16Array</nidx>
 128 <nidx>readWord32Array</nidx>
 129 <nidx>readWord64Array</nidx>
 130 <nidx>readInt8Array</nidx>
 131 <nidx>readInt16Array</nidx>
 132 <nidx>readInt32Array</nidx>
 133 <nidx>readInt64Array</nidx>
 134 <nidx>writeCharArray</nidx>
 135 <nidx>writeIntArray</nidx>
 136 <nidx>writeAddrArray</nidx>
 137 <nidx>writeFloatArray</nidx>
 138 <nidx>writeDoubleArray</nidx>
 139 <nidx>writeWord8Array</nidx>
 140 <nidx>writeWord16Array</nidx>
 141 <nidx>writeWord32Array</nidx>
 142 <nidx>writeWord64Array</nidx>
 143 <nidx>writeInt8Array</nidx>
 144 <nidx>writeInt16Array</nidx>
 145 <nidx>writeInt32Array</nidx>
 146 <nidx>writeInt64Array</nidx>
 147 <nidx>freezeCharArray</nidx>
 148 <nidx>freezeIntArray</nidx>
 149 <nidx>freezeAddrArray</nidx>
 150 <nidx>freezeFloatArray</nidx>
 151 <nidx>freezeDoubleArray</nidx>
 152 <nidx>unsafeFreezeByteArray</nidx>
 153
 154 <bf/Remarks:/
 155 <itemize>
 156 <item>
 157 A Mutable byte array is created by specifying its size in units of
 158 some basic type. For example,
 159
 160 <tscreen><code>
 161   mkPair :: ST s (MutableByteArray s Int)
 162   mkPair = newIntArray (0,1)
 163 </code></tscreen>
 164
 165 creates a mutable array capable of storing two <tt/Int/s. Notice
 166 that the range size <em/is not in bytes/, but in units of the
 167 basic type.
 168
 169 <item>
 170 A mutable byte array is not parameterised over the kind of values
 171 it contains. A consequence of this is that it is possible to
 172 have byte arrays containing a mix of basic types, or even read
 173 a value from the array at a different type from which it was
 174 written, e.g.,
 175
 176 <tscreen><code>
 177  isLitteEndian :: IO Bool
 178  isLitteEndian = stToIO $ do
 179     x <- newIntArray (0,1)
 180     writeIntArray x 1
 181     v <- readCharArray x 0
 182     return (v == chr 1)
 183 </code></tscreen>
 184
 185 It's left as an exercise for the reader to determine whether having
 186 byte arrays not be parameterised over the type of values they
 187 contain is a bug or a feature..
 188
 189 <item>
 190 As for mutable arrays, operations for turning mutable byte arrays
 191 into immutable byte arrays are also provided by the <tt/freeze*/
 192 class of actions. There's also the non-copying
 193 <tt/unsafeFreezeByteArray/.
 194 <p>
 195 Thawing of byte arrays is currently not supported.
 196
 197 <item>
 198 The operation <tt/sizeofMutableByteArray/ returns the size of
 199 the array, <em/in bytes./
 200 </itemize>