-- 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.9.1.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_# = Word64#
type Int64_# = Int64#


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

-- | Class of monads which can perform primitive state-transformer actions.
class Monad m => PrimMonad (m :: Type -> Type) where {
    
    -- | State token type.
    type PrimState (m :: Type -> Type);
}

-- | Execute a primitive operation.
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a

-- | <a>RealWorld</a> 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 <a>RealWorld</a>; it's only used in the type system, to
--   parameterise <a>State#</a>.
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 :: Type -> Type)

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

-- | <a>PrimMonad</a>'s state token type can be annoying to handle in
--   constraints. This typeclass lets users (visually) notice
--   <a>PrimState</a> equality constraints less, by witnessing that <tt>s ~
--   <a>PrimState</a> m</tt>.
class (PrimMonad m, s ~ PrimState m) => MonadPrim s (m :: Type -> Type)

-- | <a>PrimBase</a>'s state token type can be annoying to handle in
--   constraints. This typeclass lets users (visually) notice
--   <a>PrimState</a> equality constraints less, by witnessing that <tt>s ~
--   <a>PrimState</a> m</tt>.
class (PrimBase m, MonadPrim s m) => MonadPrimBase s (m :: Type -> Type)

-- | 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 arbitrary state token to any
--   <a>PrimMonad</a>. This operation is highly unsafe!
unsafeSTToPrim :: PrimMonad m => ST s a -> m a

-- | See <a>unsafeInlineIO</a>. This function is not recommended for the
--   same reasons.
unsafeInlinePrim :: PrimBase m => m a -> a

-- | Generally, do not use this function. It is the same as
--   <tt>accursedUnutterablePerformIO</tt> from <tt>bytestring</tt> and is
--   well behaved under narrow conditions. See the documentation of that
--   function to get an idea of when this is sound. In most cases
--   <tt>GHC.IO.Unsafe.unsafeDupablePerformIO</tt> should be preferred.
unsafeInlineIO :: IO a -> a

-- | See <a>unsafeInlineIO</a>. This function is not recommended for the
--   same reasons. Prefer <tt>runST</tt> when <tt>s</tt> is free.
unsafeInlineST :: ST s a -> a

-- | Ensure that the value is considered alive by the garbage collection.
--   Warning: GHC has optimization passes that can erase <tt>touch</tt> if
--   it is certain that an exception is thrown afterward. Prefer
--   <a>keepAlive</a>.
touch :: PrimMonad m => a -> m ()

-- | Variant of <a>touch</a> that keeps a value of an unlifted type (e.g.
--   <tt>MutableByteArray#</tt>) alive.
touchUnlifted :: forall m (a :: UnliftedType). PrimMonad m => a -> m ()

-- | Keep value <tt>x</tt> alive until computation <tt>k</tt> completes.
--   Warning: This primop exists for completeness, but it is difficult to
--   use correctly. Prefer <a>keepAliveUnlifted</a> if the value to keep
--   alive is simply a wrapper around an unlifted type (e.g.
--   <tt>ByteArray</tt>).
keepAlive :: PrimBase m => a -> m r -> m r

-- | Variant of <a>keepAlive</a> in which the value kept alive is of an
--   unlifted boxed type.
keepAliveUnlifted :: forall m (a :: UnliftedType) r. PrimBase m => a -> m r -> m r

-- | Create an action to force a value; generalizes <a>evaluate</a>
evalPrim :: forall a m. PrimMonad m => a -> m a
unsafeInterleave :: PrimBase m => m a -> m a
unsafeDupableInterleave :: PrimBase m => m a -> m a
noDuplicate :: PrimMonad m => m ()
instance (Control.Monad.Primitive.PrimBase m, Control.Monad.Primitive.MonadPrim s m) => Control.Monad.Primitive.MonadPrimBase s m
instance (Control.Monad.Primitive.PrimMonad m, s GHC.Types.~ Control.Monad.Primitive.PrimState m) => Control.Monad.Primitive.MonadPrim s m
instance Control.Monad.Primitive.PrimBase GHC.Types.IO
instance Control.Monad.Primitive.PrimBase m => Control.Monad.Primitive.PrimBase (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimBase (GHC.Internal.Control.Monad.ST.Lazy.Imp.ST s)
instance Control.Monad.Primitive.PrimBase (GHC.Internal.ST.ST s)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Accum.AccumT w m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Cont.ContT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Primitive.PrimMonad GHC.Types.IO
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.CPS.RWST r w s m)
instance (GHC.Internal.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.Reader.ReaderT r m)
instance Control.Monad.Primitive.PrimMonad (GHC.Internal.Control.Monad.ST.Lazy.Imp.ST s)
instance Control.Monad.Primitive.PrimMonad (GHC.Internal.ST.ST s)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Select.SelectT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.CPS.WriterT w m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Lazy.WriterT w m)


-- | Primitive operations on <a>MVar</a>. This module provides a similar
--   interface to <a>Control.Concurrent.MVar</a>. However, the functions
--   are generalized to work in any <a>PrimMonad</a> instead of only
--   working in <a>IO</a>. Note that all of the functions here are
--   completely deterministic. Users of <a>MVar</a> are responsible for
--   designing abstractions that guarantee determinism in the presence of
--   multi-threading.
--   
--   For a more detailed explanation, see <a>Control.Concurrent.MVar</a>.
module Data.Primitive.MVar

-- | A synchronizing variable, used for communication between concurrent
--   threads. It can be thought of as a box, which may be empty or full.
data MVar s a
MVar :: MVar# s a -> MVar s a

-- | Create a new <a>MVar</a> that holds the supplied argument.
newMVar :: PrimMonad m => a -> m (MVar (PrimState m) a)

-- | Check whether a given <a>MVar</a> is empty.
--   
--   Notice that the boolean value returned is just a snapshot of the state
--   of the <a>MVar</a>. By the time you get to react on its result, the
--   <a>MVar</a> may have been filled (or emptied) - so be extremely
--   careful when using this operation. Use <a>tryTakeMVar</a> instead if
--   possible.
isEmptyMVar :: PrimMonad m => MVar (PrimState m) a -> m Bool

-- | Create a new <a>MVar</a> that is initially empty.
newEmptyMVar :: PrimMonad m => m (MVar (PrimState m) a)

-- | Put a value into an <a>MVar</a>. If the <a>MVar</a> is currently full,
--   <a>putMVar</a> will wait until it becomes empty.
--   
--   There are two further important properties of <a>putMVar</a>:
--   
--   <ul>
--   <li><a>putMVar</a> is single-wakeup. That is, if there are multiple
--   threads blocked in <a>putMVar</a>, and the <a>MVar</a> becomes empty,
--   only one thread will be woken up. The runtime guarantees that the
--   woken thread completes its <a>putMVar</a> operation.</li>
--   <li>When multiple threads are blocked on an <a>MVar</a>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using <a>MVar</a>s.</li>
--   </ul>
putMVar :: PrimMonad m => MVar (PrimState m) a -> a -> m ()

-- | Atomically read the contents of an <a>MVar</a>. If the <a>MVar</a> is
--   currently empty, <a>readMVar</a> will wait until it is full.
--   <a>readMVar</a> is guaranteed to receive the next <a>putMVar</a>.
--   
--   <i>Multiple Wakeup:</i> <a>readMVar</a> is multiple-wakeup, so when
--   multiple readers are blocked on an <a>MVar</a>, all of them are woken
--   up at the same time.
--   
--   <ul>
--   <li>It is single-wakeup instead of multiple-wakeup.</li>
--   <li>It might not receive the value from the next call to
--   <a>putMVar</a> if there is already a pending thread blocked on
--   <a>takeMVar</a>.</li>
--   <li>If another thread puts a value in the <a>MVar</a> in between the
--   calls to <a>takeMVar</a> and <a>putMVar</a>, that value may be
--   overridden.</li>
--   </ul>
readMVar :: PrimMonad m => MVar (PrimState m) a -> m a

-- | Return the contents of the <a>MVar</a>. If the <a>MVar</a> is
--   currently empty, <a>takeMVar</a> will wait until it is full. After a
--   <a>takeMVar</a>, the <a>MVar</a> is left empty.
--   
--   There are two further important properties of <a>takeMVar</a>:
--   
--   <ul>
--   <li><a>takeMVar</a> is single-wakeup. That is, if there are multiple
--   threads blocked in <a>takeMVar</a>, and the <a>MVar</a> becomes full,
--   only one thread will be woken up. The runtime guarantees that the
--   woken thread completes its <a>takeMVar</a> operation.</li>
--   <li>When multiple threads are blocked on an <a>MVar</a>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using <a>MVar</a>s.</li>
--   </ul>
takeMVar :: PrimMonad m => MVar (PrimState m) a -> m a

-- | A non-blocking version of <a>putMVar</a>. The <a>tryPutMVar</a>
--   function attempts to put the value <tt>a</tt> into the <a>MVar</a>,
--   returning <a>True</a> if it was successful, or <a>False</a> otherwise.
tryPutMVar :: PrimMonad m => MVar (PrimState m) a -> a -> m Bool

-- | A non-blocking version of <a>readMVar</a>. The <a>tryReadMVar</a>
--   function returns immediately, with <a>Nothing</a> if the <a>MVar</a>
--   was empty, or <tt><a>Just</a> a</tt> if the <a>MVar</a> was full with
--   contents <tt>a</tt>.
--   
--   <ul>
--   <li>It is single-wakeup instead of multiple-wakeup.</li>
--   <li>In the presence of other threads calling <a>putMVar</a>,
--   <a>tryReadMVar</a> may block.</li>
--   <li>If another thread puts a value in the <a>MVar</a> in between the
--   calls to <a>tryTakeMVar</a> and <a>putMVar</a>, that value may be
--   overridden.</li>
--   </ul>
tryReadMVar :: PrimMonad m => MVar (PrimState m) a -> m (Maybe a)

-- | A non-blocking version of <a>takeMVar</a>. The <a>tryTakeMVar</a>
--   function returns immediately, with <a>Nothing</a> if the <a>MVar</a>
--   was empty, or <tt><a>Just</a> a</tt> if the <a>MVar</a> was full with
--   contents <tt>a</tt>. After <a>tryTakeMVar</a>, the <a>MVar</a> is left
--   empty.
tryTakeMVar :: PrimMonad m => MVar (PrimState m) a -> m (Maybe a)
instance GHC.Classes.Eq (Data.Primitive.MVar.MVar s a)


-- | 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.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)

-- | Read a value from the array at the given index.
--   
--   <i>Note:</i> this function does not do bounds checking.
readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m a

-- | Write a value to the array at the given index.
--   
--   <i>Note:</i> this function does not do bounds checking.
writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()

-- | Read a value from the immutable array at the given index.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexArray :: Array a -> Int -> a

-- | Read a value from the immutable array at the given index using an
--   applicative. 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 the 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.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexArrayM :: Applicative m => Array a -> Int -> m a

-- | Read a value from the immutable array at the given index, returning
--   the result in an unboxed unary tuple. This is currently used to
--   implement folds.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexArray## :: Array a -> Int -> (# 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.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
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.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
thawArray :: PrimMonad m => Array a -> Int -> Int -> m (MutableArray (PrimState m) a)

-- | Execute the monadic action and freeze the resulting array.
--   
--   <pre>
--   runArray m = runST $ m &gt;&gt;= unsafeFreezeArray
--   </pre>
runArray :: (forall s. () => ST s (MutableArray s a)) -> Array a

-- | Create an array of the given size with a default value, apply the
--   monadic function and freeze the result. If the size is 0, return
--   <a>emptyArray</a> (rather than a new copy thereof).
--   
--   <pre>
--   createArray 0 _ _ = emptyArray
--   createArray n x f = runArray $ do
--     mary &lt;- newArray n x
--     f mary
--     pure mary
--   </pre>
createArray :: Int -> a -> (forall s. () => MutableArray s a -> ST s ()) -> Array 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.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
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
--   overlap.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> MutableArray (PrimState m) a -> Int -> Int -> m ()

-- | Return a newly allocated <a>Array</a> with the specified subrange of
--   the provided <a>Array</a>.
--   
--   <i>Note:</i> 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 <a>MutableArray</a>. with the specified
--   subrange of the provided <a>MutableArray</a>. The provided
--   <a>MutableArray</a> should contain the full subrange specified by the
--   two Ints, but this is not checked.
--   
--   <i>Note:</i> The provided array 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)

-- | The number of elements in an immutable array.
sizeofArray :: Array a -> Int

-- | The number of elements in a mutable array.
sizeofMutableArray :: MutableArray s a -> Int

-- | The empty <a>Array</a>.
emptyArray :: Array a

-- | Create an array from a list of a known length. If the length of the
--   list does not match the given length, this throws an exception.
arrayFromListN :: Int -> [a] -> Array a

-- | Create an array from a list.
arrayFromList :: [a] -> Array a

-- | Strict map over the elements of the array.
mapArray' :: (a -> b) -> Array a -> Array b

-- | This is the fastest, most straightforward way to traverse an array,
--   but it only works correctly with a sufficiently "affine"
--   <a>PrimMonad</a> instance. In particular, it must only produce
--   <i>one</i> result array. <a>ListT</a>-transformed monads, for example,
--   will not work right at all.
traverseArrayP :: PrimMonad m => (a -> m b) -> Array a -> m (Array b)
instance GHC.Internal.Base.Alternative Data.Primitive.Array.Array
instance GHC.Internal.Base.Applicative Data.Primitive.Array.Array
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.Primitive.Array.Array a)
instance (GHC.Internal.Data.Typeable.Internal.Typeable s, GHC.Internal.Data.Typeable.Internal.Typeable a) => GHC.Internal.Data.Data.Data (Data.Primitive.Array.MutableArray s a)
instance Data.Functor.Classes.Eq1 Data.Primitive.Array.Array
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.Internal.Data.Foldable.Foldable Data.Primitive.Array.Array
instance GHC.Internal.Base.Functor Data.Primitive.Array.Array
instance GHC.Internal.IsList.IsList (Data.Primitive.Array.Array a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Data.Primitive.Array.Array a)
instance GHC.Internal.Base.Monad Data.Primitive.Array.Array
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Primitive.Array.Array
instance GHC.Internal.Control.Monad.Fix.MonadFix Data.Primitive.Array.Array
instance GHC.Internal.Base.MonadPlus Data.Primitive.Array.Array
instance Control.Monad.Zip.MonadZip Data.Primitive.Array.Array
instance GHC.Internal.Base.Monoid (Data.Primitive.Array.Array a)
instance Control.DeepSeq.NFData1 Data.Primitive.Array.Array
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Ord1 Data.Primitive.Array.Array
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Read1 Data.Primitive.Array.Array
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Data.Primitive.Array.Array a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Show1 Data.Primitive.Array.Array
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Primitive.Array.Array a)
instance GHC.Internal.Data.Traversable.Traversable Data.Primitive.Array.Array


-- | Primitive boxed mutable variables. This is a generalization of
--   <a>Data.IORef</a>, <a>Data.STRef</a> and <a>Data.STRef.Lazy</a> to
--   work in any <a>PrimMonad</a>.
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>.
--   
--   This function is useful for using <a>MutVar</a> in a safe way in a
--   multithreaded program. If you only have one <a>MutVar</a>, then using
--   <a>atomicModifyMutVar</a> to access and modify it will prevent race
--   conditions.
--   
--   Extending the atomicity to multiple <a>MutVar</a>s is problematic, so
--   if you need to do anything more complicated, using <a>MVar</a> instead
--   is a good idea.
--   
--   <a>atomicModifyMutVar</a> does not apply the function strictly. This
--   means if a program calls <a>atomicModifyMutVar</a> many times, but
--   seldom uses the value, thunks will pile up in memory resulting in a
--   space leak. To avoid this problem, use <a>atomicModifyMutVar'</a>
--   instead.
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>.
--   
--   <a>modifyMutVar</a> does not apply the function strictly. This means
--   if a program calls <a>modifyMutVar</a> many times, but seldom uses the
--   value, thunks will pile up in memory resulting in a space leak. To
--   avoid this problem, use <a>modifyMutVar'</a> instead.
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 ()

-- | Convert <a>MutVar</a> to <a>IORef</a>
mutVarFromIORef :: IORef a -> MutVar RealWorld a

-- | Convert <a>MutVar</a> to <a>IORef</a>
mutVarToIORef :: MutVar RealWorld a -> IORef a

-- | Convert <a>MutVar</a> to <a>STRef</a>
mutVarFromSTRef :: STRef s a -> MutVar s a

-- | Convert <a>MutVar</a> to <a>STRef</a>
mutVarToSTRef :: MutVar s a -> STRef s a
instance GHC.Classes.Eq (Data.Primitive.MutVar.MutVar s a)


-- | Small arrays are boxed (im)mutable arrays.
--   
--   The underlying structure of the <a>Array</a> 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, <a>Array</a>
--   would likely be superior.
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.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newSmallArray :: PrimMonad m => Int -> a -> m (SmallMutableArray (PrimState m) a)

-- | Read the element at a given index in a mutable array.
--   
--   <i>Note:</i> this function does not do bounds checking.
readSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> m a

-- | Write an element at the given idex in a mutable array.
--   
--   <i>Note:</i> this function does not do bounds checking.
writeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> a -> m ()

-- | Copy a slice of an immutable array into a mutable array.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copySmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallArray a -> Int -> Int -> m ()

-- | Copy a slice of one mutable array into another.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copySmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallMutableArray (PrimState m) a -> Int -> Int -> m ()

-- | Look up an element in an immutable array.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexSmallArray :: SmallArray a -> Int -> a

-- | Look up an element in an immutable array.
--   
--   The purpose of returning a result using an applicative 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>
--   
--   It also 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.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexSmallArrayM :: Applicative m => SmallArray a -> Int -> m a

-- | Read a value from the immutable array at the given index, returning
--   the result in an unboxed unary tuple. This is currently used to
--   implement folds.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexSmallArray## :: SmallArray a -> Int -> (# a #)

-- | Create a copy of a slice of an immutable array.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
cloneSmallArray :: SmallArray a -> Int -> Int -> SmallArray a

-- | Create a copy of a slice of a mutable array.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
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.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
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.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
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)

-- | Execute the monadic action and freeze the resulting array.
--   
--   <pre>
--   runSmallArray m = runST $ m &gt;&gt;= unsafeFreezeSmallArray
--   </pre>
runSmallArray :: (forall s. () => ST s (SmallMutableArray s a)) -> SmallArray a

-- | Create an array of the given size with a default value, apply the
--   monadic function and freeze the result. If the size is 0, return
--   <a>emptySmallArray</a> (rather than a new copy thereof).
--   
--   <pre>
--   createSmallArray 0 _ _ = emptySmallArray
--   createSmallArray n x f = runSmallArray $ do
--     mary &lt;- newSmallArray n x
--     f mary
--     pure mary
--   </pre>
createSmallArray :: Int -> a -> (forall s. () => SmallMutableArray s a -> ST s ()) -> SmallArray a

-- | The number of elements in an immutable array.
sizeofSmallArray :: SmallArray a -> Int

-- | Get the number of elements in a mutable array. Unlike
--   <a>sizeofSmallMutableArray</a>, this function will be sure to produce
--   the correct result if <a>SmallMutableArray</a> has been shrunk in
--   place. Consider the following:
--   
--   <pre>
--   do
--     sa &lt;- <a>newSmallArray</a> 10 x
--     print $ <a>sizeofSmallMutableArray</a> sa
--     <a>shrinkSmallMutableArray</a> sa 5
--     print $ sizeofSmallMutableArray sa
--   </pre>
--   
--   The compiler is well within its rights to eliminate the second size
--   check and print <tt>10</tt> twice. However,
--   <a>getSizeofSmallMutableArray</a> will check the size each time it's
--   <i>executed</i> (not <i>evaluated</i>), so it won't have this problem:
--   
--   <pre>
--   do
--     sa &lt;- <a>newSmallArray</a> 10 x
--     print =&lt;&lt; getSizeofSmallMutableArray sa
--     <a>shrinkSmallMutableArray</a> sa 5
--     print =&lt;&lt; getSizeofSmallMutableArray sa
--   </pre>
--   
--   will certainly print <tt>10</tt> and then <tt>5</tt>.
getSizeofSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> m Int

-- | The number of elements in a mutable array. This should only be used
--   for arrays that are not shrunk in place.
--   
--   This is deprecated and will be removed in a future release. Use
--   <a>getSizeofSmallMutableArray</a> instead.

-- | <i>Deprecated: use getSizeofSmallMutableArray instead</i>
sizeofSmallMutableArray :: SmallMutableArray s a -> Int

-- | Shrink the mutable array in place. The size given must be equal to or
--   less than the current size of the array. This is not checked.
shrinkSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> m ()

-- | Resize a mutable array to new specified size. The returned
--   <a>SmallMutableArray</a> is either the original
--   <a>SmallMutableArray</a> resized in-place or, if not possible, a newly
--   allocated <a>SmallMutableArray</a> with the original content copied
--   over.
--   
--   To avoid undefined behaviour, the original <a>SmallMutableArray</a>
--   shall not be accessed anymore after a <a>resizeSmallMutableArray</a>
--   has been performed. Moreover, no reference to the old one should be
--   kept in order to allow garbage collection of the original
--   <a>SmallMutableArray</a> in case a new <a>SmallMutableArray</a> had to
--   be allocated.
resizeSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> a -> m (SmallMutableArray (PrimState m) a)

-- | The empty <a>SmallArray</a>.
emptySmallArray :: SmallArray a

-- | Create a <a>SmallArray</a> from a list.
smallArrayFromList :: [a] -> SmallArray a

-- | Create a <a>SmallArray</a> from a list of a known length. If the
--   length of the list does not match the given length, this throws an
--   exception.
smallArrayFromListN :: Int -> [a] -> SmallArray a

-- | Strict map over the elements of the array.
mapSmallArray' :: (a -> b) -> SmallArray a -> SmallArray b

-- | This is the fastest, most straightforward way to traverse an array,
--   but it only works correctly with a sufficiently "affine"
--   <a>PrimMonad</a> instance. In particular, it must only produce
--   <i>one</i> result array. <a>ListT</a>-transformed monads, for example,
--   will not work right at all.
traverseSmallArrayP :: PrimMonad m => (a -> m b) -> SmallArray a -> m (SmallArray b)
instance GHC.Internal.Base.Alternative Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Applicative Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.Primitive.SmallArray.SmallArray a)
instance (GHC.Internal.Data.Typeable.Internal.Typeable s, GHC.Internal.Data.Typeable.Internal.Typeable a) => GHC.Internal.Data.Data.Data (Data.Primitive.SmallArray.SmallMutableArray s a)
instance Data.Functor.Classes.Eq1 Data.Primitive.SmallArray.SmallArray
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.Internal.Data.Foldable.Foldable Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Functor Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.IsList.IsList (Data.Primitive.SmallArray.SmallArray a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Control.Monad.Fix.MonadFix Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.MonadPlus Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Monad Data.Primitive.SmallArray.SmallArray
instance Control.Monad.Zip.MonadZip Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Monoid (Data.Primitive.SmallArray.SmallArray a)
instance Control.DeepSeq.NFData1 Data.Primitive.SmallArray.SmallArray
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Ord1 Data.Primitive.SmallArray.SmallArray
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Read1 Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Show1 Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Data.Traversable.Traversable Data.Primitive.SmallArray.SmallArray


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

-- | Class of types supporting primitive array operations. This includes
--   interfacing with GC-managed memory (functions suffixed with
--   <tt>ByteArray#</tt>) and interfacing with unmanaged memory (functions
--   suffixed with <tt>Addr#</tt>). Endianness is platform-dependent.
class Prim a

-- | The size of values of type <tt>a</tt> in bytes. This has to be used
--   with TypeApplications: <tt>sizeOfType @a</tt>.
sizeOfType# :: Prim a => Proxy a -> Int#

-- | The size of values of type <tt>a</tt> in bytes. The argument is not
--   used.
--   
--   It is recommended to use <a>sizeOfType#</a> instead.
sizeOf# :: Prim a => a -> Int#

-- | The alignment of values of type <tt>a</tt> in bytes. This has to be
--   used with TypeApplications: <tt>alignmentOfType @a</tt>.
alignmentOfType# :: Prim a => Proxy a -> Int#

-- | The alignment of values of type <tt>a</tt> in bytes. The argument is
--   not used.
--   
--   It is recommended to use <a>alignmentOfType#</a> instead.
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

-- | The size of values of type <tt>a</tt> in bytes. The argument is not
--   used.
--   
--   It is recommended to use <a>sizeOfType</a> instead.
--   
--   This function has existed since 0.1, but was moved from
--   <a>Primitive</a> to <a>Types</a> in version 0.6.3.0.
sizeOf :: Prim a => a -> Int

-- | The size of values of type <tt>a</tt> in bytes. This has to be used
--   with TypeApplications: <tt>sizeOfType @a</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; import Data.Int (Int32)
--   
--   &gt;&gt;&gt; sizeOfType @Int32
--   4
--   </pre>
sizeOfType :: Prim a => Int

-- | The alignment of values of type <tt>a</tt> in bytes. The argument is
--   not used.
--   
--   It is recommended to use <a>alignmentOfType</a> instead.
--   
--   This function has existed since 0.1, but was moved from
--   <a>Primitive</a> to <a>Types</a> in version 0.6.3.0.
alignment :: Prim a => a -> Int

-- | The alignment of values of type <tt>a</tt> in bytes. This has to be
--   used with TypeApplications: <tt>alignmentOfType @a</tt>.
alignmentOfType :: Prim a => Int

-- | An implementation of <a>setByteArray#</a> that calls
--   <a>writeByteArray#</a> to set each element. This is helpful when
--   writing a <a>Prim</a> instance for a multi-word data type for which
--   there is no CPU-accelerated way to broadcast a value to contiguous
--   memory. It is typically used alongside <a>defaultSetOffAddr#</a>. For
--   example:
--   
--   <pre>
--   data Trip = Trip Int Int Int
--   
--   instance Prim Trip
--     sizeOfType# _ = 3# *# sizeOfType# (proxy# :: Proxy# Int)
--     alignmentOfType# _ = alignmentOfType# (proxy# :: Proxy# Int)
--     indexByteArray# arr# i# = ...
--     readByteArray# arr# i# = ...
--     writeByteArray# arr# i# (Trip a b c) =
--       \s0 -&gt; case writeByteArray# arr# (3# *# i#) a s0 of
--          s1 -&gt; case writeByteArray# arr# ((3# *# i#) +# 1#) b s1 of
--            s2 -&gt; case writeByteArray# arr# ((3# *# i#) +# 2# ) c s2 of
--              s3 -&gt; s3
--     setByteArray# = defaultSetByteArray#
--     indexOffAddr# addr# i# = ...
--     readOffAddr# addr# i# = ...
--     writeOffAddr# addr# i# (Trip a b c) =
--       \s0 -&gt; case writeOffAddr# addr# (3# *# i#) a s0 of
--          s1 -&gt; case writeOffAddr# addr# ((3# *# i#) +# 1#) b s1 of
--            s2 -&gt; case writeOffAddr# addr# ((3# *# i#) +# 2# ) c s2 of
--              s3 -&gt; s3
--     setOffAddr# = defaultSetOffAddr#
--   </pre>
defaultSetByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s

-- | An implementation of <a>setOffAddr#</a> that calls
--   <a>writeOffAddr#</a> to set each element. The documentation of
--   <a>defaultSetByteArray#</a> provides an example of how to use this.
defaultSetOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s

-- | Newtype that uses a <a>Prim</a> instance to give rise to a
--   <a>Storable</a> instance. This type is intended to be used with the
--   <tt>DerivingVia</tt> extension available in GHC 8.6 and up. For
--   example, consider a user-defined <a>Prim</a> instance for a multi-word
--   data type.
--   
--   <pre>
--   data Uuid = Uuid Word64 Word64
--     deriving Storable via (PrimStorable Uuid)
--   instance Prim Uuid where ...
--   </pre>
--   
--   Writing the <a>Prim</a> instance is tedious and unavoidable, but the
--   <a>Storable</a> instance comes for free once the <a>Prim</a> instance
--   is written.
newtype PrimStorable a
PrimStorable :: a -> PrimStorable a
[getPrimStorable] :: PrimStorable a -> a

-- | A value of type <tt><a>Ptr</a> a</tt> represents a pointer to an
--   object, or an array of objects, which may be marshalled to or from
--   Haskell values of type <tt>a</tt>.
--   
--   The type <tt>a</tt> will often be an instance of class <a>Storable</a>
--   which provides the marshalling operations. However this is not
--   essential, and you can provide your own operations to access the
--   pointer. For example you might write small foreign functions to get or
--   set the fields of a C <tt>struct</tt>.
data Ptr a
Ptr :: Addr# -> Ptr a
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CBlkCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CBlkSize
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CBool
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CCc
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CClock
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CClockId
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CDev
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CDouble
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CFloat
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CFsBlkCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CFsFilCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CGid
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CId
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CIno
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CInt
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CIntMax
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CIntPtr
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CKey
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CLLong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CLong
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CMode
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CNlink
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.COff
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CPid
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CPtrdiff
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CRLim
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSUSeconds
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CShort
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSigAtomic
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSize
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CSpeed
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CSsize
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CTcflag
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CTime
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CTimer
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUInt
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUIntMax
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUIntPtr
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CULLong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CULong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUSeconds
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUShort
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CUid
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CWchar
instance Data.Primitive.Types.Prim GHC.Types.Char
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Complex.Complex a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Functor.Const.Const a b)
instance Data.Primitive.Types.Prim GHC.Types.Double
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Ord.Down a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.Fd
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.First a)
instance Data.Primitive.Types.Prim GHC.Types.Float
instance Data.Primitive.Types.Prim (GHC.Internal.Ptr.FunPtr a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Functor.Identity.Identity a)
instance Data.Primitive.Types.Prim GHC.Types.Int
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int16
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int32
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int64
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int8
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.Ptr.IntPtr
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Last a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Max a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Min a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Product a)
instance Data.Primitive.Types.Prim (GHC.Internal.Ptr.Ptr a)
instance Data.Primitive.Types.Prim (GHC.Internal.Stable.StablePtr a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Sum a)
instance Data.Primitive.Types.Prim GHC.Types.Word
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word16
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word32
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word64
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word8
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.Ptr.WordPtr
instance Data.Primitive.Types.Prim a => GHC.Internal.Foreign.Storable.Storable (Data.Primitive.Types.PrimStorable a)


-- | Primitive operations on byte arrays. Most functions in this module
--   include an element type in their type signature and interpret the unit
--   for offsets and lengths as that element. A few functions (e.g.
--   <a>copyByteArray</a>, <a>freezeByteArray</a>) do not include an
--   element type. Such functions interpret offsets and lengths as units of
--   8-bit words.
module Data.Primitive.ByteArray

-- | Lifted wrapper for <a>ByteArray#</a>.
--   
--   Since <a>ByteArray#</a> is an unlifted type and not a member of kind
--   <a>Type</a>, things like <tt>[ByteArray#]</tt> or <tt>IO
--   ByteArray#</tt> are ill-typed. To work around this inconvenience this
--   module provides a standard lifted wrapper, inhabiting <a>Type</a>.
--   Clients are expected to use <a>ByteArray</a> in higher-level APIs, but
--   wrap and unwrap <a>ByteArray</a> internally as they please and use
--   functions from <a>GHC.Exts</a>.
data ByteArray
ByteArray :: ByteArray# -> ByteArray

-- | Lifted wrapper for <a>MutableByteArray#</a>.
--   
--   Since <a>MutableByteArray#</a> is an unlifted type and not a member of
--   kind <a>Type</a>, things like <tt>[MutableByteArray#]</tt> or <tt>IO
--   MutableByteArray#</tt> are ill-typed. To work around this
--   inconvenience this module provides a standard lifted wrapper,
--   inhabiting <a>Type</a>. Clients are expected to use
--   <a>MutableByteArray</a> in higher-level APIs, but wrap and unwrap
--   <a>MutableByteArray</a> internally as they please and use functions
--   from <a>GHC.Exts</a>.
data MutableByteArray s
MutableByteArray :: MutableByteArray# s -> MutableByteArray s

-- | A boxed, unlifted datatype representing a region of raw memory in the
--   garbage-collected heap, which is not scanned for pointers during
--   garbage collection.
--   
--   It is created by freezing a <a>MutableByteArray#</a> with
--   <a>unsafeFreezeByteArray#</a>. Freezing is essentially a no-op, as
--   <a>MutableByteArray#</a> and <a>ByteArray#</a> share the same heap
--   structure under the hood.
--   
--   The immutable and mutable variants are commonly used for scenarios
--   requiring high-performance data structures, like <tt>Text</tt>,
--   <tt>Primitive Vector</tt>, <tt>Unboxed Array</tt>, and
--   <tt>ShortByteString</tt>.
--   
--   Another application of fundamental importance is <tt>Integer</tt>,
--   which is backed by <a>ByteArray#</a>.
--   
--   The representation on the heap of a Byte Array is:
--   
--   <pre>
--   +------------+-----------------+-----------------------+
--   |            |                 |                       |
--   |   HEADER   | SIZE (in bytes) |       PAYLOAD         |
--   |            |                 |                       |
--   +------------+-----------------+-----------------------+
--   </pre>
--   
--   To obtain a pointer to actual payload (e.g., for FFI purposes) use
--   <a>byteArrayContents#</a> or <a>mutableByteArrayContents#</a>.
--   
--   Alternatively, enabling the <tt>UnliftedFFITypes</tt> extension allows
--   to mention <a>ByteArray#</a> and <a>MutableByteArray#</a> in FFI type
--   signatures directly.
data ByteArray# :: UnliftedType

-- | A mutable <tt>ByteAray#</tt>. It can be created in three ways:
--   
--   <ul>
--   <li><a>newByteArray#</a>: Create an unpinned array.</li>
--   <li><a>newPinnedByteArray#</a>: This will create a pinned array,</li>
--   <li><a>newAlignedPinnedByteArray#</a>: This will create a pinned
--   array, with a custom alignment.</li>
--   </ul>
--   
--   Unpinned arrays can be moved around during garbage collection, so you
--   must not store or pass pointers to these values if there is a chance
--   for the garbage collector to kick in. That said, even unpinned arrays
--   can be passed to unsafe FFI calls, because no garbage collection
--   happens during these unsafe calls (see <a>Guaranteed Call Safety</a>
--   in the GHC Manual). For safe FFI calls, byte arrays must be not only
--   pinned, but also kept alive by means of the keepAlive# function for
--   the duration of a call (that's because garbage collection cannot move
--   a pinned array, but is free to scrap it altogether).
data MutableByteArray# a :: UnliftedType

-- | Create a new mutable byte array of the specified size in bytes. The
--   underlying memory is left uninitialized.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size in bytes. The
--   garbage collector is guaranteed not to move it. The underlying memory
--   is left uninitialized.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size in bytes and
--   with the given alignment. The garbage collector is guaranteed not to
--   move it. The underlying memory is left uninitialized.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newAlignedPinnedByteArray :: PrimMonad m => Int -> Int -> m (MutableByteArray (PrimState m))

-- | Resize a mutable byte array. The new size is given in bytes.
--   
--   This will either resize the array in-place or, if not possible,
--   allocate the contents into a new, unpinned array and copy the original
--   array's contents.
--   
--   To avoid undefined behaviour, the original <a>MutableByteArray</a>
--   shall not be accessed anymore after a <a>resizeMutableByteArray</a>
--   has been performed. Moreover, no reference to the old one should be
--   kept in order to allow garbage collection of the original
--   <a>MutableByteArray</a> in case a new <a>MutableByteArray</a> had to
--   be allocated.
resizeMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m (MutableByteArray (PrimState m))

-- | Shrink a mutable byte array. The new size is given in bytes. It must
--   be smaller than the old size. The array will be resized in place.
shrinkMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m ()

-- | Read a primitive value from the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes.
--   
--   <i>Note:</i> this function does not do bounds checking.
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.
--   
--   <i>Note:</i> this function does not do bounds checking.
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.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexByteArray :: Prim a => ByteArray -> Int -> a

-- | Read an 8-bit element from the byte array, interpreting it as a
--   Latin-1-encoded character. The offset is given in bytes.
--   
--   <i>Note:</i> this function does not do bounds checking.
readCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m Char

-- | Write a character to the byte array, encoding it with Latin-1 as a
--   single byte. Behavior is undefined for codepoints outside of the ASCII
--   and Latin-1 blocks. The offset is given in bytes.
--   
--   <i>Note:</i> this function does not do bounds checking.
writeCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Char -> m ()

-- | Read an 8-bit element from the byte array, interpreting it as a
--   Latin-1-encoded character. The offset is given in bytes.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexCharArray :: ByteArray -> Int -> Char

-- | The empty <a>ByteArray</a>.
emptyByteArray :: ByteArray

-- | Create a <a>ByteArray</a> from a list.
--   
--   <pre>
--   byteArrayFromList xs = <a>byteArrayFromListN</a> (length xs) xs
--   </pre>
byteArrayFromList :: Prim a => [a] -> ByteArray

-- | Create a <a>ByteArray</a> from a list of a known length. If the length
--   of the list does not match the given length, this throws an exception.
byteArrayFromListN :: Prim a => Int -> [a] -> ByteArray

-- | Right-fold over the elements of a <a>ByteArray</a>.
foldrByteArray :: Prim a => (a -> b -> b) -> b -> ByteArray -> b

-- | Lexicographic comparison of equal-length slices into two byte arrays.
--   This wraps the <tt>compareByteArrays#</tt> primop, which wraps
--   <tt>memcmp</tt>.
compareByteArrays :: ByteArray -> Int -> ByteArray -> Int -> Int -> Ordering

-- | Create an immutable copy of a slice of a byte array. The offset and
--   length are given in bytes.
--   
--   This operation makes a copy of the specified section, so it is safe to
--   continue using the mutable array afterward.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
freezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m ByteArray

-- | Create a mutable byte array from a slice of an immutable byte array.
--   The offset and length are given in bytes.
--   
--   This operation makes a copy of the specified slice, so it is safe to
--   use the immutable array afterward.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
thawByteArray :: PrimMonad m => ByteArray -> Int -> Int -> m (MutableByteArray (PrimState m))

-- | Execute the monadic action and freeze the resulting array.
--   
--   <pre>
--   runByteArray m = runST $ m &gt;&gt;= unsafeFreezeByteArray
--   </pre>
runByteArray :: (forall s. () => ST s (MutableByteArray s)) -> ByteArray
createByteArray :: Int -> (forall s. () => MutableByteArray s -> ST s ()) -> ByteArray

-- | 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.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
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.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()

-- | Copy a slice of a byte array to an unmanaged pointer address. These
--   must not overlap. The offset and length are given in elements, not in
--   bytes.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> ByteArray -> Int -> Int -> m ()

-- | Copy a slice of a mutable byte array to an unmanaged pointer address.
--   These must not overlap. The offset and length are given in elements,
--   not in bytes.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutableByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutableByteArray (PrimState m) -> Int -> Int -> m ()

-- | Copy a slice of a byte array to an unmanaged address. These must not
--   overlap.
--   
--   Note: This function is just <a>copyByteArrayToPtr</a> where <tt>a</tt>
--   is <a>Word8</a>.
copyByteArrayToAddr :: PrimMonad m => Ptr Word8 -> ByteArray -> Int -> Int -> m ()

-- | Copy a slice of a mutable byte array to an unmanaged address. These
--   must not overlap.
--   
--   Note: This function is just <a>copyMutableByteArrayToPtr</a> where
--   <tt>a</tt> is <a>Word8</a>.
copyMutableByteArrayToAddr :: PrimMonad m => Ptr Word8 -> MutableByteArray (PrimState m) -> Int -> Int -> m ()

-- | Copy from an unmanaged pointer address to a byte array. These must not
--   overlap. The offset and length are given in elements, not in bytes.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> 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.
--   
--   <i>Note:</i> this function does not do bounds checking.
setByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> Int -> a -> m ()

-- | Fill a slice of a mutable byte array with a byte.
--   
--   <i>Note:</i> this function does not do bounds checking.
fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> 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.
cloneByteArray :: ByteArray -> Int -> Int -> ByteArray

-- | Return a newly allocated mutable array with the specified subrange of
--   the provided mutable array. The provided mutable array should contain
--   the full subrange specified by the two Ints, but this is not checked.
cloneMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m (MutableByteArray (PrimState m))

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

-- | Size of the mutable byte array in bytes.
--   
--   This function is deprecated and will be removed. Its behavior is
--   undefined if <a>resizeMutableByteArray</a> is ever called on the
--   mutable byte array given as the argument. Prefer
--   <a>getSizeofMutableByteArray</a>, which ensures correct sequencing in
--   the presence of resizing.

-- | <i>Deprecated: use getSizeofMutableByteArray instead</i>
sizeofMutableByteArray :: MutableByteArray s -> Int

-- | Get the size of a byte array in bytes. Unlike
--   <a>sizeofMutableByteArray</a>, this function ensures sequencing in the
--   presence of resizing.
getSizeofMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m Int

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

-- | Check whether or not the byte array is pinned. Pinned byte arrays
--   cannot be moved by the garbage collector. It is safe to use
--   <a>byteArrayContents</a> on such byte arrays.
--   
--   Caution: This function is only available when compiling with GHC 8.2
--   or newer.
isByteArrayPinned :: ByteArray -> Bool

-- | Check whether or not the mutable byte array is pinned.
--   
--   Caution: This function is only available when compiling with GHC 8.2
--   or newer.
isMutableByteArrayPinned :: MutableByteArray s -> Bool

-- | Create a foreign pointer that points to the array's data. This
--   operation is only safe on <i>pinned</i> byte arrays. The array's data
--   is not garbage collected while references to the foreign pointer
--   exist. Writing to the array through the foreign pointer results in
--   undefined behavior.
byteArrayAsForeignPtr :: ByteArray -> ForeignPtr Word8

-- | Variant of <a>byteArrayAsForeignPtr</a> for mutable byte arrays.
--   Similarly, this is only safe on <i>pinned</i> mutable byte arrays.
--   This function differs from the variant for immutable arrays in that it
--   is safe to write to the array though the foreign pointer.
mutableByteArrayAsForeignPtr :: MutableByteArray RealWorld -> ForeignPtr Word8

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays. Byte arrays allocated by
--   <a>newPinnedByteArray</a> and <a>newAlignedPinnedByteArray</a> are
--   guaranteed to be pinned. Byte arrays allocated by <a>newByteArray</a>
--   may or may not be pinned (use <a>isByteArrayPinned</a> to figure out).
--   
--   Prefer <a>withByteArrayContents</a>, which ensures that the array is
--   not garbage collected while the pointer is being used.
byteArrayContents :: ByteArray -> Ptr Word8

-- | A composition of <a>byteArrayContents</a> and
--   <a>keepAliveUnlifted</a>. The callback function must not return the
--   pointer. The argument byte array must be <i>pinned</i>. See
--   <a>byteArrayContents</a> for an explanation of which byte arrays are
--   pinned.
--   
--   Note: This could be implemented with <a>keepAlive</a> instead of
--   <a>keepAliveUnlifted</a>, but <a>keepAlive</a> here would cause GHC to
--   materialize the wrapper data constructor on the heap.
withByteArrayContents :: PrimBase m => ByteArray -> (Ptr Word8 -> m a) -> m a

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays. See <a>byteArrayContents</a> for an
--   explanation of which byte arrays are pinned.
--   
--   Prefer <a>withByteArrayContents</a>, which ensures that the array is
--   not garbage collected while the pointer is being used.
mutableByteArrayContents :: MutableByteArray s -> Ptr Word8

-- | A composition of <a>mutableByteArrayContents</a> and
--   <a>keepAliveUnlifted</a>. The callback function must not return the
--   pointer. The argument byte array must be <i>pinned</i>. See
--   <a>byteArrayContents</a> for an explanation of which byte arrays are
--   pinned.
withMutableByteArrayContents :: PrimBase m => MutableByteArray (PrimState m) -> (Ptr Word8 -> m a) -> m a


-- | Arrays of unboxed primitive types. The functions provided by this
--   module match the behavior of those provided by
--   <a>Data.Primitive.ByteArray</a>, and the underlying types and primops
--   that back them are the same. However, the type constructors
--   <a>PrimArray</a> and <a>MutablePrimArray</a> take one additional
--   argument compared to their respective counterparts <a>ByteArray</a>
--   and <a>MutableByteArray</a>. This argument is used to designate the
--   type of element in the array. Consequently, all functions in this
--   module accept length and indices in terms of elements, not bytes.
module Data.Primitive.PrimArray

-- | Arrays of unboxed elements. This accepts types like <a>Double</a>,
--   <a>Char</a>, <a>Int</a> and <a>Word</a>, as well as their fixed-length
--   variants (<a>Word8</a>, <a>Word16</a>, etc.). Since the elements are
--   unboxed, a <a>PrimArray</a> is strict in its elements. This differs
--   from the behavior of <a>Array</a>, which is lazy in its elements.
data PrimArray a
PrimArray :: ByteArray# -> PrimArray a

-- | Mutable primitive arrays associated with a primitive state token.
--   These can be written to and read from in a monadic context that
--   supports sequencing, such as <a>IO</a> or <a>ST</a>. Typically, a
--   mutable primitive array will be built and then converted to an
--   immutable primitive array using <a>unsafeFreezePrimArray</a>. However,
--   it is also acceptable to simply discard a mutable primitive array
--   since it lives in managed memory and will be garbage collected when no
--   longer referenced.
data MutablePrimArray s a
MutablePrimArray :: MutableByteArray# s -> MutablePrimArray s a

-- | Create a new mutable primitive array of the given length. The
--   underlying memory is left uninitialized.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
newPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Create a <i>pinned</i> primitive array of the specified size (in
--   elements). The garbage collector is guaranteed not to move it. The
--   underlying memory is left uninitialized.
newPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Create a <i>pinned</i> primitive array of the specified size (in
--   elements) and with the alignment given by its <a>Prim</a> instance.
--   The garbage collector is guaranteed not to move it. The underlying
--   memory is left uninitialized.
newAlignedPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Resize a mutable primitive array. The new size is given in elements.
--   
--   This will either resize the array in-place or, if not possible,
--   allocate the contents into a new, unpinned array and copy the original
--   array's contents.
--   
--   To avoid undefined behaviour, the original <a>MutablePrimArray</a>
--   shall not be accessed anymore after a <a>resizeMutablePrimArray</a>
--   has been performed. Moreover, no reference to the old one should be
--   kept in order to allow garbage collection of the original
--   <a>MutablePrimArray</a> in case a new <a>MutablePrimArray</a> had to
--   be allocated.
resizeMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> m (MutablePrimArray (PrimState m) a)

-- | Shrink a mutable primitive array. The new size is given in elements.
--   It must be smaller than the old size. The array will be resized in
--   place.
shrinkMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> m ()

-- | Read a value from the array at the given index.
--   
--   <i>Note:</i> this function does not do bounds checking.
readPrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> m a

-- | Write an element to the given index.
--   
--   <i>Note:</i> this function does not do bounds checking.
writePrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> a -> m ()

-- | Read a primitive value from the primitive array.
--   
--   <i>Note:</i> this function does not do bounds checking.
indexPrimArray :: Prim a => PrimArray a -> Int -> a

-- | Create an immutable copy of a slice of a primitive array. The offset
--   and length are given in elements.
--   
--   This operation makes a copy of the specified section, so it is safe to
--   continue using the mutable array afterward.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
freezePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Int -> m (PrimArray a)

-- | Create a mutable primitive array from a slice of an immutable
--   primitive array. The offset and length are given in elements.
--   
--   This operation makes a copy of the specified slice, so it is safe to
--   use the immutable array afterward.
--   
--   <i>Note:</i> The provided array should contain the full subrange
--   specified by the two Ints, but this is not checked.
thawPrimArray :: (PrimMonad m, Prim a) => PrimArray a -> Int -> Int -> m (MutablePrimArray (PrimState m) a)

-- | Execute the monadic action and freeze the resulting array.
--   
--   <pre>
--   runPrimArray m = runST $ m &gt;&gt;= unsafeFreezePrimArray
--   </pre>
runPrimArray :: (forall s. () => ST s (MutablePrimArray s a)) -> PrimArray a

-- | Create an uninitialized array of the given length, apply the function
--   to it, and freeze the result.
--   
--   <i>Note:</i> this function does not check if the input is
--   non-negative.
--   
--   @since FIXME
createPrimArray :: Prim a => Int -> (forall s. () => MutablePrimArray s a -> ST s ()) -> PrimArray a

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

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

-- | Copy part of an array into another mutable array.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> PrimArray a -> Int -> Int -> m ()

-- | Copy part of a mutable array into another mutable array. In the case
--   that the destination and source arrays are the same, the regions may
--   overlap.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()

-- | Copy a slice of an immutable primitive array to a pointer. The offset
--   and length are given in elements of type <tt>a</tt>. This function
--   assumes that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <a>Storable</a> instance.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> PrimArray a -> Int -> Int -> m ()

-- | Copy a slice of a mutable primitive array to a pointer. The offset and
--   length are given in elements of type <tt>a</tt>. This function assumes
--   that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <a>Storable</a> instance.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutablePrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()

-- | Copy from a pointer to a mutable primitive array. The offset and
--   length are given in elements of type <tt>a</tt>. This function assumes
--   that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <a>Storable</a> instance.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> 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.
clonePrimArray :: Prim a => PrimArray a -> Int -> Int -> PrimArray a

-- | Return a newly allocated mutable array with the specified subrange of
--   the provided mutable array. The provided mutable array should contain
--   the full subrange specified by the two Ints, but this is not checked.
cloneMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Int -> m (MutablePrimArray (PrimState m) a)

-- | Fill a slice of a mutable primitive array with a value.
--   
--   <i>Note:</i> this function does not do bounds checking.
setPrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> Int -> a -> m ()

-- | Check if the two arrays refer to the same memory block.
sameMutablePrimArray :: MutablePrimArray s a -> MutablePrimArray s a -> Bool

-- | Get the size of a mutable primitive array in elements. Unlike
--   <a>sizeofMutablePrimArray</a>, this function ensures sequencing in the
--   presence of resizing.
getSizeofMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> m Int

-- | Size of the mutable primitive array in elements. This function shall
--   not be used on primitive arrays that are an argument to or a result of
--   <a>resizeMutablePrimArray</a> or <a>shrinkMutablePrimArray</a>.
--   
--   This function is deprecated and will be removed.

-- | <i>Deprecated: use getSizeofMutablePrimArray instead</i>
sizeofMutablePrimArray :: forall s a. Prim a => MutablePrimArray s a -> Int

-- | Get the size, in elements, of the primitive array.
sizeofPrimArray :: Prim a => PrimArray a -> Int

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> prim arrays allocated by <a>newPinnedByteArray</a> or
--   <a>newAlignedPinnedByteArray</a>.
primArrayContents :: PrimArray a -> Ptr a

-- | A composition of <a>primArrayContents</a> and
--   <a>keepAliveUnlifted</a>. The callback function must not return the
--   pointer. The argument array must be <i>pinned</i>. See
--   <a>primArrayContents</a> for an explanation of which primitive arrays
--   are pinned.
--   
--   Note: This could be implemented with <a>keepAlive</a> instead of
--   <a>keepAliveUnlifted</a>, but <a>keepAlive</a> here would cause GHC to
--   materialize the wrapper data constructor on the heap.
withPrimArrayContents :: PrimBase m => PrimArray a -> (Ptr a -> m a) -> m a

-- | 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>.
mutablePrimArrayContents :: MutablePrimArray s a -> Ptr a

-- | A composition of <a>mutablePrimArrayContents</a> and
--   <a>keepAliveUnlifted</a>. The callback function must not return the
--   pointer. The argument array must be <i>pinned</i>. See
--   <a>primArrayContents</a> for an explanation of which primitive arrays
--   are pinned.
withMutablePrimArrayContents :: PrimBase m => MutablePrimArray (PrimState m) a -> (Ptr a -> m a) -> m a

-- | Check whether or not the primitive array is pinned. Pinned primitive
--   arrays cannot be moved by the garbage collector. It is safe to use
--   <a>primArrayContents</a> on such arrays. This function is only
--   available when compiling with GHC 8.2 or newer.
isPrimArrayPinned :: PrimArray a -> Bool

-- | Check whether or not the mutable primitive array is pinned. This
--   function is only available when compiling with GHC 8.2 or newer.
isMutablePrimArrayPinned :: MutablePrimArray s a -> Bool

-- | Convert a <a>PrimArray</a> to a list.
primArrayToList :: Prim a => PrimArray a -> [a]

-- | Create a <a>PrimArray</a> from a list.
--   
--   <pre>
--   primArrayFromList vs = <a>primArrayFromListN</a> (length vs) vs
--   </pre>
primArrayFromList :: Prim a => [a] -> PrimArray a

-- | Create a <a>PrimArray</a> from a list of a known length. If the length
--   of the list does not match the given length, this throws an exception.
primArrayFromListN :: Prim a => Int -> [a] -> PrimArray a

-- | Lazy right-associated fold over the elements of a <a>PrimArray</a>.
foldrPrimArray :: Prim a => (a -> b -> b) -> b -> PrimArray a -> b

-- | Strict right-associated fold over the elements of a <a>PrimArray</a>.
foldrPrimArray' :: Prim a => (a -> b -> b) -> b -> PrimArray a -> b

-- | Lazy left-associated fold over the elements of a <a>PrimArray</a>.
foldlPrimArray :: Prim a => (b -> a -> b) -> b -> PrimArray a -> b

-- | Strict left-associated fold over the elements of a <a>PrimArray</a>.
foldlPrimArray' :: Prim a => (b -> a -> b) -> b -> PrimArray a -> b

-- | Strict left-associated fold over the elements of a <a>PrimArray</a>.
foldlPrimArrayM' :: (Prim a, Monad m) => (b -> a -> m b) -> b -> PrimArray a -> m b

-- | Traverse the primitive array, discarding the results. There is no
--   <a>PrimMonad</a> variant of this function, since it would not provide
--   any performance benefit.
traversePrimArray_ :: (Applicative f, Prim a) => (a -> f b) -> PrimArray a -> f ()

-- | Traverse the primitive array with the indices, discarding the results.
--   There is no <a>PrimMonad</a> variant of this function, since it would
--   not provide any performance benefit.
itraversePrimArray_ :: (Applicative f, Prim a) => (Int -> a -> f b) -> PrimArray a -> f ()

-- | The empty <a>PrimArray</a>.
emptyPrimArray :: PrimArray a

-- | Map over the elements of a primitive array.
mapPrimArray :: (Prim a, Prim b) => (a -> b) -> PrimArray a -> PrimArray b

-- | Indexed map over the elements of a primitive array.
imapPrimArray :: (Prim a, Prim b) => (Int -> a -> b) -> PrimArray a -> PrimArray b

-- | Generate a primitive array.
generatePrimArray :: Prim a => Int -> (Int -> a) -> PrimArray a

-- | Create a primitive array by copying the element the given number of
--   times.
replicatePrimArray :: Prim a => Int -> a -> PrimArray a

-- | Filter elements of a primitive array according to a predicate.
filterPrimArray :: Prim a => (a -> Bool) -> PrimArray a -> PrimArray a

-- | Map over a primitive array, optionally discarding some elements. This
--   has the same behavior as <tt>Data.Maybe.mapMaybe</tt>.
mapMaybePrimArray :: (Prim a, Prim b) => (a -> Maybe b) -> PrimArray a -> PrimArray b

-- | Traverse a primitive array. The traversal performs all of the
--   applicative effects <i>before</i> forcing the resulting values and
--   writing them to the new primitive array. Consequently:
--   
--   <pre>
--   &gt;&gt;&gt; traversePrimArray (\x -&gt; print x $&gt; bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
--   1
--   2
--   3
--   *** Exception: Prelude.undefined
--   </pre>
--   
--   The function <a>traversePrimArrayP</a> always outperforms this
--   function, but it requires a <a>PrimMonad</a> constraint, and it forces
--   the values as it performs the effects.
traversePrimArray :: (Applicative f, Prim a, Prim b) => (a -> f b) -> PrimArray a -> f (PrimArray b)

-- | Traverse a primitive array with the index of each element.
itraversePrimArray :: (Applicative f, Prim a, Prim b) => (Int -> a -> f b) -> PrimArray a -> f (PrimArray b)

-- | Generate a primitive array by evaluating the applicative generator
--   function at each index.
generatePrimArrayA :: (Applicative f, Prim a) => Int -> (Int -> f a) -> f (PrimArray a)

-- | Execute the applicative action the given number of times and store the
--   results in a <a>PrimArray</a>.
replicatePrimArrayA :: (Applicative f, Prim a) => Int -> f a -> f (PrimArray a)

-- | Filter the primitive array, keeping the elements for which the monadic
--   predicate evaluates true.
filterPrimArrayA :: (Applicative f, Prim a) => (a -> f Bool) -> PrimArray a -> f (PrimArray a)

-- | Map over the primitive array, keeping the elements for which the
--   applicative predicate provides a <a>Just</a>.
mapMaybePrimArrayA :: (Applicative f, Prim a, Prim b) => (a -> f (Maybe b)) -> PrimArray a -> f (PrimArray b)

-- | Traverse a primitive array. The traversal forces the resulting values
--   and writes them to the new primitive array as it performs the monadic
--   effects. Consequently:
--   
--   <pre>
--   &gt;&gt;&gt; traversePrimArrayP (\x -&gt; print x $&gt; bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
--   1
--   2
--   *** Exception: Prelude.undefined
--   </pre>
--   
--   In many situations, <a>traversePrimArrayP</a> can replace
--   <a>traversePrimArray</a>, changing the strictness characteristics of
--   the traversal but typically improving the performance. Consider the
--   following short-circuiting traversal:
--   
--   <pre>
--   incrPositiveA :: PrimArray Int -&gt; Maybe (PrimArray Int)
--   incrPositiveA xs = traversePrimArray (\x -&gt; bool Nothing (Just (x + 1)) (x &gt; 0)) xs
--   </pre>
--   
--   This can be rewritten using <a>traversePrimArrayP</a>. To do this, we
--   must change the traversal context to <tt>MaybeT (ST s)</tt>, which has
--   a <a>PrimMonad</a> instance:
--   
--   <pre>
--   incrPositiveB :: PrimArray Int -&gt; Maybe (PrimArray Int)
--   incrPositiveB xs = runST $ runMaybeT $ traversePrimArrayP
--     (\x -&gt; bool (MaybeT (return Nothing)) (MaybeT (return (Just (x + 1)))) (x &gt; 0))
--     xs
--   </pre>
--   
--   Benchmarks demonstrate that the second implementation runs 150 times
--   faster than the first. It also results in fewer allocations.
traversePrimArrayP :: (PrimMonad m, Prim a, Prim b) => (a -> m b) -> PrimArray a -> m (PrimArray b)

-- | Traverse a primitive array with the indices. The traversal forces the
--   resulting values and writes them to the new primitive array as it
--   performs the monadic effects.
itraversePrimArrayP :: (Prim a, Prim b, PrimMonad m) => (Int -> a -> m b) -> PrimArray a -> m (PrimArray b)

-- | Generate a primitive array by evaluating the monadic generator
--   function at each index.
generatePrimArrayP :: (PrimMonad m, Prim a) => Int -> (Int -> m a) -> m (PrimArray a)

-- | Execute the monadic action the given number of times and store the
--   results in a primitive array.
replicatePrimArrayP :: (PrimMonad m, Prim a) => Int -> m a -> m (PrimArray a)

-- | Filter the primitive array, keeping the elements for which the monadic
--   predicate evaluates to true.
filterPrimArrayP :: (PrimMonad m, Prim a) => (a -> m Bool) -> PrimArray a -> m (PrimArray a)

-- | Map over the primitive array, keeping the elements for which the
--   monadic predicate provides a <a>Just</a>.
mapMaybePrimArrayP :: (PrimMonad m, Prim a, Prim b) => (a -> m (Maybe b)) -> PrimArray a -> m (PrimArray b)
instance GHC.Classes.Eq (Data.Primitive.PrimArray.MutablePrimArray s a)
instance (GHC.Classes.Eq a, Data.Primitive.Types.Prim a) => GHC.Classes.Eq (Data.Primitive.PrimArray.PrimArray a)
instance Data.Primitive.Types.Prim a => GHC.Internal.IsList.IsList (Data.Primitive.PrimArray.PrimArray a)
instance Language.Haskell.TH.Syntax.Lift (Data.Primitive.PrimArray.PrimArray a)
instance GHC.Internal.Base.Monoid (Data.Primitive.PrimArray.PrimArray a)
instance Control.DeepSeq.NFData (Data.Primitive.PrimArray.MutablePrimArray s a)
instance Control.DeepSeq.NFData (Data.Primitive.PrimArray.PrimArray a)
instance (GHC.Classes.Ord a, Data.Primitive.Types.Prim a) => GHC.Classes.Ord (Data.Primitive.PrimArray.PrimArray a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.PrimArray.PrimArray a)
instance (GHC.Internal.Show.Show a, Data.Primitive.Types.Prim a) => GHC.Internal.Show.Show (Data.Primitive.PrimArray.PrimArray a)


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

-- | A value of type <tt><a>Ptr</a> a</tt> represents a pointer to an
--   object, or an array of objects, which may be marshalled to or from
--   Haskell values of type <tt>a</tt>.
--   
--   The type <tt>a</tt> will often be an instance of class <a>Storable</a>
--   which provides the marshalling operations. However this is not
--   essential, and you can provide your own operations to access the
--   pointer. For example you might write small foreign functions to get or
--   set the fields of a C <tt>struct</tt>.
data Ptr a
Ptr :: Addr# -> Ptr a

-- | The constant <a>nullPtr</a> contains a distinguished value of
--   <a>Ptr</a> that is not associated with a valid memory location.
nullPtr :: Ptr a

-- | Offset a pointer by the given number of elements.
advancePtr :: Prim a => Ptr a -> Int -> Ptr a

-- | Subtract a pointer from another pointer. The result represents the
--   number of elements of type <tt>a</tt> that fit in the contiguous
--   memory range bounded by these two pointers.
subtractPtr :: Prim a => Ptr a -> Ptr a -> Int

-- | Read a value from a memory position given by a pointer 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.
indexOffPtr :: Prim a => Ptr a -> 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.
readOffPtr :: (Prim a, PrimMonad m) => Ptr a -> 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.
writeOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m ()

-- | Copy the given number of elements from the second <a>Ptr</a> to the
--   first. The areas may not overlap.
copyPtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()

-- | Copy the given number of elements from the second <a>Ptr</a> to the
--   first. The areas may overlap.
movePtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()

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

-- | Copy from a pointer to a mutable primitive array. The offset and
--   length are given in elements of type <tt>a</tt>. This function assumes
--   that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <a>Storable</a> instance.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()

-- | Copy from an unmanaged pointer address to a byte array. These must not
--   overlap. The offset and length are given in elements, not in bytes.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> Int -> m ()


-- | Reexports all primitive operations.
module Data.Primitive


-- | Variant of <tt>MutVar</tt> that has one less indirection for primitive
--   types. The difference is illustrated by comparing <tt>MutVar Int</tt>
--   and <tt>PrimVar Int</tt>:
--   
--   <ul>
--   <li><tt>MutVar Int</tt>: <tt>MutVar# --&gt; I#</tt></li>
--   <li><tt>PrimVar Int</tt>: <tt>MutableByteArray#</tt></li>
--   </ul>
--   
--   This module is adapted from a module in Edward Kmett's
--   <tt>prim-ref</tt> library.
module Data.Primitive.PrimVar

-- | A <a>PrimVar</a> behaves like a single-element mutable primitive
--   array.
newtype PrimVar s a
PrimVar :: MutablePrimArray s a -> PrimVar s a

-- | Create a primitive reference.
newPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)

-- | Create a pinned primitive reference.
newPinnedPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)

-- | Create a pinned primitive reference with the appropriate alignment for
--   its contents.
newAlignedPinnedPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)

-- | Read a value from the <a>PrimVar</a>.
readPrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> m a

-- | Write a value to the <a>PrimVar</a>.
writePrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> a -> m ()

-- | Mutate the contents of a <a>PrimVar</a>.
modifyPrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> (a -> a) -> m ()

-- | Yield a pointer to the data of a <a>PrimVar</a>. This operation is
--   only safe on pinned byte arrays allocated by <a>newPinnedPrimVar</a>
--   or <a>newAlignedPinnedPrimVar</a>.
primVarContents :: PrimVar s a -> Ptr a

-- | Convert a <a>PrimVar</a> to a one-elment <a>MutablePrimArray</a>.
primVarToMutablePrimArray :: PrimVar s a -> MutablePrimArray s a

-- | Given a primitive reference, the expected old value, and the new
--   value, perform an atomic compare and swap i.e. write the new value if
--   the current value matches the provided old value. Returns the value of
--   the element before the operation.
casInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> Int -> m Int

-- | Given a reference, and a value to add, atomically add the value to the
--   element. Returns the value of the element before the operation.
fetchAddInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, and a value to subtract, atomically subtract the
--   value from the element. Returns the value of the element before the
--   operation.
fetchSubInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, and a value to bitwise and, atomically and the
--   value with the element. Returns the value of the element before the
--   operation.
fetchAndInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, and a value to bitwise nand, atomically nand the
--   value with the element. Returns the value of the element before the
--   operation.
fetchNandInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, and a value to bitwise or, atomically or the value
--   with the element. Returns the value of the element before the
--   operation.
fetchOrInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, and a value to bitwise xor, atomically xor the
--   value with the element. Returns the value of the element before the
--   operation.
fetchXorInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int

-- | Given a reference, atomically read an element.
atomicReadInt :: PrimMonad m => PrimVar (PrimState m) Int -> m Int

-- | Given a reference, atomically write an element.
atomicWriteInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m ()
instance GHC.Classes.Eq (Data.Primitive.PrimVar.PrimVar s a)
