Copyright | (c) The FFI task force 2001 |
---|---|

License | BSD-style (see the file libraries/base/LICENSE) |

Maintainer | ffi@haskell.org |

Stability | provisional |

Portability | portable |

Safe Haskell | Trustworthy |

Language | Haskell2010 |

Marshalling support: routines allocating, storing, and retrieving Haskell lists that are represented as arrays in the foreign language

## Synopsis

- mallocArray :: forall a. Storable a => Int -> IO (Ptr a)
- mallocArray0 :: Storable a => Int -> IO (Ptr a)
- allocaArray :: forall a b. Storable a => Int -> (Ptr a -> IO b) -> IO b
- allocaArray0 :: Storable a => Int -> (Ptr a -> IO b) -> IO b
- reallocArray :: forall a. Storable a => Ptr a -> Int -> IO (Ptr a)
- reallocArray0 :: Storable a => Ptr a -> Int -> IO (Ptr a)
- callocArray :: forall a. Storable a => Int -> IO (Ptr a)
- callocArray0 :: Storable a => Int -> IO (Ptr a)
- peekArray :: Storable a => Int -> Ptr a -> IO [a]
- peekArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO [a]
- pokeArray :: Storable a => Ptr a -> [a] -> IO ()
- pokeArray0 :: Storable a => a -> Ptr a -> [a] -> IO ()
- newArray :: Storable a => [a] -> IO (Ptr a)
- newArray0 :: Storable a => a -> [a] -> IO (Ptr a)
- withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b
- withArray0 :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b
- withArrayLen :: Storable a => [a] -> (Int -> Ptr a -> IO b) -> IO b
- withArrayLen0 :: Storable a => a -> [a] -> (Int -> Ptr a -> IO b) -> IO b
- copyArray :: forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
- moveArray :: forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
- lengthArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO Int
- advancePtr :: forall a. Storable a => Ptr a -> Int -> Ptr a

# Marshalling arrays

## Allocation

mallocArray :: forall a. Storable a => Int -> IO (Ptr a) Source #

Allocate storage for the given number of elements of a storable type
(like `malloc`

, but for multiple elements).

mallocArray0 :: Storable a => Int -> IO (Ptr a) Source #

Like `mallocArray`

, but add an extra position to hold a special
termination element.

allocaArray :: forall a b. Storable a => Int -> (Ptr a -> IO b) -> IO b Source #

Temporarily allocate space for the given number of elements
(like `alloca`

, but for multiple elements).

allocaArray0 :: Storable a => Int -> (Ptr a -> IO b) -> IO b Source #

Like `allocaArray`

, but add an extra position to hold a special
termination element.

reallocArray :: forall a. Storable a => Ptr a -> Int -> IO (Ptr a) Source #

Adjust the size of an array

reallocArray0 :: Storable a => Ptr a -> Int -> IO (Ptr a) Source #

Adjust the size of an array including an extra position for the end marker.

callocArray :: forall a. Storable a => Int -> IO (Ptr a) Source #

Like `mallocArray`

, but allocated memory is filled with bytes of value zero.

callocArray0 :: Storable a => Int -> IO (Ptr a) Source #

Like `callocArray0`

, but allocated memory is filled with bytes of value
zero.

## Marshalling

peekArray :: Storable a => Int -> Ptr a -> IO [a] Source #

Convert an array of given length into a Haskell list. The implementation is tail-recursive and so uses constant stack space.

peekArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO [a] Source #

Convert an array terminated by the given end marker into a Haskell list

pokeArray :: Storable a => Ptr a -> [a] -> IO () Source #

Write the list elements consecutive into memory

pokeArray0 :: Storable a => a -> Ptr a -> [a] -> IO () Source #

Write the list elements consecutive into memory and terminate them with the given marker element

## Combined allocation and marshalling

newArray :: Storable a => [a] -> IO (Ptr a) Source #

Write a list of storable elements into a newly allocated, consecutive
sequence of storable values
(like `new`

, but for multiple elements).

newArray0 :: Storable a => a -> [a] -> IO (Ptr a) Source #

Write a list of storable elements into a newly allocated, consecutive sequence of storable values, where the end is fixed by the given end marker

withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b Source #

Temporarily store a list of storable values in memory
(like `with`

, but for multiple elements).

withArray0 :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b Source #

Like `withArray`

, but a terminator indicates where the array ends

withArrayLen :: Storable a => [a] -> (Int -> Ptr a -> IO b) -> IO b Source #

Like `withArray`

, but the action gets the number of values
as an additional parameter

withArrayLen0 :: Storable a => a -> [a] -> (Int -> Ptr a -> IO b) -> IO b Source #

Like `withArrayLen`

, but a terminator indicates where the array ends

## Copying

(argument order: destination, source)

copyArray :: forall a. Storable a => Ptr a -> Ptr a -> Int -> IO () Source #

Copy the given number of elements from the second array (source) into the
first array (destination); the copied areas may *not* overlap

moveArray :: forall a. Storable a => Ptr a -> Ptr a -> Int -> IO () Source #

Copy the given number of elements from the second array (source) into the
first array (destination); the copied areas *may* overlap

## Finding the length

lengthArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO Int Source #

Return the number of elements in an array, excluding the terminator