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


-- | Abstactions and concrete implementations of mutable containers
--   
--   See docs and README at
--   <a>http://www.stackage.org/package/mutable-containers</a>
@package mutable-containers
@version 0.3.3


-- | Classes and concrete implementations for mutable data structures.
--   
--   For more information on the design of this library, see the README
--   file, also available at
--   <a>http://www.stackage.org/package/mutable-containers</a>.
module Data.Mutable

-- | A primitive ByteArray reference, supporting any monad.
--   
--   Since 0.2.0
data PRef s a

-- | A primitive ByteArray IO reference.
type IOPRef = PRef (PrimState IO)

-- | Since 0.2.0
asPRef :: PRef s a -> PRef s a

-- | An unboxed vector reference, supporting any monad.
--   
--   Since 0.2.0
data URef s a

-- | An unboxed IO vector reference.
type IOURef = URef (PrimState IO)

-- | Since 0.2.0
asURef :: URef s a -> URef s a

-- | A storable vector reference, supporting any monad.
--   
--   Since 0.2.0
data SRef s a

-- | A storable IO vector reference.
type IOSRef = SRef (PrimState IO)

-- | Since 0.2.0
asSRef :: SRef s a -> SRef s a

-- | A boxed vector reference, supporting any monad.
--   
--   Since 0.2.0
data BRef s a

-- | A boxed IO vector reference.
type IOBRef = BRef (PrimState IO)

-- | Since 0.2.0
asBRef :: BRef s a -> BRef s a

-- | A mutable variable in the <a>IO</a> monad
data IORef a :: * -> *

-- | Since 0.2.0
asIORef :: IORef a -> IORef a

-- | a value of type <tt>STRef s a</tt> is a mutable variable in state
--   thread <tt>s</tt>, containing a value of type <tt>a</tt>
data STRef s a :: * -> * -> *

-- | Since 0.2.0
asSTRef :: STRef s a -> STRef s a

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

-- | Since 0.2.0
asMutVar :: MutVar s a -> MutVar s a

-- | A double-ended queue supporting any underlying vector type and any
--   monad.
--   
--   This implements a circular double-ended queue with exponential growth.
--   
--   Since 0.2.0
data Deque v s a

-- | A <a>Deque</a> specialized to unboxed vectors.
--   
--   Since 0.2.0
type UDeque = Deque MVector

-- | Since 0.2.0
asUDeque :: UDeque s a -> UDeque s a

-- | A <a>Deque</a> specialized to storable vectors.
--   
--   Since 0.2.0
type SDeque = Deque MVector

-- | Since 0.2.0
asSDeque :: SDeque s a -> SDeque s a

-- | A <a>Deque</a> specialized to boxed vectors.
--   
--   Since 0.2.0
type BDeque = Deque MVector

-- | Since 0.2.0
asBDeque :: BDeque s a -> BDeque s a

-- | A doubly-linked list.
--   
--   Since 0.3.0
data DLList s a

-- | Since 0.2.0
asDLList :: DLList s a -> DLList s a

-- | The parent typeclass for all mutable containers.
--   
--   Since 0.2.0
class MutableContainer c where type MCState c where {
    type family MCState c;
}

-- | Typeclass for single-cell mutable references.
--   
--   Since 0.2.0
class MutableContainer c => MutableRef c where type RefElement c where {
    type family RefElement c;
}

-- | Create a new mutable reference with the given value.
--   
--   Since 0.2.0
newRef :: (MutableRef c, PrimMonad m, PrimState m ~ MCState c) => RefElement c -> m c

-- | Read the current value in the mutable reference.
--   
--   Since 0.2.0
readRef :: (MutableRef c, PrimMonad m, PrimState m ~ MCState c) => c -> m (RefElement c)

-- | Write a new value to the mutable reference.
--   
--   Since 0.2.0
writeRef :: (MutableRef c, PrimMonad m, PrimState m ~ MCState c) => c -> RefElement c -> m ()

-- | Modify the value in the mutable reference, without necessarily forcing
--   the result.
--   
--   Note: some implementations <i>will</i> force the result, in particular
--   <tt>PRef</tt>, <tt>SRef</tt>, and <tt>URef</tt>.
--   
--   Since 0.2.0
modifyRef :: (MutableRef c, PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> RefElement c) -> m ()

-- | Modify the value in the mutable reference, forcing the result.
--   
--   Since 0.2.0
modifyRef' :: (MutableRef c, PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> RefElement c) -> m ()

-- | <tt>MutableRef</tt>s that provide for atomic modifications of their
--   contents.
--   
--   Since 0.2.0
class MutableRef c => MutableAtomicRef c

-- | Modify the value without necessarily forcing the result.
--   
--   Since 0.2.0
atomicModifyRef :: (MutableAtomicRef c, PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> (RefElement c, a)) -> m a

-- | Modify the value, forcing the result.
--   
--   Since 0.2.0
atomicModifyRef' :: (MutableAtomicRef c, PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> (RefElement c, a)) -> m a

-- | Containers which contain 0 or more values.
--   
--   Since 0.2.0
class MutableContainer c => MutableCollection c where type CollElement c where {
    type family CollElement c;
}

-- | Create a new, empty collection.
--   
--   Since 0.2.0
newColl :: (MutableCollection c, PrimMonad m, PrimState m ~ MCState c) => m c

-- | Place a value at the front of the collection.
--   
--   Since 0.2.0
class MutableCollection c => MutablePushFront c

-- | Place a value at the front of the collection.
--   
--   Since 0.2.0
pushFront :: (MutablePushFront c, PrimMonad m, PrimState m ~ MCState c) => c -> CollElement c -> m ()

-- | Place a value at the back of the collection.
--   
--   Since 0.2.0
class MutableCollection c => MutablePushBack c

-- | Place a value at the back of the collection.
--   
--   Since 0.2.0
pushBack :: (MutablePushBack c, PrimMonad m, PrimState m ~ MCState c) => c -> CollElement c -> m ()

-- | Take a value from the front of the collection, if available.
--   
--   Since 0.2.0
class MutableCollection c => MutablePopFront c

-- | Take a value from the front of the collection, if available.
--   
--   Since 0.2.0
popFront :: (MutablePopFront c, PrimMonad m, PrimState m ~ MCState c) => c -> m (Maybe (CollElement c))

-- | Take a value from the back of the collection, if available.
--   
--   Since 0.2.0
class MutableCollection c => MutablePopBack c

-- | Take a value from the back of the collection, if available.
--   
--   Since 0.2.0
popBack :: (MutablePopBack c, PrimMonad m, PrimState m ~ MCState c) => c -> m (Maybe (CollElement c))

-- | Collections which allow pushing and popping at the front (aka FIFOs).
--   
--   Since 0.2.0
type MutableQueue c = (MutablePopFront c, MutablePushBack c)

-- | Collections which allow pushing at the back and popping at the front
--   (aka FILOs).
--   
--   Since 0.2.0
type MutableStack c = (MutablePopFront c, MutablePushFront c)

-- | Collections which allow pushing and popping at the front and back.
--   
--   Since 0.2.0
type MutableDeque c = (MutableQueue c, MutablePushFront c, MutablePopBack c)

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

-- | State token type

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

-- | Class of types supporting primitive array operations
class Prim a
class (Vector Vector a, MVector MVector a) => Unbox a

-- | The member functions of this class facilitate writing values of
--   primitive types to raw memory (which may have been allocated with the
--   above mentioned routines) and reading values from blocks of raw
--   memory. The class, furthermore, includes support for computing the
--   storage requirements and alignment restrictions of storable types.
--   
--   Memory addresses are represented as values of type <tt><a>Ptr</a>
--   a</tt>, for some <tt>a</tt> which is an instance of class
--   <a>Storable</a>. The type argument to <a>Ptr</a> helps provide some
--   valuable type safety in FFI code (you can't mix pointers of different
--   types without an explicit cast), while helping the Haskell type system
--   figure out which marshalling method is needed for a given pointer.
--   
--   All marshalling between Haskell and a foreign language ultimately
--   boils down to translating Haskell data structures into the binary
--   representation of a corresponding data structure of the foreign
--   language and vice versa. To code this marshalling in Haskell, it is
--   necessary to manipulate primitive data types stored in unstructured
--   memory blocks. The class <a>Storable</a> facilitates this manipulation
--   on all types for which it is instantiated, which are the standard
--   basic types of Haskell, the fixed size <tt>Int</tt> types
--   (<a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>), the fixed
--   size <tt>Word</tt> types (<a>Word8</a>, <a>Word16</a>, <a>Word32</a>,
--   <a>Word64</a>), <a>StablePtr</a>, all types from
--   <a>Foreign.C.Types</a>, as well as <a>Ptr</a>.
class Storable a