1 <sect2> <idx/MutableArray/
2 <label id="sec:MutableArray">
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.
11 <sect3> <idx/Mutable arrays/
12 <label id="sec:MutableArray:mutable-arrays">
15 The mutable array section of the API provides the following
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)
28 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
31 <nidx>boundsOfArray</nidx>
32 <nidx>readArray</nidx>
33 <nidx>writeArray</nidx>
34 <nidx>freezeArray</nidx>
35 <nidx>thawArray</nidx>
36 <nidx>unsafeFreezeArray</nidx>
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 :-)
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.)
56 <sect3> <idx/Mutable byte arrays/
57 <label id="sec:MutableArray:mutable-byte-arrays">
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)
70 boundsOfMutableByteArray
71 :: Ix ix => MutableByteArray s ix -> (ix, ix)
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
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 ()
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)
110 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
112 sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int
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>
157 A Mutable byte array is created by specifying its size in units of
158 some basic type. For example,
161 mkPair :: ST s (MutableByteArray s Int)
162 mkPair = newIntArray (0,1)
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
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
177 isLitteEndian :: IO Bool
178 isLitteEndian = stToIO $ do
179 x <- newIntArray (0,1)
181 v <- readCharArray x 0
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..
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/.
195 Thawing of byte arrays is currently not supported.
198 The operation <tt/sizeofMutableByteArray/ returns the size of
199 the array, <em/in bytes./