Commit bb0b4b69 authored by rrt's avatar rrt
Browse files

[project @ 2000-01-05 11:06:23 by rrt]

Documentation changed from LinuxDoc to DocBook format, and license added to
the user guide.
parent 5ca77490
<sect2>The <idx/ByteArray/ interface
<label id="sec:byte-array">
<p>
<nidx>ByteArray interface (GHC extensions)</nidx>
<Sect2 id="sec-byte-array">
<Title>The ByteArray
<IndexTerm><Primary>ByteArray</Primary></IndexTerm>
interface
</Title>
<tt/ByteArray/s are chunks of immutable Haskell heap:
<Para>
<IndexTerm><Primary>ByteArray interface (GHC extensions)</Primary></IndexTerm>
</Para>
<tscreen><code>
<Para>
<Literal>ByteArray</Literal>s are chunks of immutable Haskell heap:
</Para>
<Para>
<ProgramListing>
data ByteArray ix -- abstract
-- instance of: Eq, CCallable.
newByteArray :: Ix ix => (ix,ix) -> ST s (ByteArray ix)
indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
sizeofByteArray :: Ix ix => ByteArray ix -> Int
</code></tscreen>
<nidx/newByteArray/
<nidx/indexCharArray/
<nidx/indexIntArray/
<nidx/indexAddrArray/
<nidx/indexFloatArray/
<nidx/indexDoubleArray/
<nidx/indexDoubleArray/
<nidx/sizeofByteArray/
<bf/Remarks:/
<itemize>
<item>
The operation <tt/newByteArray/ creates a byte array of length
equal to the range of its indices <em/in bytes/.
<item>
<tt/sizeofByteArray/ returns the size of the byte array, <em/in bytes/.
<item>
newByteArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (ByteArray ix)
indexCharArray :: Ix ix =&#62; ByteArray ix -&#62; ix -&#62; Char
indexIntArray :: Ix ix =&#62; ByteArray ix -&#62; ix -&#62; Int
indexAddrArray :: Ix ix =&#62; ByteArray ix -&#62; ix -&#62; Addr
indexFloatArray :: Ix ix =&#62; ByteArray ix -&#62; ix -&#62; Float
indexDoubleArray :: Ix ix =&#62; ByteArray ix -&#62; ix -&#62; Double
sizeofByteArray :: Ix ix =&#62; ByteArray ix -&#62; Int
</ProgramListing>
<IndexTerm><Primary>newByteArray</Primary></IndexTerm>
<IndexTerm><Primary>indexCharArray</Primary></IndexTerm>
<IndexTerm><Primary>indexIntArray</Primary></IndexTerm>
<IndexTerm><Primary>indexAddrArray</Primary></IndexTerm>
<IndexTerm><Primary>indexFloatArray</Primary></IndexTerm>
<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>sizeofByteArray</Primary></IndexTerm>
</Para>
<Para>
<Emphasis>Remarks:</Emphasis>
</Para>
<Para>
<ItemizedList>
<ListItem>
<Para>
The operation <Literal>newByteArray</Literal> creates a byte array of length
equal to the range of its indices <Emphasis>in bytes</Emphasis>.
</Para>
</ListItem>
<ListItem>
<Para>
<Literal>sizeofByteArray</Literal> returns the size of the byte array, <Emphasis>in bytes</Emphasis>.
</Para>
</ListItem>
<ListItem>
<Para>
Equality on byte arrays is value equality, not pointer equality (as is
the case for its mutable variant.) Two byte arrays are equal if
they're of the same length and they're pairwise equal.
</itemize>
</Para>
</ListItem>
</ItemizedList>
</Para>
</Sect2>
......@@ -5,10 +5,6 @@ ifeq "$(BIN_DIST)" "1"
install :: html dvi info
endif
# Split up the pages on a per-sect2 basis. Big HTML docs
# are a pain to flick through and use.
SRC_SGML2HTML_OPTS += -s 1
SGML_DOC = users_guide
# Generating index is semi-automatic, you need to:
......
<sect2> <idx/MutableArray/
<label id="MutableArray">
<p>
<Sect2 id="MutableArray">
<Title>MutableArray
<IndexTerm><Primary>MutableArray</Primary></IndexTerm>
</Title>
The <tt/MutableArray/ interface provide operations for reading and
<Para>
The <Literal>MutableArray</Literal> interface provide operations for reading and
writing values to mutable arrays. There's two kinds of
mutable arrays, the mutatable version of Haskell <tt/Array/s
and <em/mutable byte arrays/, chunks of memory containing
values of some basic type.
mutable arrays, the mutatable version of Haskell <Literal>Array</Literal>s
and <Emphasis>mutable byte arrays</Emphasis>, chunks of memory containing
values of some basic type.
</Para>
<sect3> <idx/Mutable arrays/
<label id="MutableArray:mutable-arrays">
<p>
<Sect3 id="MutableArray-mutable-arrays">
<Title>Mutable arrays
<IndexTerm><Primary>Mutable arrays</Primary></IndexTerm>
</Title>
<Para>
The mutable array section of the API provides the following
operations:
</Para>
<tscreen><code>
<Para>
<ProgramListing>
-- 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)
</code></tscreen>
<nidx>newArray</nidx>
<nidx>boundsOfArray</nidx>
<nidx>readArray</nidx>
<nidx>writeArray</nidx>
<nidx>freezeArray</nidx>
<nidx>thawArray</nidx>
<nidx>unsafeFreezeArray</nidx>
<nidx>unsafeThawArray</nidx>
<bf/Remarks:/
<itemize>
<item>
The <tt/freezeArray/ action converts a mutable array into an
immutable one by copying, whereas <tt/unsafeFreezeArray/ returns
newArray :: Ix ix -&#62; (ix,ix) -&#62; elt -&#62; ST s (MutableArray s ix elt)
boundsOfArray :: Ix ix =&#62; MutableArray s ix elt -&#62; (ix, ix)
readArray :: Ix ix =&#62; MutableArray s ix elt -&#62; ix -&#62; ST s elt
writeArray :: Ix ix =&#62; MutableArray s ix elt -&#62; ix -&#62; elt -&#62; ST s ()
freezeArray :: Ix ix =&#62; MutableArray s ix elt -&#62; ST s (Array ix elt)
thawArray :: Ix ix =&#62; Array ix elt -&#62; ST s (MutableArray s ix elt)
unsafeFreezeArray :: Ix ix =&#62; MutableArray s ix elt -&#62; ST s (Array ix elt)
unsafeThawArray :: Ix ix =&#62; Array ix elt -&#62; ST s (MutableArray s ix elt)
</ProgramListing>
<IndexTerm><Primary>newArray</Primary></IndexTerm>
<IndexTerm><Primary>boundsOfArray</Primary></IndexTerm>
<IndexTerm><Primary>readArray</Primary></IndexTerm>
<IndexTerm><Primary>writeArray</Primary></IndexTerm>
<IndexTerm><Primary>freezeArray</Primary></IndexTerm>
<IndexTerm><Primary>thawArray</Primary></IndexTerm>
<IndexTerm><Primary>unsafeFreezeArray</Primary></IndexTerm>
<IndexTerm><Primary>unsafeThawArray</Primary></IndexTerm>
</Para>
<Para>
<Emphasis>Remarks:</Emphasis>
</Para>
<Para>
<ItemizedList>
<ListItem>
<Para>
The <Literal>freezeArray</Literal> action converts a mutable array into an
immutable one by copying, whereas <Literal>unsafeFreezeArray</Literal> 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 :-)
<item>
The operation <tt/thawArray/ goes the other way, converting
an immutable <tt/Array/ into a mutable one. This is done by
copying. The operation <tt/unsafeThawArray/ is also provided,
</Para>
</ListItem>
<ListItem>
<Para>
The operation <Literal>thawArray</Literal> goes the other way, converting
an immutable <Literal>Array</Literal> into a mutable one. This is done by
copying. The operation <Literal>unsafeThawArray</Literal> is also provided,
which places the same kind of proof obligation on the programmer
as <tt/unsafeFreezeArray/ does.
</itemize>
as <Literal>unsafeFreezeArray</Literal> does.
</Para>
</ListItem>
</ItemizedList>
<sect3> <idx/Mutable byte arrays/
<label id="MutableArray:mutable-byte-arrays">
<p>
</Para>
<tscreen><code>
</Sect3>
<Sect3 id="MutableArray-mutable-byte-arrays">
<Title>Mutable byte arrays
<IndexTerm><Primary>Mutable byte arrays</Primary></IndexTerm>
</Title>
<Para>
<ProgramListing>
-- 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 ()
freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
freezeStablePtrArray :: 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)
</code></tscreen>
<nidx>newCharArray</nidx>
<nidx>newAddrArray</nidx>
<nidx>newIntArray</nidx>
<nidx>newFloatArray</nidx>
<nidx>newDoubleArray</nidx>
<nidx>boundsOfMutableByteArray</nidx>
<nidx>readCharArray</nidx>
<nidx>readIntArray</nidx>
<nidx>readAddrArray</nidx>
<nidx>readFloatArray</nidx>
<nidx>readDoubleArray</nidx>
<nidx>readWord8Array</nidx>
<nidx>readWord16Array</nidx>
<nidx>readWord32Array</nidx>
<nidx>readWord64Array</nidx>
<nidx>readInt8Array</nidx>
<nidx>readInt16Array</nidx>
<nidx>readInt32Array</nidx>
<nidx>readInt64Array</nidx>
<nidx>writeCharArray</nidx>
<nidx>writeIntArray</nidx>
<nidx>writeAddrArray</nidx>
<nidx>writeFloatArray</nidx>
<nidx>writeDoubleArray</nidx>
<nidx>writeWord8Array</nidx>
<nidx>writeWord16Array</nidx>
<nidx>writeWord32Array</nidx>
<nidx>writeWord64Array</nidx>
<nidx>writeInt8Array</nidx>
<nidx>writeInt16Array</nidx>
<nidx>writeInt32Array</nidx>
<nidx>writeInt64Array</nidx>
<nidx>freezeCharArray</nidx>
<nidx>freezeIntArray</nidx>
<nidx>freezeAddrArray</nidx>
<nidx>freezeFloatArray</nidx>
<nidx>freezeDoubleArray</nidx>
<nidx>unsafeFreezeByteArray</nidx>
<nidx>unsafeThawByteArray</nidx>
<nidx>thawByteArray</nidx>
<bf/Remarks:/
<itemize>
<item>
newCharArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newAddrArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newIntArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newWordArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newFloatArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newDoubleArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
newStablePtrArray :: Ix ix =&#62; (ix,ix) -&#62; ST s (MutableByteArray s ix)
boundsOfMutableByteArray
:: Ix ix =&#62; MutableByteArray s ix -&#62; (ix, ix)
readCharArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Char
readIntArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Int
readAddrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Addr
readFloatArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Float
readDoubleArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Double
readStablePtrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s (StablePtr a)
readWord8Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Word8
readWord16Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Word16
readWord32Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Word32
readWord64Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Word64
readInt8Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Int8
readInt16Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Int16
readInt32Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Int32
readInt64Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; ST s Int64
writeCharArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Char -&#62; ST s ()
writeIntArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Int -&#62; ST s ()
writeAddrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Addr -&#62; ST s ()
writeFloatArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Float -&#62; ST s ()
writeDoubleArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Double -&#62; ST s ()
writeStablePtrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; StablePtr a -&#62; ST s ()
writeWord8Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Word8 -&#62; ST s ()
writeWord16Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Word16 -&#62; ST s ()
writeWord32Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Word32 -&#62; ST s ()
writeWord64Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Word64 -&#62; ST s ()
writeInt8Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Int8 -&#62; ST s ()
writeInt16Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Int16 -&#62; ST s ()
writeInt32Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Int32 -&#62; ST s ()
writeInt64Array :: Ix ix =&#62; MutableByteArray s ix -&#62; ix -&#62; Int64 -&#62; ST s ()
freezeCharArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
freezeIntArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
freezeAddrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
freezeFloatArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
freezeDoubleArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
freezeStablePtrArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
unsafeFreezeByteArray :: Ix ix =&#62; MutableByteArray s ix -&#62; ST s (ByteArray ix)
sizeofMutableByteArray :: Ix ix =&#62; MutableByteArray s ix -&#62; Int
thawByteArray :: Ix ix =&#62; ByteArray ixt -&#62; ST s (MutableByteArray s ix)
unsafeThawByteArray :: Ix ix =&#62; ByteArray ixt -&#62; ST s (MutableByteArray s ix)
</ProgramListing>
<IndexTerm><Primary>newCharArray</Primary></IndexTerm>
<IndexTerm><Primary>newAddrArray</Primary></IndexTerm>
<IndexTerm><Primary>newIntArray</Primary></IndexTerm>
<IndexTerm><Primary>newFloatArray</Primary></IndexTerm>
<IndexTerm><Primary>newDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>boundsOfMutableByteArray</Primary></IndexTerm>
<IndexTerm><Primary>readCharArray</Primary></IndexTerm>
<IndexTerm><Primary>readIntArray</Primary></IndexTerm>
<IndexTerm><Primary>readAddrArray</Primary></IndexTerm>
<IndexTerm><Primary>readFloatArray</Primary></IndexTerm>
<IndexTerm><Primary>readDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>readWord8Array</Primary></IndexTerm>
<IndexTerm><Primary>readWord16Array</Primary></IndexTerm>
<IndexTerm><Primary>readWord32Array</Primary></IndexTerm>
<IndexTerm><Primary>readWord64Array</Primary></IndexTerm>
<IndexTerm><Primary>readInt8Array</Primary></IndexTerm>
<IndexTerm><Primary>readInt16Array</Primary></IndexTerm>
<IndexTerm><Primary>readInt32Array</Primary></IndexTerm>
<IndexTerm><Primary>readInt64Array</Primary></IndexTerm>
<IndexTerm><Primary>writeCharArray</Primary></IndexTerm>
<IndexTerm><Primary>writeIntArray</Primary></IndexTerm>
<IndexTerm><Primary>writeAddrArray</Primary></IndexTerm>
<IndexTerm><Primary>writeFloatArray</Primary></IndexTerm>
<IndexTerm><Primary>writeDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>writeWord8Array</Primary></IndexTerm>
<IndexTerm><Primary>writeWord16Array</Primary></IndexTerm>
<IndexTerm><Primary>writeWord32Array</Primary></IndexTerm>
<IndexTerm><Primary>writeWord64Array</Primary></IndexTerm>
<IndexTerm><Primary>writeInt8Array</Primary></IndexTerm>
<IndexTerm><Primary>writeInt16Array</Primary></IndexTerm>
<IndexTerm><Primary>writeInt32Array</Primary></IndexTerm>
<IndexTerm><Primary>writeInt64Array</Primary></IndexTerm>
<IndexTerm><Primary>freezeCharArray</Primary></IndexTerm>
<IndexTerm><Primary>freezeIntArray</Primary></IndexTerm>
<IndexTerm><Primary>freezeAddrArray</Primary></IndexTerm>
<IndexTerm><Primary>freezeFloatArray</Primary></IndexTerm>
<IndexTerm><Primary>freezeDoubleArray</Primary></IndexTerm>
<IndexTerm><Primary>unsafeFreezeByteArray</Primary></IndexTerm>
<IndexTerm><Primary>unsafeThawByteArray</Primary></IndexTerm>
<IndexTerm><Primary>thawByteArray</Primary></IndexTerm>
</Para>
<Para>
<Emphasis>Remarks:</Emphasis>
<ItemizedList>
<ListItem>
<Para>
A Mutable byte array is created by specifying its size in units of
some basic type. For example,
<tscreen><code>
mkPair :: ST s (MutableByteArray s Int)
mkPair = newIntArray (0,1)
</code></tscreen>
creates a mutable array capable of storing two <tt/Int/s. Notice
that the range size <em/is not in bytes/, but in units of the
<ProgramListing>
mkPair :: ST s (MutableByteArray s Int)
mkPair = newIntArray (0,1)
</ProgramListing>
creates a mutable array capable of storing two <Literal>Int</Literal>s. Notice
that the range size <Emphasis>is not in bytes</Emphasis>, but in units of the
basic type.
<item>
</Para>
</ListItem>
<ListItem>
<Para>
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.,
<tscreen><code>
isLitteEndian :: IO Bool
isLitteEndian = stToIO $ do
x <- newIntArray (0,1)
writeIntArray x 1
v <- readCharArray x 0
return (v == chr 1)
</code></tscreen>
<ProgramListing>
isLitteEndian :: IO Bool
isLitteEndian = stToIO $ do
x &#60;- newIntArray (0,1)
writeIntArray x 1
v &#60;- readCharArray x 0
return (v == chr 1)
</ProgramListing>
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..
<item>
</Para>
</ListItem>
<ListItem>
<Para>
As for mutable arrays, operations for turning mutable byte arrays
into immutable byte arrays are also provided by the <tt/freeze*/
into immutable byte arrays are also provided by the <Literal>freeze*</Literal>
class of actions. There's also the non-copying
<tt/unsafeFreezeByteArray/.
<p>
<item>
<Literal>unsafeFreezeByteArray</Literal>.
</Para>
</ListItem>
<ListItem>
<Para>
Operations for going the other way, where an immutable byte
array is 'thawed' are also provided. <tt/thawByteArray/ does
this by copying, whereas <tt/unsafeThawByteArray/ does not
array is 'thawed' are also provided. <Literal>thawByteArray</Literal> does
this by copying, whereas <Literal>unsafeThawByteArray</Literal> does not
</Para>
</ListItem>
<ListItem>
<Para>
The operation <Literal>sizeofMutableByteArray</Literal> returns the size of
the array, <Emphasis>in bytes.</Emphasis>
</Para>
</ListItem>
</ItemizedList>
</Para>
</Sect3>
<item>
The operation <tt/sizeofMutableByteArray/ returns the size of
the array, <em/in bytes./
</itemize>
</Sect2>
%************************************************************************
%* *
<sect>Building and using Win32 DLLs
<label id="win32-dlls">
<p>
<nidx>Dynamic link libraries, Win32</nidx>
<nidx>DLLs, Win32</nidx>
%* *
%************************************************************************
<Chapter id="win32-dlls">
<Title>Building and using Win32 DLLs
</Title>
<Para>
<IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm>
<IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm>
On Win32 platforms, the compiler is capable of both producing and using
dynamic link libraries (DLLs) containing ghc-compiled code. This
section shows you how to make use of this facility.
</Para>
%************************************************************************
%* *
<sect1>Linking with DLLs
<label id="win32-dlls:link">
<p>
%* *
%************************************************************************
<Sect1 id="win32-dlls-link">
<Title>Linking with DLLs
</Title>
<Para>
The default on Win32 platforms is to link applications in such a way
that the executables will use the Prelude and system libraries DLLs,
rather than contain (large chunks of) them. This is transparent at the
command-line, so
</Para>
<tscreen><verb>
<Para>
<Screen>
sh$ cat main.hs
module Main where
main = putStrLn "hello, world!"
......@@ -37,133 +35,186 @@ sh$ ls -l main.exe
sh$ ./main
hello, world!
sh$
</verb></tscreen>
</Screen>
</Para>
will give you a binary as before, but the <tt>main.exe</tt> generated
<Para>
will give you a binary as before, but the <Literal>main.exe</Literal> generated
will use the Prelude and RTS DLLs instead.
</Para>
<Para>
6K for a <Literal>"hello, world"</Literal> application - not bad, huh? :-)
</Para>
6K for a <tt>"hello, world"</tt> application - not bad, huh? :-)
</Sect1>
%************************************************************************
%* *
<sect1>Not linking with DLLs
<label id="win32-dlls:linking-static">