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


-- | Types for offsets into unboxed arrays
--   
--   Types for offsets into unboxed arrays
@package primitive-offset
@version 0.1.0.0

module Data.Primitive.ByteArray.Offset

-- | A byte array and an index into the array. The element type is
--   understood to be byte (an 8-bit word).
data ByteArrayOffset
ByteArrayOffset :: {-# UNPACK #-} !ByteArray -> {-# UNPACK #-} !Int -> ByteArrayOffset
[$sel:array:ByteArrayOffset] :: ByteArrayOffset -> {-# UNPACK #-} !ByteArray
[$sel:index:ByteArrayOffset] :: ByteArrayOffset -> {-# UNPACK #-} !Int

-- | A mutable byte array and an index into the array. The element type is
--   understood to be byte (an 8-bit word).
data MutableByteArrayOffset s
MutableByteArrayOffset :: {-# UNPACK #-} !MutableByteArray s -> {-# UNPACK #-} !Int -> MutableByteArrayOffset s
[$sel:array:MutableByteArrayOffset] :: MutableByteArrayOffset s -> {-# UNPACK #-} !MutableByteArray s
[$sel:index:MutableByteArrayOffset] :: MutableByteArrayOffset s -> {-# UNPACK #-} !Int


-- | Data types for describing an array paired with an index into it. This
--   is intended to be used in wrappers for <tt>unsafe</tt> FFI calls. For
--   example, the POSIX function <tt>recvfrom</tt> takes a
--   <tt>socklen_t*</tt> argument. (Let us assume that <tt>socklen_t</tt>
--   is equivalant to <tt>int</tt> for this example.) How is this argument
--   best described by a Haskell type? When working with pinned memory, the
--   best option <tt><tt>Ptr</tt> <tt>CInt</tt></tt>. It works equally well
--   regardless of whether we originally had an array of <tt>CInt</tt> or a
--   pointer to a single <tt>CInt</tt>. This works because of functions
--   like <a>advancePtr</a> and <a>plusPtr</a> that effectively index into
--   an array. Unpinned memory, however, is trickier. We want to have the
--   full flexibility (handling both a single-element or multi-element
--   buffer) that <tt><tt>Ptr</tt> <tt>CInt</tt></tt> affords. We cannot
--   offset into a <a>MutablePrimArray</a> to get a new one like we could
--   with <tt>Ptr</tt>. (Such a function is not possible because unpinned
--   memory can be relocated.) So, the offseting must be done in the C
--   function wrapped by the <tt>unsafe</tt> FFI. This means that the
--   offset must be passed together with the <a>MutablePrimArray</a>. This
--   is the precisely the product that <a>MutablePrimArrayOffset</a>
--   represents. In a type signature, it provides additional clarity about
--   the meaning of the offset.
--   
--   This library is used in the extensively in the <tt>posix-api</tt>
--   library to clarify intent in a number of type signatures.
module Data.Primitive.PrimArray.Offset

-- | A primitive array and an index into the array.
data PrimArrayOffset a
PrimArrayOffset :: {-# UNPACK #-} !PrimArray a -> {-# UNPACK #-} !Int -> PrimArrayOffset a
[$sel:array:PrimArrayOffset] :: PrimArrayOffset a -> {-# UNPACK #-} !PrimArray a
[$sel:index:PrimArrayOffset] :: PrimArrayOffset a -> {-# UNPACK #-} !Int

-- | A mutable primitive array and an index into the array.
data MutablePrimArrayOffset s a
MutablePrimArrayOffset :: {-# UNPACK #-} !MutablePrimArray s a -> {-# UNPACK #-} !Int -> MutablePrimArrayOffset s a
[$sel:array:MutablePrimArrayOffset] :: MutablePrimArrayOffset s a -> {-# UNPACK #-} !MutablePrimArray s a
[$sel:index:MutablePrimArrayOffset] :: MutablePrimArrayOffset s a -> {-# UNPACK #-} !Int

-- | Recover the element in the primitive array.
indexOffset :: Prim a => PrimArrayOffset a -> a

-- | Recover the element in the mutable primitive array.
readOffset :: (PrimMonad m, Prim a) => MutablePrimArrayOffset (PrimState m) a -> m a