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


-- | Primitive memory-related operations
--   
--   This package provides various primitive memory-related operations.
@package primitive
@version 0.6.2.0


-- | Machine-dependent constants
module Data.Primitive.MachDeps
sIZEOF_CHAR :: Int
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
type Word64_# = Word#
type Int64_# = Int#


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

-- | Class of monads which can perform primitive state-transformer actions
class Monad m => PrimMonad m where type PrimState m where {
    type family PrimState m;
}

-- | Execute a primitive operation
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> 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 ()

-- | Class of primitive monads for state-transformer actions.
--   
--   Unlike <a>PrimMonad</a>, this typeclass requires that the
--   <tt>Monad</tt> be fully expressed as a state transformer, therefore
--   disallowing other monad transformers on top of the base <tt>IO</tt> or
--   <tt>ST</tt>.
class PrimMonad m => PrimBase m

-- | Expose the internal structure of the monad
internal :: PrimBase m => m a -> State# (PrimState m) -> (# State# (PrimState m), a #)

-- | Lifts a <a>PrimBase</a> into another <a>PrimMonad</a> with the same
--   underlying state token type.
liftPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a

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

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

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

-- | Convert an <a>IO</a> action to a <a>PrimMonad</a>.
ioToPrim :: (PrimMonad m, PrimState m ~ RealWorld) => IO a -> m a

-- | Convert an <a>ST</a> action to a <a>PrimMonad</a>.
stToPrim :: PrimMonad m => ST (PrimState m) a -> m a

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

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

-- | Convert any <a>PrimBase</a> to <a>ST</a> with an arbitrary state
--   token. This operation is highly unsafe!
unsafePrimToST :: PrimBase m => m a -> ST s a

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

-- | Convert an <a>ST</a> action with an arbitraty state token to any
--   <a>PrimMonad</a>. This operation is highly unsafe!
unsafeSTToPrim :: PrimMonad m => ST s a -> m a
unsafeInlinePrim :: PrimBase m => m a -> a
unsafeInlineIO :: IO a -> a
unsafeInlineST :: ST s a -> a
touch :: PrimMonad m => a -> m ()

-- | Create an action to force a value; generalizes <a>evaluate</a>
evalPrim :: forall a m. PrimMonad m => a -> m a
instance Control.Monad.Primitive.PrimMonad GHC.Types.IO
instance Control.Monad.Primitive.PrimBase GHC.Types.IO
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimBase m => Control.Monad.Primitive.PrimBase (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Maybe.MaybeT m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Primitive.PrimMonad (GHC.ST.ST s)
instance Control.Monad.Primitive.PrimBase (GHC.ST.ST s)


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

-- | Boxed arrays
data Array a
Array :: Array# a -> 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
[marray#] :: 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

-- | Create an immutable copy of a slice of an array.
--   
--   This operation makes a copy of the specified section, so it is safe to
--   continue using the mutable array afterward.
freezeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Int -> m (Array a)

-- | Create a mutable array from a slice of an immutable array.
--   
--   This operation makes a copy of the specified slice, so it is safe to
--   use the immutable array afterward.
thawArray :: PrimMonad m => Array a -> Int -> Int -> m (MutableArray (PrimState 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 ()

-- | Return a newly allocated Array with the specified subrange of the
--   provided Array. The provided Array should contain the full subrange
--   specified by the two Ints, but this is not checked.
cloneArray :: Array a -> Int -> Int -> Array a

-- | Return a newly allocated MutableArray. with the specified subrange of
--   the provided MutableArray. The provided MutableArray should contain
--   the full subrange specified by the two Ints, but this is not checked.
cloneMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Int -> m (MutableArray (PrimState m) a)
sizeofArray :: Array a -> Int
sizeofMutableArray :: MutableArray s a -> Int

-- | The <a>fromListN</a> function takes the input list's length as a hint.
--   Its behaviour should be equivalent to <a>fromList</a>. The hint can be
--   used to construct the structure <tt>l</tt> more efficiently compared
--   to <a>fromList</a>. If the given hint does not equal to the input
--   list's length the behaviour of <a>fromListN</a> is not specified.
fromListN :: IsList l => Int -> [Item l] -> l

-- | The <a>fromList</a> function constructs the structure <tt>l</tt> from
--   the given list of <tt>Item l</tt>
fromList :: IsList l => [Item l] -> l
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Primitive.Array.Array a)
instance GHC.Classes.Eq (Data.Primitive.Array.MutableArray s a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.Array.Array a)
instance Data.Foldable.Foldable Data.Primitive.Array.Array
instance Data.Traversable.Traversable Data.Primitive.Array.Array
instance GHC.Exts.IsList (Data.Primitive.Array.Array a)
instance GHC.Base.Functor Data.Primitive.Array.Array
instance GHC.Base.Applicative Data.Primitive.Array.Array
instance GHC.Base.Alternative Data.Primitive.Array.Array
instance GHC.Base.Monad Data.Primitive.Array.Array
instance GHC.Base.MonadPlus Data.Primitive.Array.Array
instance Control.Monad.Zip.MonadZip Data.Primitive.Array.Array
instance Control.Monad.Fix.MonadFix Data.Primitive.Array.Array
instance GHC.Base.Monoid (Data.Primitive.Array.Array a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Primitive.Array.Array a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Primitive.Array.Array a)
instance Data.Data.Data a => Data.Data.Data (Data.Primitive.Array.Array a)
instance (Data.Typeable.Internal.Typeable s, Data.Typeable.Internal.Typeable a) => Data.Data.Data (Data.Primitive.Array.MutableArray s a)


-- | Primitive boxed mutable variables
module Data.Primitive.MutVar

-- | A <a>MutVar</a> behaves like a single-element mutable array associated
--   with a primitive state token.
data MutVar s a
MutVar :: (MutVar# s a) -> MutVar s a

-- | Create a new <a>MutVar</a> with the specified initial value
newMutVar :: PrimMonad m => a -> m (MutVar (PrimState m) a)

-- | Read the value of a <a>MutVar</a>
readMutVar :: PrimMonad m => MutVar (PrimState m) a -> m a

-- | Write a new value into a <a>MutVar</a>
writeMutVar :: PrimMonad m => MutVar (PrimState m) a -> a -> m ()

-- | Atomically mutate the contents of a <a>MutVar</a>
atomicModifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b

-- | Strict version of <a>atomicModifyMutVar</a>. This forces both the
--   value stored in the <a>MutVar</a> as well as the value returned.
atomicModifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b

-- | Mutate the contents of a <a>MutVar</a>
modifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()

-- | Strict version of <a>modifyMutVar</a>
modifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
instance GHC.Classes.Eq (Data.Primitive.MutVar.MutVar s a)


-- | Small arrays are boxed (im)mutable arrays.
--   
--   The underlying structure of the <tt>Array</tt> type contains a card
--   table, allowing segments of the array to be marked as having been
--   mutated. This allows the garbage collector to only re-traverse
--   segments of the array that have been marked during certain phases,
--   rather than having to traverse the entire array.
--   
--   <a>SmallArray</a> lacks this table. This means that it takes up less
--   memory and has slightly faster writes. It is also more efficient
--   during garbage collection so long as the card table would have a
--   single entry covering the entire array. These advantages make them
--   suitable for use as arrays that are known to be small.
--   
--   The card size is 128, so for uses much larger than that,
--   <tt>Array</tt> would likely be superior.
--   
--   The underlying type, <a>SmallArray#</a>, was introduced in GHC 7.10,
--   so prior to that version, this module simply implements small arrays
--   as <tt>Array</tt>.
module Data.Primitive.SmallArray
data SmallArray a
SmallArray :: (SmallArray# a) -> SmallArray a
data SmallMutableArray s a
SmallMutableArray :: (SmallMutableArray# s a) -> SmallMutableArray s a

-- | Create a new small mutable array.
newSmallArray :: PrimMonad m => Int -> a -> m (SmallMutableArray (PrimState m) a)

-- | Read the element at a given index in a mutable array.
readSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> m a

-- | Write an element at the given idex in a mutable array.
writeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> a -> m ()

-- | Copy a slice of an immutable array into a mutable array.
copySmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallArray a -> Int -> Int -> m ()

-- | Copy a slice of one mutable array into another.
copySmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallMutableArray (PrimState m) a -> Int -> Int -> m ()

-- | Look up an element in an immutable array.
indexSmallArray :: SmallArray a -> Int -> a

-- | Look up an element in an immutable array.
--   
--   The purpose of returning a result using a monad is to allow the caller
--   to avoid retaining references to the array. Evaluating the return
--   value will cause the array lookup to be performed, even though it may
--   not require the element of the array to be evaluated (which could
--   throw an exception). For instance:
--   
--   <pre>
--   data Box a = Box a
--   ...
--   
--   f sa = case indexSmallArrayM sa 0 of
--     Box x -&gt; ...
--   </pre>
--   
--   <tt>x</tt> is not a closure that references <tt>sa</tt> as it would be
--   if we instead wrote:
--   
--   <pre>
--   let x = indexSmallArray sa 0
--   </pre>
--   
--   And does not prevent <tt>sa</tt> from being garbage collected.
--   
--   Note that <a>Identity</a> is not adequate for this use, as it is a
--   newtype, and cannot be evaluated without evaluating the element.
indexSmallArrayM :: Monad m => SmallArray a -> Int -> m a

-- | Create a copy of a slice of an immutable array.
cloneSmallArray :: SmallArray a -> Int -> Int -> SmallArray a

-- | Create a copy of a slice of a mutable array.
cloneSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> Int -> m (SmallMutableArray (PrimState m) a)

-- | Create an immutable array corresponding to a slice of a mutable array.
--   
--   This operation copies the portion of the array to be frozen.
freezeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> Int -> m (SmallArray a)

-- | Render a mutable array immutable.
--   
--   This operation performs no copying, so care must be taken not to
--   modify the input array after freezing.
unsafeFreezeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> m (SmallArray a)

-- | Create a mutable array corresponding to a slice of an immutable array.
--   
--   This operation copies the portion of the array to be thawed.
thawSmallArray :: PrimMonad m => SmallArray a -> Int -> Int -> m (SmallMutableArray (PrimState m) a)

-- | Render an immutable array mutable.
--   
--   This operation performs no copying, so care must be taken with its
--   use.
unsafeThawSmallArray :: PrimMonad m => SmallArray a -> m (SmallMutableArray (PrimState m) a)
sizeofSmallArray :: SmallArray a -> Int
sizeofSmallMutableArray :: SmallMutableArray s a -> Int
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Classes.Eq (Data.Primitive.SmallArray.SmallMutableArray s a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.SmallArray.SmallArray a)
instance Data.Foldable.Foldable Data.Primitive.SmallArray.SmallArray
instance Data.Traversable.Traversable Data.Primitive.SmallArray.SmallArray
instance GHC.Base.Functor Data.Primitive.SmallArray.SmallArray
instance GHC.Base.Applicative Data.Primitive.SmallArray.SmallArray
instance GHC.Base.Alternative Data.Primitive.SmallArray.SmallArray
instance GHC.Base.Monad Data.Primitive.SmallArray.SmallArray
instance GHC.Base.MonadPlus Data.Primitive.SmallArray.SmallArray
instance Control.Monad.Zip.MonadZip Data.Primitive.SmallArray.SmallArray
instance Control.Monad.Fix.MonadFix Data.Primitive.SmallArray.SmallArray
instance GHC.Base.Monoid (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Exts.IsList (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Primitive.SmallArray.SmallArray a)
instance Data.Data.Data a => Data.Data.Data (Data.Primitive.SmallArray.SmallArray a)
instance (Data.Typeable.Internal.Typeable s, Data.Typeable.Internal.Typeable a) => Data.Data.Data (Data.Primitive.SmallArray.SmallMutableArray s a)


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

-- | Class of types supporting primitive array operations
class Prim a

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

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

-- | Read a value from the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)

-- | Write a value to the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s

-- | Fill a slice of the mutable array with a value. The offset and length
--   of the chunk are in elements of type <tt>a</tt> rather than in bytes.
setByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s

-- | 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 => Addr# -> Int# -> State# s -> (# State# s, 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 => Addr# -> Int# -> a -> State# s -> State# s

-- | Fill a memory block given by an address, an offset and a length. The
--   offset and length are in elements of type <tt>a</tt> rather than in
--   bytes.
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s

-- | A machine address
data Addr
Addr :: Addr# -> Addr
instance GHC.Classes.Eq Data.Primitive.Types.Addr
instance GHC.Classes.Ord Data.Primitive.Types.Addr
instance Data.Data.Data Data.Primitive.Types.Addr
instance Data.Primitive.Types.Prim GHC.Types.Word
instance Data.Primitive.Types.Prim GHC.Word.Word8
instance Data.Primitive.Types.Prim GHC.Word.Word16
instance Data.Primitive.Types.Prim GHC.Word.Word32
instance Data.Primitive.Types.Prim GHC.Word.Word64
instance Data.Primitive.Types.Prim GHC.Types.Int
instance Data.Primitive.Types.Prim GHC.Int.Int8
instance Data.Primitive.Types.Prim GHC.Int.Int16
instance Data.Primitive.Types.Prim GHC.Int.Int32
instance Data.Primitive.Types.Prim GHC.Int.Int64
instance Data.Primitive.Types.Prim GHC.Types.Float
instance Data.Primitive.Types.Prim GHC.Types.Double
instance Data.Primitive.Types.Prim GHC.Types.Char
instance Data.Primitive.Types.Prim Data.Primitive.Types.Addr
instance Data.Primitive.Types.Prim (GHC.Ptr.Ptr a)
instance Data.Primitive.Types.Prim (GHC.Ptr.FunPtr a)


-- | 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
infixl 6 `plusAddr`

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

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

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

-- | Fill a memory block of with the given value. The length is in elements
--   of type <tt>a</tt> rather than in bytes.
setAddr :: (Prim a, PrimMonad m) => Addr -> Int -> a -> m ()


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

-- | 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. The offset and
--   length are given in elements of type <tt>a</tt> rather than in bytes.
setByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> Int -> a -> m ()

-- | Fill a slice of a mutable byte array with a byte.
fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> 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
instance Data.Data.Data Data.Primitive.ByteArray.ByteArray
instance Data.Typeable.Internal.Typeable s => Data.Data.Data (Data.Primitive.ByteArray.MutableByteArray s)


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


-- | GHC contains three general classes of value types:
--   
--   <ol>
--   <li>Unboxed types: values are machine values made up of fixed numbers
--   of bytes</li>
--   <li>Unlifted types: values are pointers, but strictly evaluated</li>
--   <li>Lifted types: values are pointers, lazily evaluated</li>
--   </ol>
--   
--   The first category can be stored in a <a>ByteArray</a>, and this
--   allows types in category 3 that are simple wrappers around category 1
--   types to be stored more efficiently using a <a>ByteArray</a>. This
--   module provides the same facility for category 2 types.
--   
--   GHC has two primitive types, <a>ArrayArray#</a> and
--   <a>MutableArrayArray#</a>. These are arrays of pointers, but of
--   category 2 values, so they are known to not be bottom. This allows
--   types that are wrappers around such types to be stored in an array
--   without an extra level of indirection.
--   
--   The way that the <a>ArrayArray#</a> API works is that one can read and
--   write <a>ArrayArray#</a> values to the positions. This works because
--   all category 2 types share a uniform representation, unlike unboxed
--   values which are represented by varying (by type) numbers of bytes.
--   However, using the this makes the internal API very unsafe to use, as
--   one has to coerce values to and from <a>ArrayArray#</a>.
--   
--   The API presented by this module is more type safe.
--   <a>UnliftedArray</a> and <a>MutableUnliftedArray</a> are parameterized
--   by the type of arrays they contain, and the coercions necessary are
--   abstracted into a class, <a>PrimUnlifted</a>, of things that are
--   eligible to be stored.
module Data.Primitive.UnliftedArray

-- | Immutable arrays that efficiently store types that are simple wrappers
--   around unlifted primitive types. The values of the unlifted type are
--   stored directly, eliminating a layer of indirection.
data UnliftedArray e
UnliftedArray :: ArrayArray# -> UnliftedArray e

-- | Mutable arrays that efficiently store types that are simple wrappers
--   around unlifted primitive types. The values of the unlifted type are
--   stored directly, eliminating a layer of indirection.
data MutableUnliftedArray s e
MutableUnliftedArray :: (MutableArrayArray# s) -> MutableUnliftedArray s e

-- | Classifies the types that are able to be stored in
--   <a>UnliftedArray</a> and <a>MutableUnliftedArray</a>. These should be
--   types that are just liftings of the unlifted pointer types, so that
--   their internal contents can be safely coerced into an
--   <a>ArrayArray#</a>.
class PrimUnlifted a
toArrayArray# :: PrimUnlifted a => a -> ArrayArray#
fromArrayArray# :: PrimUnlifted a => ArrayArray# -> a

-- | Creates a new <a>MutableUnliftedArray</a>. This function is unsafe,
--   because it allows access to the raw contents of the underlying
--   <a>ArrayArray#</a>.
unsafeNewUnliftedArray :: (PrimMonad m) => Int -> m (MutableUnliftedArray (PrimState m) a)

-- | Creates a new <a>MutableUnliftedArray</a> with the specified value as
--   initial contents. This is slower than <a>unsafeNewUnliftedArray</a>,
--   but safer.
newUnliftedArray :: (PrimMonad m, PrimUnlifted a) => Int -> a -> m (MutableUnliftedArray (PrimState m) a)

-- | Sets all the positions in an unlifted array to the designated value.
setUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> a -> m ()

-- | Yields the length of an <a>UnliftedArray</a>.
sizeofUnliftedArray :: UnliftedArray e -> Int

-- | Yields the length of a <a>MutableUnliftedArray</a>.
sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int

-- | Gets the value at the specified position of a
--   <a>MutableUnliftedArray</a>.
readUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> m a

-- | Sets the value at the specified position of a
--   <a>MutableUnliftedArray</a>.
writeUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> a -> m ()

-- | Gets the value at the specified position of an <a>UnliftedArray</a>.
indexUnliftedArray :: PrimUnlifted a => UnliftedArray a -> Int -> a

-- | Gets the value at the specified position of an <a>UnliftedArray</a>.
--   The purpose of the <a>Monad</a> is to allow for being eager in the
--   <a>UnliftedArray</a> value without having to introduce a data
--   dependency directly on the result value.
--   
--   It should be noted that this is not as much of a problem as with a
--   normal <a>Array</a>, because elements of an <a>UnliftedArray</a> are
--   guaranteed to not be exceptional. This function is provided in case it
--   is more desirable than being strict in the result value.
indexUnliftedArrayM :: (PrimUnlifted a, Monad m) => UnliftedArray a -> Int -> m a

-- | Freezes a <a>MutableUnliftedArray</a>, yielding an
--   <a>UnliftedArray</a>. This simply marks the array as frozen in place,
--   so it should only be used when no further modifications to the mutable
--   array will be performed.
unsafeFreezeUnliftedArray :: (PrimMonad m) => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a)

-- | Freezes a portion of a <a>MutableUnliftedArray</a>, yielding an
--   <a>UnliftedArray</a>. This operation is safe, in that it copies the
--   frozen portion, and the existing mutable array may still be used
--   afterward.
freezeUnliftedArray :: (PrimMonad m) => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (UnliftedArray a)

-- | Thaws a portion of an <a>UnliftedArray</a>, yielding a
--   <a>MutableUnliftedArray</a>. This copies the thawed portion, so
--   mutations will not affect the original array.
thawUnliftedArray :: (PrimMonad m) => UnliftedArray a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)

-- | Determines whether two <a>MutableUnliftedArray</a> values are the
--   same. This is object/pointer identity, not based on the contents.
sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool

-- | Copies the contents of an immutable array into a mutable array.
copyUnliftedArray :: (PrimMonad m) => MutableUnliftedArray (PrimState m) a -> Int -> UnliftedArray a -> Int -> Int -> m ()

-- | Copies the contents of one mutable array into another.
copyMutableUnliftedArray :: (PrimMonad m) => MutableUnliftedArray (PrimState m) a -> Int -> MutableUnliftedArray (PrimState m) a -> Int -> Int -> m ()

-- | Creates a copy of a portion of an <a>UnliftedArray</a>
cloneUnliftedArray :: UnliftedArray a -> Int -> Int -> UnliftedArray a

-- | Creates a new <a>MutableUnliftedArray</a> containing a copy of a
--   portion of another mutable array.
cloneMutableUnliftedArray :: (PrimMonad m) => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.UnliftedArray.UnliftedArray e)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.UnliftedArray.MutableUnliftedArray s e)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.Array.Array a)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.Array.MutableArray s a)
instance Data.Primitive.UnliftedArray.PrimUnlifted Data.Primitive.ByteArray.ByteArray
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.ByteArray.MutableByteArray s)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.SmallArray.SmallArray a)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.SmallArray.SmallMutableArray s a)
instance Data.Primitive.UnliftedArray.PrimUnlifted (Data.Primitive.MutVar.MutVar s a)
instance GHC.Classes.Eq (Data.Primitive.UnliftedArray.MutableUnliftedArray s a)
instance (GHC.Classes.Eq a, Data.Primitive.UnliftedArray.PrimUnlifted a) => GHC.Classes.Eq (Data.Primitive.UnliftedArray.UnliftedArray a)