-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | using the `Prim` interface for the FFI -- -- This library provides an alternative to the Storable interface, -- using the Prim typeclass. The goal is to make it possible to -- avoid the duplicated code between Storable and Prim APIs -- when one is working mostly with the primitive or -- contiguous APIs. @package primitive-foreign @version 0.1 module Data.Primitive.Foreign -- | Size of values of type a. The argument is not used. -- -- This function has existed since 0.1, but was moved from -- Primitive to Types in version 0.6.3.0 sizeOf :: Prim a => a -> Int -- | Alignment of values of type a. The argument is not used. -- -- This function has existed since 0.1, but was moved from -- Primitive to Types in version 0.6.3.0 alignment :: Prim a => a -> Int -- | Read a value from the given memory location. -- -- Note that the peek and poke functions might require properly aligned -- addresses to function correctly. This is architecture dependent; thus, -- portable code should ensure that when peeking or poking values of some -- type a, the alignment constraint for a, as given by -- the function alignment is fulfilled. peek :: forall a. Prim a => Ptr a -> IO a -- | Read a value from a memory area regarded as an array of values of the -- same kind. The first argument specifies the start address of the array -- and the second the index into the array (the first element of the -- array has index 0). The following equality holds, -- -- 
--   peekElemOff addr idx = fixIO $ \result ->
--     peek (addr `plusPtr` (idx * sizeOf result))
--
-- -- Note that this is only a specification, not necessarily the concrete -- implementation of the function. peekElemOff :: forall a. Prim a => Ptr a -> Int -> IO a -- | Read a value from a memory location given by a base address and -- offset. The following equality holds: -- -- 
--   peekByteOff addr off = peek (addr `plusPtr` off)
--
peekByteOff :: forall a. Prim a => Ptr Void -> Int -> IO a -- | Write the given value to the given memory location. Alignment -- restrictions might apply; see peek. poke :: forall a. Prim a => Ptr a -> a -> IO () -- | Write a value to a memory area regarded as an array of values of the -- same kind. The following equality holds: -- -- 
--   pokeElemOff addr idx x =
--     poke (addr `plusPtr` (idx * sizeOf x)) x
--
pokeElemOff :: forall a. Prim a => Ptr a -> Int -> a -> IO () -- | Write a value to a memory location given by a base address and offset. -- The following equality holds: -- -- 
--   pokeByteOff addr off x = poke (addr `plusPtr` off) x
--
pokeByteOff :: forall a. Prim a => Ptr Void -> Int -> a -> IO () -- | alloca f executes the computation f, passing -- as argument a pointer to a temporarily allocated block of memory -- sufficient to hold values of type a. -- -- The memory is freed when f terminates (either normally or via -- an exception), so the pointer passed to f must not be -- used after this. alloca :: forall a b. Prim a => (Ptr a -> IO b) -> IO b -- | allocaBytes n f executes the computation f, -- passing as argument a pointer to a temporarily allocated block of -- memory of n bytes. The block of memory is sufficiently -- aligned for any of the basic foreign types that fits into a memory -- block of the allocated size. -- -- The memory is freed when f terminates (either normally or via -- an exception), so the pointer passed to f must not be -- used after this. allocaBytes :: () => Int -> (Ptr a -> IO b) -> IO b allocaBytesAligned :: () => Int -> Int -> (Ptr a -> IO b) -> IO b malloc :: forall a. Prim a => IO (Ptr a) -- | Allocate a block of memory of the given number of bytes. The block of -- memory is sufficiently aligned for any of the basic foreign types that -- fits into a memory block of the allocated size. -- -- The memory may be deallocated using free or -- finalizerFree when no longer required. mallocBytes :: () => Int -> IO (Ptr a) calloc :: forall a. Prim a => IO (Ptr a) -- | Llike mallocBytes but memory is filled with bytes of value -- zero. callocBytes :: () => Int -> IO (Ptr a) realloc :: forall a b. Prim b => Ptr a -> IO (Ptr b) -- | Resize a memory area that was allocated with malloc or -- mallocBytes to the given size. The returned pointer may refer -- to an entirely different memory area, but will be sufficiently aligned -- for any of the basic foreign types that fits into a memory block of -- the given size. The contents of the referenced memory area will be the -- same as of the original pointer up to the minimum of the original size -- and the given size. -- -- If the pointer argument to reallocBytes is nullPtr, -- reallocBytes behaves like malloc. If the requested size -- is 0, reallocBytes behaves like free. reallocBytes :: () => Ptr a -> Int -> IO (Ptr a) -- | Free a block of memory that was allocated with malloc, -- mallocBytes, realloc, reallocBytes, new or -- any of the newX functions in -- Foreign.Marshal.Array or Foreign.C.String. free :: () => Ptr a -> IO () -- | A pointer to a foreign function equivalent to free, which may -- be used as a finalizer (cf ForeignPtr) for storage allocated -- with malloc, mallocBytes, realloc or -- reallocBytes. finalizerFree :: () => FinalizerPtr a -- | Allocate storage for the given number of elements of a storable type -- (like malloc, but for multiple elements). mallocArray :: forall a. Prim a => Int -> IO (Ptr a) -- | Like mallocArray, but add an extra position to hold a special -- termination element. mallocArray0 :: forall a. Prim a => Int -> IO (Ptr a) -- | Temporarily allocate space for the given number of elements (like -- alloca, but for multiple elements). allocaArray :: forall a b. Prim a => Int -> (Ptr a -> IO b) -> IO b -- | Like allocaArray, but add an extra position to hold a special -- termination element. allocaArray0 :: forall a b. Prim a => Int -> (Ptr a -> IO b) -> IO b -- | Adjust the size of an array. reallocArray :: forall a. Prim a => Ptr a -> Int -> IO (Ptr a) -- | Adjust the size of an array, including an extra position for the -- terminating element. reallocArray0 :: forall a. Prim a => Ptr a -> Int -> IO (Ptr a) -- | Like mallocArray, but allocated memory is filled with bytes of -- value zero. callocArray :: forall a. Prim a => Int -> IO (Ptr a) -- | Like mallocArray0, but allocated memory is filled with bytes of -- value zero. callocArray0 :: forall a. Prim a => Int -> IO (Ptr a) -- | Convert an array of given length into a Haskell PrimArray. peekArray :: forall a. Prim a => Int -> Ptr a -> IO (PrimArray a) -- | Convert an array terminated by the given terminator into a Haskell -- PrimArray. peekArray0 :: forall a. (Prim a, Eq a) => a -> Ptr a -> IO (PrimArray a) -- | Write the PrimArray into memory at the given location. pokeArray :: forall a. Prim a => Ptr a -> PrimArray a -> IO () -- | Write the PrimArray into memory and terminate the elements with -- a given terminating element. pokeArray0 :: forall a. Prim a => a -> Ptr a -> PrimArray a -> IO () -- | Write a PrimArray into a newly allocated, consecutive sequence -- of primitive values. newArray :: forall a. Prim a => PrimArray a -> IO (Ptr a) -- | Write a PrimArray into a newly allocated, consecutive sequence -- of primitive values, where the end is fixed by the given terminating -- element. newArray0 :: forall a. Prim a => a -> PrimArray a -> IO (Ptr a) -- | Temporarily store a PrimArray in memory. withArray :: forall a b. Prim a => PrimArray a -> (Ptr a -> IO b) -> IO b -- | Like withArray, but a terminator indicates where the array -- ends. withArray0 :: forall a b. Prim a => a -> PrimArray a -> (Ptr a -> IO b) -> IO b -- | Like withArray, but the action is also passed the size of the -- PrimArray. withArrayLen :: forall a b. Prim a => PrimArray a -> (Int -> Ptr a -> IO b) -> IO b -- | Like withArrayLen, but a terminator indicates where the array -- ends. withArrayLen0 :: forall a b. Prim a => a -> PrimArray a -> (Int -> Ptr a -> IO b) -> IO b -- | Copy the given number of elements from the source array into the -- destination array; the memory regions may not overlap. copyArray :: forall a. Prim a => Ptr a -> Ptr a -> Int -> IO () -- | Copy the given number of elements from the source array into the -- destination array; the memory regions may overlap. moveArray :: forall a. Prim a => Ptr a -> Ptr a -> Int -> IO () -- | Return the number of elements in an array, excluding the terminator lengthArray0 :: forall a. (Prim a, Eq a) => a -> Ptr a -> IO Int -- | Advance a pointer into an array by the given number of elements. advancePtr :: forall a. Prim a => Ptr a -> Int -> Ptr a with :: forall a b. Prim a => a -> (Ptr a -> IO b) -> IO b new :: forall a. Prim a => a -> IO (Ptr a) -- | Allocate storage and marshal a storable value wrapped into a -- Maybe -- -- maybeNew :: () => (a -> IO (Ptr b)) -> Maybe a -> IO (Ptr b) -- | Converts a withXXX combinator into one marshalling a value -- wrapped into a Maybe, using nullPtr to represent -- Nothing. maybeWith :: () => (a -> (Ptr b -> IO c) -> IO c) -> Maybe a -> (Ptr b -> IO c) -> IO c -- | Convert a peek combinator into a one returning Nothing if -- applied to a nullPtr maybePeek :: () => (Ptr a -> IO b) -> Ptr a -> IO (Maybe b) -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may not overlap copyBytes :: () => Ptr a -> Ptr a -> Int -> IO () -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may overlap moveBytes :: () => Ptr a -> Ptr a -> Int -> IO () -- | Fill a given number of bytes in memory area with a byte value. fillBytes :: () => Ptr a -> Word8 -> Int -> IO ()