-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Regional memory pointers
--   
--   The library allows you to allocate memory in a region yielding a
--   regional pointer to it. When the region terminates all pointers are
--   automatically freed. Most importantly, a pointer can't be returned
--   from the region. So it's impossible to reference unallocated memory.
--   
--   The primary technique used in this package is called "Lightweight
--   monadic regions" which was invented by Oleg Kiselyov and Chung-chieh
--   Shan. See:
--   
--   <a>http://okmij.org/ftp/Haskell/regions.html#light-weight</a>
--   
--   This technique is implemented in the <tt>regions</tt> package which is
--   re-exported from this library.
--   
--   This library provides wrappers around all the <tt>Ptr</tt> functions
--   from the <tt>Foreign.*</tt> modules from <tt>base</tt>.
@package regional-pointers
@version 0.1


-- | <i>Unsafe</i> functions for retrieving the actual Ptr from a regional
--   pointer and for lifting operations on Ptrs to RegionalPtrs.
module Foreign.Ptr.Region.Unsafe
unsafePtr :: RegionalPtr α r -> Ptr α
unsafeWrap :: (MonadIO m) => (Ptr α -> IO β) -> (RegionalPtr α r -> m β)
unsafeWrap2 :: (MonadIO m) => (Ptr α -> γ -> IO β) -> (RegionalPtr α r -> γ -> m β)
unsafeWrap3 :: (MonadIO m) => (Ptr α -> γ -> δ -> IO β) -> (RegionalPtr α r -> γ -> δ -> m β)


module Foreign.Ptr.Region

-- | Represents memory of <a>size</a> number of bytes which may be
--   marshalled to or from Haskell values of type <tt>α</tt>. Before you
--   can use the memory you have to allocate it using <a>open</a>.
newtype Memory α
Memory :: Int -> Memory α
size :: Memory α -> Int

-- | Handy type synonym for a regional handle to memory. This should
--   provide a safer replacement for <tt>Foreign.Ptr.</tt><a>Ptr</a>
type RegionalPtr α r = RegionalHandle (Memory α) r
mapRegionalPtr :: (Ptr α -> Ptr β) -> (RegionalPtr α r -> RegionalPtr β r)

-- | Wraps: <tt>Foreign.Ptr.</tt><a>castPtr</a>
castPtr :: RegionalPtr α r -> RegionalPtr β r

-- | Wraps: <tt>Foreign.Ptr.</tt><a>plusPtr</a>
plusPtr :: RegionalPtr α r -> Int -> RegionalPtr β r

-- | Wraps: <tt>Foreign.Ptr.</tt><a>alignPtr</a>
alignPtr :: RegionalPtr α r -> Int -> RegionalPtr α r

-- | Wraps: <tt>Foreign.Ptr.</tt><a>minusPtr</a>
minusPtr :: RegionalPtr α r -> RegionalPtr β r -> Int


module Foreign.Marshal.Alloc.Region

-- | Convenience function which allocates sufficient memory to hold values
--   of type <tt>α</tt>, applies the given continuation function to the
--   resulting regional pointer and runs the resulting region.
--   
--   This should provide a safer replacement for:
--   <tt>Foreign.Marshal.Alloc.<a>alloca</a></tt>.
--   
--   Note that: <tt>alloca = <a>allocaBytes</a> $ <a>sizeOf</a> (undefined
--   :: α)</tt>
alloca :: (Storable α, MonadCatchIO pr) => (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β

-- | Convenience function which allocates the given number of bytes,
--   applies the given continuation function to the resulting regional
--   pointer and runs the resulting region.
--   
--   This should provide a safer replacement for:
--   <tt>Foreign.Marshal.Alloc.<a>allocaBytes</a></tt>.
--   
--   Note that: <tt>allocaBytes = <a>with</a> . <a>Memory</a></tt>
allocaBytes :: (MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β

-- | Convenience function which allocates sufficient memory to hold values
--   of type <tt>α</tt> and returns a regional pointer to them.
--   
--   This should provide a safer replacement for:
--   <tt>Foreign.Marshal.Alloc.<a>malloc</a></tt>.
--   
--   Note that: <tt>malloc = <a>mallocBytes</a> $ <a>sizeOf</a> (undefined
--   :: α)</tt>
malloc :: (Storable α, MonadCatchIO pr) => RegionT s pr (RegionalPtr α (RegionT s pr))

-- | Convenience function which allocates the given number of bytes and
--   returns a regional pointer to them.
--   
--   This should provide a safer replacement for:
--   <tt>Foreign.Marshal.Alloc.<a>mallocBytes</a></tt>.
--   
--   Note that: <tt>mallocBytes = <a>open</a> . <a>Memory</a></tt>
mallocBytes :: (MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr))


module Foreign.Marshal.Array.Region
mallocArray :: (Storable α, MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr))
mallocArray0 :: (Storable α, MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr))
allocaArray :: (Storable α, MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β
allocaArray0 :: (Storable α, MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>peekArray</a>.
peekArray :: (Storable α, ParentOf pr cr, MonadIO cr) => Int -> RegionalPtr α pr -> cr [α]

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>peekArray0</a>.
peekArray0 :: (Storable α, Eq α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> cr [α]

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>pokeArray</a>.
pokeArray :: (Storable α, ParentOf pr cr, MonadIO cr) => RegionalPtr α pr -> [α] -> cr ()

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>pokeArray0</a>.
pokeArray0 :: (Storable α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> [α] -> cr ()
newArray :: (Storable α, MonadCatchIO pr) => [α] -> RegionT s pr (RegionalPtr α (RegionT s pr))
newArray0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> RegionT s pr (RegionalPtr α (RegionT s pr))
withArray :: (Storable α, MonadCatchIO pr) => [α] -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β
withArray0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β
withArrayLen :: (Storable α, MonadCatchIO pr) => [α] -> (forall s. Int -> RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β
withArrayLen0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> (forall s. Int -> RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>copyArray</a>.
copyArray :: (Storable α, ParentOf pr cr, MonadIO cr) => RegionalPtr α pr -> RegionalPtr α pr -> Int -> cr ()

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>moveArray</a>.
moveArray :: (Storable α, ParentOf pr cr, MonadIO cr) => RegionalPtr α pr -> RegionalPtr α pr -> Int -> cr ()

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>lengthArray0</a>.
lengthArray0 :: (Storable α, Eq α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> cr Int

-- | Wraps: <tt>Foreign.Marshal.Array.</tt><a>advancePtr</a>.
advancePtr :: (Storable α) => RegionalPtr α pr -> Int -> RegionalPtr α pr


-- | Lifts methods of the <a>Storable</a> type class from
--   <tt>Foreign.Storable</tt> to regional pointers.
module Foreign.Storable.Region

-- | Wraps: <tt>Foreign.Storable.<a>peekElemOff</a></tt>.
peekElemOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> Int -> cr α

-- | Wraps: <tt>Foreign.Storable.<a>pokeElemOff</a></tt>.
pokeElemOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> Int -> α -> cr ()

-- | Wraps: <tt>Foreign.Storable.<a>peekByteOff</a></tt>.
peekByteOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr β pr -> Int -> cr α

-- | Wraps: <tt>Foreign.Storable.<a>pokeByteOff</a></tt>.
pokeByteOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr β pr -> Int -> α -> cr ()

-- | Wraps: <tt>Foreign.Storable.<a>peek</a></tt>.
peek :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> cr α

-- | Wraps: <tt>Foreign.Storable.<a>poke</a></tt>.
poke :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> α -> cr ()


module Foreign.Marshal.Utils.Region
with :: (Storable α, MonadCatchIO pr) => α -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β
new :: (Storable α, MonadCatchIO pr) => α -> RegionT s pr (RegionalPtr α (RegionT s pr))

-- | Convert a Haskell <a>Bool</a> to its numeric representation
fromBool :: (Num a) => Bool -> a

-- | Convert a Boolean in numeric representation to a Haskell value
toBool :: (Num a) => a -> Bool
copyBytes :: (ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr2 -> Int -> cr ()
moveBytes :: (ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr2 -> Int -> cr ()


-- | Lifts functions and types from <tt>Foreign.C.String</tt> to regional
--   pointers.
module Foreign.C.String.Region

-- | Handy type synonym for a regional pointer to an array of C characters
--   terminated by a NUL.
--   
--   This should provide a safer replacement for
--   <tt>Foreign.C.String.<a>CString</a></tt>.
type RegionalCString r = RegionalPtr CChar r

-- | Handy type synonym for a regional pointer to an array of C characters
--   which is paired with the length of the array instead of terminated by
--   a NUL. (Thus allowing NUL characters in the middle of the string)
--   
--   This should provide a safer replacement for
--   <tt>Foreign.C.String.<a>CStringLen</a></tt>.
type RegionalCStringLen r = (RegionalPtr CChar r, Int)
peekCString :: (ParentOf pr cr, MonadIO cr) => RegionalCString pr -> cr String
peekCStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCStringLen pr -> cr String
newCString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCString (RegionT s pr))
newCStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCStringLen (RegionT s pr))
withCString :: (MonadCatchIO pr) => String -> (forall s. RegionalCString (RegionT s pr) -> RegionT s pr α) -> pr α
withCStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCStringLen (RegionT s pr) -> RegionT s pr α) -> pr α
charIsRepresentable :: (MonadIO m) => Char -> m Bool

-- | Convert a Haskell character to a C character. This function is only
--   safe on the first 256 characters.
castCharToCChar :: Char -> CChar

-- | Convert a C byte, representing a Latin-1 character, to the
--   corresponding Haskell character.
castCCharToChar :: CChar -> Char
peekCAString :: (ParentOf pr cr, MonadIO cr) => RegionalCString pr -> cr String
peekCAStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCStringLen pr -> cr String
newCAString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCString (RegionT s pr))
newCAStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCStringLen (RegionT s pr))
withCAString :: (MonadCatchIO pr) => String -> (forall s. RegionalCString (RegionT s pr) -> RegionT s pr α) -> pr α
withCAStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCStringLen (RegionT s pr) -> RegionT s pr α) -> pr α

-- | Handy type synonym for a regional pointer to an array of C wide
--   characters terminated by a NUL.
--   
--   This should provide a safer replacement for
--   <tt>Foreign.C.String.<a>CWString</a></tt>.
type RegionalCWString r = RegionalPtr CWchar r

-- | Handy type synonym for a regional pointer to an array of C wide
--   characters which is paired with the length of the array instead of
--   terminated by a NUL. (Thus allowing NUL characters in the middle of
--   the string)
--   
--   This should provide a safer replacement for
--   <tt>Foreign.C.String.<a>CWStringLen</a></tt>.
type RegionalCWStringLen r = (RegionalPtr CWchar r, Int)
peekCWString :: (ParentOf pr cr, MonadIO cr) => RegionalCWString pr -> cr String
peekCWStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCWStringLen pr -> cr String
newCWString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCWString (RegionT s pr))
newCWStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCWStringLen (RegionT s pr))
withCWString :: (MonadCatchIO pr) => String -> (forall s. RegionalCWString (RegionT s pr) -> RegionT s pr α) -> pr α
withCWStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCWStringLen (RegionT s pr) -> RegionT s pr α) -> pr α