-- 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.
@package primitive
@version 0.2


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


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


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

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

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


-- | 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
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 ()
instance Ord Addr
instance Eq Addr


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