ghc/lib/exts/MutableArray.lhs

   1 %
   2 % (c) The AQUA Project, Glasgow University, 1997
   3 %
   4 \section[MutableArray]{The @MutableArray@ interface}
   5
   6 Mutable (byte)arrays interface, re-exports type types and operations
   7 over them from @ArrBase@. Have to be used in conjunction with
   8 @ST@.
   9
  10 \begin{code}
  11 module MutableArray
  12    (
  13     MutableArray(..),        -- not abstract
  14     MutableByteArray(..),
  15
  16     ST,
  17     Ix,
  18
  19     -- Creators:
  20     newArray,           -- :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
  21     newCharArray,
  22     newAddrArray,
  23     newIntArray,
  24     newFloatArray,
  25     newDoubleArray,     -- :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
  26
  27     boundsOfArray,      -- :: Ix ix => MutableArray s ix elt -> (ix, ix)
  28     boundsOfByteArray,  -- :: Ix ix => MutableByteArray s ix -> (ix, ix)
  29
  30     readArray,          -- :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
  31
  32     readCharArray,      -- :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
  33     readIntArray,       -- :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
  34     readAddrArray,      -- :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
  35     readFloatArray,     -- :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
  36     readDoubleArray,    -- :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
  37
  38     writeArray,         -- :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
  39     writeCharArray,     -- :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
  40     writeIntArray,      -- :: Ix ix => MutableByteArray s ix -> ix -> Int  -> ST s ()
  41     writeAddrArray,     -- :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
  42     writeFloatArray,    -- :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
  43     writeDoubleArray,   -- :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
  44
  45     freezeArray,        -- :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
  46     freezeCharArray,    -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  47     freezeIntArray,     -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  48     freezeAddrArray,    -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  49     freezeFloatArray,   -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  50     freezeDoubleArray,  -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  51
  52     unsafeFreezeArray,     -- :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
  53     unsafeFreezeByteArray, -- :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
  54     thawArray,             -- :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
  55
  56      -- the sizes are reported back are *in bytes*.
  57     sizeofByteArray,        -- :: Ix ix => ByteArray ix -> Int
  58     sizeofMutableByteArray, -- :: Ix ix => MutableByteArray s ix -> Int
  59
  60 {-
  61     readWord8Array,         -- :: Ix ix => MutableByteArray s ix -> Word8
  62     readWord16Array,        -- :: Ix ix => MutableByteArray s ix -> Word16
  63     readWord32Array,        -- :: Ix ix => MutableByteArray s ix -> Word32
  64 -}
  65     ) where
  66
  67 import PrelArr
  68 import PrelBase (sizeofMutableByteArray#, sizeofByteArray#, Int(..) )
  69 import ST
  70 import Ix
  71
  72 \end{code}
  73
  74 \begin{code}
  75 sizeofByteArray :: Ix ix => ByteArray ix -> Int
  76 sizeofByteArray (ByteArray _ arr#) =
  77   case (sizeofByteArray# arr#) of
  78     i# -> (I# i#)
  79
  80 sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int
  81 sizeofMutableByteArray (MutableByteArray _ arr#) =
  82   case (sizeofMutableByteArray# arr#) of
  83     i# -> (I# i#)
  84
  85 \end{code}
  86
  87 begin{code}
  88 readWord8Array  :: Ix ix => MutableByteArray RealWorld ix -> ix -> IO Word8
  89 readWord16Array :: Ix ix => MutableByteArray RealWorld ix -> ix -> IO Word16
  90 readWord32Array :: Ix ix => MutableByteArray RealWorld ix -> ix -> IO Word32
  91
  92 {- NB!!: The index for an array is in units of the element type being read -}
  93
  94 readWord8Array (MutableByteArray ixs arr#) n@(I# n#) =
  95     case sizeofMutableByteArray# arr#   of
  96       I# bytes#
  97        | n# ># (bytes# -# 1#) -> fail (userError "readWord8Array: index out of bounds "++show n)
  98        | otherwise            -> IO $ \ s# ->
  99          case readCharArray# barr# n# s#  of
 100            StateAndChar# s2# r# -> IOok s2# (W8# (int2Word# (ord# r#)))
 101
 102 readWord16Array (MutableByteArray ixs arr#) n@(I# n#) =
 103     case sizeofMutableByteArray# arr#   of
 104       I# bytes#
 105        | (2# *# n#) ># (bytes# -# 1#) -> fail (userError "readWord16Array: index out of bounds "++show n)
 106        | otherwise                    -> IO $ \ s# ->
 107          case readWordArray# barr# n# s#  of
 108            StateAndInt# s2# w# -> IOok s2# (wordToWord16 (W# w#))
 109
 110 readWord32Array (MutableByteArray ixs arr#) n@(I# n#) =
 111     case sizeofMutableByteArray# arr#   of
 112       I# bytes#
 113        | (4# *# n#) ># (bytes# -# 1#) -> fail (userError "readWord32Array: index out of bounds "++show n)
 114        | otherwise                    -> IO $ \ s# ->
 115          case readWordArray# barr# n# s#  of
 116            StateAndInt# s2# w# -> IOok s2# (wordToWord32 (W# w#))
 117
 118 end{code}