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


-- | Wrappers for primitive operations
--   
--   This package provides wrappers for primitive array operations from
--   GHC.Prim.
--   
--   Changes in version 0.4
--   
--   <ul>
--   <li>Support for GHC 7.2 array copying primitives</li>
--   <li>New in <a>Data.Primitive.ByteArray</a>: <tt>copyByteArray</tt>,
--   <tt>copyMutableByteArray</tt>, <tt>moveByteArray</tt>,
--   <tt>fillByteArray</tt></li>
--   <li>Deprecated in <a>Data.Primitive.ByteArray</a>:
--   <tt>memcpyByteArray</tt>, <tt>memcpyByteArray'</tt>,
--   <tt>memmoveByteArray</tt>, <tt>memsetByteArray</tt></li>
--   <li>New in <a>Data.Primitive.Array</a>: <tt>copyArray</tt>,
--   <tt>copyMutableByteArray</tt></li>
--   <li>New in <a>Data.Primitive.Addr</a>: <tt>copyAddr</tt>,
--   <tt>moveAddr</tt></li>
--   <li>Deprecated in <a>Data.Primitive.Addr</a>: <tt>memcpyAddr</tt></li>
--   </ul>
@package primitive
@version 0.4


-- | Machine-dependent constants
module Data.Primitive.MachDeps
sIZEOF_CHAR, aLIGNMENT_WORD64, sIZEOF_WORD64, aLIGNMENT_INT64, sIZEOF_INT64, aLIGNMENT_WORD32, sIZEOF_WORD32, aLIGNMENT_INT32, sIZEOF_INT32, aLIGNMENT_WORD16, sIZEOF_WORD16, aLIGNMENT_INT16, sIZEOF_INT16, aLIGNMENT_WORD8, sIZEOF_WORD8, aLIGNMENT_INT8, sIZEOF_INT8, aLIGNMENT_STABLEPTR, sIZEOF_STABLEPTR, aLIGNMENT_FUNPTR, sIZEOF_FUNPTR, aLIGNMENT_PTR, sIZEOF_PTR, aLIGNMENT_FLOAT, sIZEOF_FLOAT, aLIGNMENT_DOUBLE, sIZEOF_DOUBLE, aLIGNMENT_WORD, sIZEOF_WORD, aLIGNMENT_INT, sIZEOF_INT, aLIGNMENT_CHAR :: Int


-- | Primitive state-transformer monads
module Control.Monad.Primitive

-- | Class of primitive state-transformer monads
class Monad m => PrimMonad m where { type family PrimState m; }
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
internal :: PrimMonad m => m a -> State# (PrimState m) -> (# State# (PrimState m), a #)

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld :: *

-- | Execute a primitive operation with no result
primitive_ :: PrimMonad m => (State# (PrimState m) -> State# (PrimState m)) -> m ()

-- | Convert a <a>PrimMonad</a> to another monad with the same state token.
primToPrim :: (PrimMonad m1, PrimMonad m2, (PrimState m1) ~ (PrimState m2)) => m1 a -> m2 a

-- | Convert a <a>PrimMonad</a> with a <a>RealWorld</a> state token to
--   <a>IO</a>
primToIO :: (PrimMonad m, (PrimState m) ~ RealWorld) => m a -> IO a

-- | Convert a <a>PrimMonad</a> to <a>ST</a>
primToST :: PrimMonad m => m a -> ST (PrimState m) a

-- | Convert a <a>PrimMonad</a> to another monad with a possibly different
--   state token. This operation is highly unsafe!
unsafePrimToPrim :: (PrimMonad m1, PrimMonad m2) => m1 a -> m2 a

-- | Convert any <a>PrimMonad</a> to <a>IO</a>. This operation is highly
--   unsafe!
unsafePrimToIO :: PrimMonad m => m a -> IO a

-- | Convert any <a>PrimMonad</a> to <a>ST</a> with an arbitrary state
--   token. This operations is highly unsafe!
unsafePrimToST :: PrimMonad m => m a -> ST s a
unsafeInlinePrim :: PrimMonad m => m a -> a
unsafeInlineIO :: IO a -> a
unsafeInlineST :: ST s a -> a
touch :: PrimMonad m => a -> m ()
instance PrimMonad (ST s)
instance PrimMonad IO


-- | Basic types and classes for primitive array operations
module Data.Primitive.Types

-- | Class of types supporting primitive array operations
class Prim a
sizeOf# :: Prim a => a -> Int#
alignment# :: Prim a => a -> Int#
indexByteArray# :: Prim a => ByteArray# -> Int# -> a
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s
indexOffAddr# :: Prim a => Addr# -> Int# -> a
readOffAddr# :: Prim a => Addr# -> Int# -> State# s -> (# State# s, a #)
writeOffAddr# :: Prim a => Addr# -> Int# -> a -> State# s -> State# s

-- | A machine address
data Addr
Addr :: Addr# -> Addr
instance Typeable Addr
instance Prim Addr
instance Prim Char
instance Prim Double
instance Prim Float
instance Prim Int64
instance Prim Int32
instance Prim Int16
instance Prim Int8
instance Prim Int
instance Prim Word64
instance Prim Word32
instance Prim Word16
instance Prim Word8
instance Prim Word
instance Data Addr
instance Ord Addr
instance Eq Addr


-- | Primitive boxed arrays
module Data.Primitive.Array

-- | Boxed arrays
data Array a
Array :: (Array# a) -> Array a

-- | Mutable boxed arrays associated with a primitive state token.
data MutableArray s a
MutableArray :: (MutableArray# s a) -> MutableArray s a

-- | Create a new mutable array of the specified size and initialise all
--   elements with the given value.
newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)

-- | Read a value from the array at the given index.
readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m a

-- | Write a value to the array at the given index.
writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()

-- | Read a value from the immutable array at the given index.
indexArray :: Array a -> Int -> a

-- | Monadically read a value from the immutable array at the given index.
--   This allows us to be strict in the array while remaining lazy in the
--   read element which is very useful for collective operations. Suppose
--   we want to copy an array. We could do something like this:
--   
--   <pre>
--   copy marr arr ... = do ...
--                          writeArray marr i (indexArray arr i) ...
--                          ...
--   </pre>
--   
--   But since primitive arrays are lazy, the calls to <a>indexArray</a>
--   will not be evaluated. Rather, <tt>marr</tt> will be filled with
--   thunks each of which would retain a reference to <tt>arr</tt>. This is
--   definitely not what we want!
--   
--   With <a>indexArrayM</a>, we can instead write
--   
--   <pre>
--   copy marr arr ... = do ...
--                          x &lt;- indexArrayM arr i
--                          writeArray marr i x
--                          ...
--   </pre>
--   
--   Now, indexing is executed immediately although the returned element is
--   still not evaluated.
indexArrayM :: Monad m => Array a -> Int -> m a

-- | Convert a mutable array to an immutable one without copying. The array
--   should not be modified after the conversion.
unsafeFreezeArray :: PrimMonad m => MutableArray (PrimState m) a -> m (Array a)

-- | Convert an immutable array to an mutable one without copying. The
--   immutable array should not be used after the conversion.
unsafeThawArray :: PrimMonad m => Array a -> m (MutableArray (PrimState m) a)

-- | Check whether the two arrays refer to the same memory block.
sameMutableArray :: MutableArray s a -> MutableArray s a -> Bool

-- | Copy a slice of an immutable array to a mutable array.
copyArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Array a -> Int -> Int -> m ()

-- | Copy a slice of a mutable array to another array. The two arrays may
--   not be the same.
copyMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> MutableArray (PrimState m) a -> Int -> Int -> m ()
instance Typeable1 Array
instance Typeable2 MutableArray
instance (Typeable s, Typeable a) => Data (MutableArray s a)
instance Typeable a => Data (Array a)


-- | Primitive operations on ByteArrays
module Data.Primitive.ByteArray

-- | Byte arrays
data ByteArray
ByteArray :: ByteArray# -> ByteArray

-- | Mutable byte arrays associated with a primitive state token
data MutableByteArray s
MutableByteArray :: (MutableByteArray# s) -> MutableByteArray s
data ByteArray# :: #
data MutableByteArray# a :: * :: * -> #

-- | Create a new mutable byte array of the specified size.
newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size. The garbage
--   collector is guaranteed not to move it.
newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size and with the
--   give alignment. The garbage collector is guaranteed not to move it.
newAlignedPinnedByteArray :: PrimMonad m => Int -> Int -> m (MutableByteArray (PrimState m))

-- | Read a primitive value from the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes.
readByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> m a

-- | Write a primitive value to the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes.
writeByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Read a primitive value from the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes.
indexByteArray :: Prim a => ByteArray -> Int -> a

-- | Convert a mutable byte array to an immutable one without copying. The
--   array should not be modified after the conversion.
unsafeFreezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m ByteArray

-- | Convert an immutable byte array to a mutable one without copying. The
--   original array should not be used after the conversion.
unsafeThawByteArray :: PrimMonad m => ByteArray -> m (MutableByteArray (PrimState m))

-- | Size of the byte array.
sizeofByteArray :: ByteArray -> Int

-- | Size of the mutable byte array.
sizeofMutableByteArray :: MutableByteArray s -> Int

-- | Check if the two arrays refer to the same memory block.
sameMutableByteArray :: MutableByteArray s -> MutableByteArray s -> Bool

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <a>newPinnedByteArray</a> or
--   <a>newAlignedPinnedByteArray</a>.
byteArrayContents :: ByteArray -> Addr

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <a>newPinnedByteArray</a> or
--   <a>newAlignedPinnedByteArray</a>.
mutableByteArrayContents :: MutableByteArray s -> Addr

-- | Copy a slice of an immutable byte array to a mutable byte array.
copyByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> ByteArray -> Int -> Int -> m ()

-- | Copy a slice of a mutable byte array into another array. The two
--   slices may not overlap.
copyMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()

-- | Copy a slice of a mutable byte array into another, potentially
--   overlapping array.
moveByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()

-- | Fill a slice of a mutable byte array with a value.
fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> m ()
memcpyByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
memcpyByteArray' :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> ByteArray -> Int -> Int -> m ()
memmoveByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
memsetByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Word8 -> Int -> m ()
instance Typeable ByteArray
instance Typeable1 MutableByteArray
instance Typeable s => Data (MutableByteArray s)
instance Data ByteArray


-- | Primitive operations on machine addresses
module Data.Primitive.Addr

-- | A machine address
data Addr
Addr :: Addr# -> Addr

-- | The null address
nullAddr :: Addr

-- | Offset an address by the given number of bytes
plusAddr :: Addr -> Int -> Addr

-- | Distance in bytes between two addresses. The result is only valid if
--   the difference fits in an <a>Int</a>.
minusAddr :: Addr -> Addr -> Int

-- | The remainder of the address and the integer.
remAddr :: Addr -> Int -> Int

-- | Read a value from a memory position given by an address and an offset.
--   The memory block the address refers to must be immutable. The offset
--   is in elements of type <tt>a</tt> rather than in bytes.
indexOffAddr :: Prim a => Addr -> Int -> a

-- | Read a value from a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
readOffAddr :: (Prim a, PrimMonad m) => Addr -> Int -> m a

-- | Write a value to a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
writeOffAddr :: (Prim a, PrimMonad m) => Addr -> Int -> a -> m ()

-- | Copy the given number of bytes from the second <a>Addr</a> to the
--   first. The areas may not overlap.
copyAddr :: PrimMonad m => Addr -> Addr -> Int -> m ()

-- | Copy the given number of bytes from the second <a>Addr</a> to the
--   first. The areas may overlap.
moveAddr :: PrimMonad m => Addr -> Addr -> Int -> m ()
memcpyAddr :: PrimMonad m => Addr -> Addr -> Int -> m ()


-- | Reexports all primitive operations
module Data.Primitive

-- | Size of values of type <tt>a</tt>. The argument is not used.
sizeOf :: Prim a => a -> Int

-- | Alignment of values of type <tt>a</tt>. The argument is not used.
alignment :: Prim a => a -> Int