1 -----------------------------------------------------------------------------
3 -- Module : Data.Array.Storable
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : non-portable (uses Data.Array.MArray)
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.
17 -- It is similar to 'Data.Array.IO.IOUArray' but slower.
18 -- Its advantage is that it's compatible with C.
20 -----------------------------------------------------------------------------
22 module Data.Array.Storable (
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
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,
34 -- * Accessing the pointer to the array contents
35 withStorableArray, -- :: StorableArray i e -> (Ptr e -> IO a) -> IO a
37 touchStorableArray, -- :: StorableArray i e -> IO ()
39 unsafeForeignPtrToStorableArray
45 import Data.Array.Base
46 import Data.Array.MArray
47 import Foreign hiding (newArray)
50 data StorableArray i e = StorableArray !i !i !(ForeignPtr e)
52 instance Storable e => MArray StorableArray e IO where
53 getBounds (StorableArray l u _) = return (l,u)
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)
61 size = rangeSize (l,u)
64 fp <- mallocForeignPtrArray (rangeSize (l,u))
65 return (StorableArray l u fp)
67 unsafeRead (StorableArray _ _ fp) i =
68 withForeignPtr fp $ \a -> peekElemOff a i
70 unsafeWrite (StorableArray _ _ fp) i e =
71 withForeignPtr fp $ \a -> pokeElemOff a i e
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
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
86 -- |Construct a 'StorableArray' from an arbitrary 'ForeignPtr'. It is
87 -- the caller's responsibility to ensure that the 'ForeignPtr' points to
88 -- an area of memory sufficient for the specified bounds.
89 unsafeForeignPtrToStorableArray
90 :: ForeignPtr e -> (i,i) -> IO (StorableArray i e)
91 unsafeForeignPtrToStorableArray p (l,u) =
92 return (StorableArray l u p)