ghc/docs/users_guide/MutableArray.sgml

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