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

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

-- | Classes and concrete implementations for mutable data structures.
--   
--   For more information on the design of this library, see the README
--   file, also available at
--   http://www.stackage.org/package/mutable-containers.
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 IO monad.
--   
--   
--   >>> import GHC.Internal.Data.IORef
--   
--   >>> r <- newIORef 0
--   
--   >>> readIORef r
--   0
--   
--   >>> writeIORef r 1
--   
--   >>> readIORef r
--   1
--   
--   >>> atomicWriteIORef r 2
--   
--   >>> readIORef r
--   2
--   
--   >>> modifyIORef' r (+ 1)
--   
--   >>> readIORef r
--   3
--   
--   >>> atomicModifyIORef' r (\a -> (a + 1, ()))
--   
--   >>> readIORef r
--   4
--   
--   
--   See also STRef and MVar.
data IORef a

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

-- | a value of type STRef s a is a mutable variable in state
--   thread s, containing a value of type a
--   
--   
--   >>> :{
--   runST (do
--       ref <- newSTRef "hello"
--       x <- readSTRef ref
--       writeSTRef ref (x ++ "world")
--       readSTRef ref )
--   :}
--   "helloworld"
--   
data STRef s a

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

-- | A MutVar 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 :: Type -> Type -> Type) s a

-- | A Deque specialized to unboxed vectors.
--   
--   Since 0.2.0
type UDeque = Deque MVector

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

-- | A Deque specialized to storable vectors.
--   
--   Since 0.2.0
type SDeque = Deque MVector

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

-- | A Deque 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 {
    
    -- | Associated type giving the primitive state token for the given
    --   container, much like <a>PrimState</a> from primitive.
    --   
    --   Since 0.2.0
    type MCState c;
}

-- | Typeclass for single-cell mutable references.
--   
--   Since 0.2.0
class MutableContainer c => MutableRef c where {
    
    -- | Associated type giving the type of the value inside the mutable
    --   reference.
    --   
    --   Since 0.2.0
    type 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 will force the result, in particular
--   PRef, SRef, and URef.
--   
--   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 ()

-- | MutableRefs 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 {
    
    -- | The type of each value in the collection.
    --   
    --   Since 0.2.0
    type 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 :: Type -> Type)

-- | State token type.
type family PrimState (m :: Type -> Type)

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

-- | Class of types supporting primitive array operations. This includes
--   interfacing with GC-managed memory (functions suffixed with
--   ByteArray#) and interfacing with unmanaged memory (functions
--   suffixed with Addr#). Endianness is platform-dependent.
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 Ptr
--   a, for some a which is an instance of class
--   Storable. The type argument to Ptr 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 Storable facilitates this manipulation
--   on all types for which it is instantiated, which are the standard
--   basic types of Haskell, the fixed size Int types
--   (Int8, Int16, Int32, Int64), the fixed
--   size Word types (Word8, Word16, Word32,
--   Word64), StablePtr, all types from
--   Foreign.C.Types, as well as Ptr.
class Storable a
