Data/Array/Storable.hs

   1 -----------------------------------------------------------------------------
   2 -- |
   3 -- Module      :  Data.Array.Storable
   4 -- Copyright   :  (c) The University of Glasgow 2001
   5 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   6 --
   7 -- Maintainer  :  libraries@haskell.org
   8 -- Stability   :  experimental
   9 -- Portability :  non-portable
  10 --
  11 -- A storable array is an IO-mutable array which stores its
  12 -- contents in a contiguous memory block living in the C
  13 -- heap. Elements are stored according to the class 'Storable'.
  14 -- You can obtain the pointer to the array contents to manipulate
  15 -- elements from languages like C.
  16 --
  17 -- It is similar to 'Data.Array.IO.IOUArray' but slower.
  18 -- Its advantage is that it's compatible with C.
  19 --
  20 -----------------------------------------------------------------------------
  21
  22 module Data.Array.Storable (
  23
  24     -- * Arrays of 'Storable' things.
  25     StorableArray, -- data StorableArray index element
  26                    --     -- index type must be in class Ix
  27                    --     -- element type must be in class Storable
  28
  29     -- * Overloaded mutable array interface
  30     -- | Module "Data.Array.MArray" provides the interface of storable arrays.
  31     -- They are instances of class 'MArray' (with the 'IO' monad).
  32     module Data.Array.MArray,
  33
  34     -- * Accessing the pointer to the array contents
  35     withStorableArray, -- :: StorableArray i e -> (Ptr e -> IO a) -> IO a
  36
  37     touchStorableArray -- :: StorableArray i e -> IO ()
  38     )
  39     where
  40
  41 import Prelude
  42
  43 import Data.Array.Base
  44 import Data.Array.MArray
  45 import Foreign hiding (newArray)
  46
  47 -- |The array type
  48 data StorableArray i e = StorableArray !i !i !(ForeignPtr e)
  49
  50 instance HasBounds StorableArray where
  51     bounds (StorableArray l u _) = (l,u)
  52
  53 instance Storable e => MArray StorableArray e IO where
  54
  55     newArray (l,u) init = do
  56         fp <- mallocForeignPtrArray size
  57         withForeignPtr fp $ \a ->
  58             sequence_ [pokeElemOff a i init | i <- [0..size-1]]
  59         return (StorableArray l u fp)
  60         where
  61         size = rangeSize (l,u)
  62
  63     newArray_ (l,u) = do
  64         fp <- mallocForeignPtrArray (rangeSize (l,u))
  65         return (StorableArray l u fp)
  66
  67     unsafeRead (StorableArray _ _ fp) i =
  68         withForeignPtr fp $ \a -> peekElemOff a i
  69
  70     unsafeWrite (StorableArray _ _ fp) i e =
  71         withForeignPtr fp $ \a -> pokeElemOff a i e
  72
  73 -- |The pointer to the array contents is obtained by 'withStorableArray'.
  74 -- The idea is similar to 'ForeignPtr' (used internally here).
  75 -- The pointer should be used only during execution of the 'IO' action
  76 -- retured by the function passed as argument to 'withStorableArray'.
  77 withStorableArray :: StorableArray i e -> (Ptr e -> IO a) -> IO a
  78 withStorableArray (StorableArray _ _ fp) f = withForeignPtr fp f
  79
  80 -- |If you want to use it afterwards, ensure that you
  81 -- 'touchStorableArray' after the last use of the pointer,
  82 -- so the array is not freed too early.
  83 touchStorableArray :: StorableArray i e -> IO ()
  84 touchStorableArray (StorableArray _ _ fp) = touchForeignPtr fp