Foreign.Marshal.Array

haskell2010-1.1.1.0: Compatibility with Haskell 2010

Safe Haskell | Safe

Foreign.Marshal.Array

Contents

- Marshalling arrays
  - Allocation
  - Marshalling
  - Combined allocation and marshalling
  - Copying
  - Finding the length
  - Indexing

Description

The module Foreign.Marshal.Array provides operations for marshalling Haskell lists into monolithic arrays and vice versa. Most functions come in two flavours: one for arrays terminated by a special termination element and one where an explicit length parameter is used to determine the extent of an array. The typical example for the former case are C's NUL terminated strings. However, please note that C strings should usually be marshalled using the functions provided by Foreign.C.String as the Unicode encoding has to be taken into account. All functions specifically operating on arrays that are terminated by a special termination element have a name ending on `0`---e.g., `mallocArray` allocates space for an array of the given size, whereas `mallocArray0` allocates space for one more element to ensure that there is room for the terminator.

Synopsis

- mallocArray :: Storable a => Int -> IO (Ptr a)
- mallocArray0 :: Storable a => Int -> IO (Ptr a)
- allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b
- allocaArray0 :: Storable a => Int -> (Ptr a -> IO b) -> IO b
- reallocArray :: Storable a => Ptr a -> Int -> IO (Ptr a)
- reallocArray0 :: Storable a => Ptr 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 :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
- moveArray :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
- lengthArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO Int
- advancePtr :: Storable a => Ptr a -> Int -> Ptr a

# Marshalling arrays

## Allocation

mallocArray :: 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 :: Storable a => Int -> (Ptr a -> IO b) -> IO bSource

Temporarily allocate space for the given number of elements (like `alloca`, but for multiple elements).

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

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

reallocArray :: 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.

## Marshalling

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

Convert an array of given length into a Haskell list.

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 bSource

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 bSource

Like `withArray`, but a terminator indicates where the array ends

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

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 bSource

Like `withArrayLen`, but a terminator indicates where the array ends

## Copying

(argument order: destination, source)

copyArray :: 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 :: 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

## Indexing

advancePtr :: Storable a => Ptr a -> Int -> Ptr aSource

Advance a pointer into an array by the given number of elements