Data.Mutable

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.

Data types

Single-cell mutable references

data PRef s a

A primitive ByteArray reference, supporting any monad.

Since 0.2.0

Instances

Prim a => MutableRef (PRef s a)

MutableContainer (PRef s a)

type RefElement (PRef s a) = a

type MCState (PRef s a) = s

type IOPRef = PRef (PrimState IO)

A primitive ByteArray IO reference.

asPRef :: PRef s a -> PRef s a

Since 0.2.0

data URef s a

An unboxed vector reference, supporting any monad.

Since 0.2.0

Instances

Unbox a => MutableRef (URef s a)

MutableContainer (URef s a)

type RefElement (URef s a) = a

type MCState (URef s a) = s

type IOURef = URef (PrimState IO)

An unboxed IO vector reference.

asURef :: URef s a -> URef s a

Since 0.2.0

data SRef s a

A storable vector reference, supporting any monad.

Since 0.2.0

Instances

Storable a => MutableRef (SRef s a)

MutableContainer (SRef s a)

type RefElement (SRef s a) = a

type MCState (SRef s a) = s

type IOSRef = SRef (PrimState IO)

A storable IO vector reference.

asSRef :: SRef s a -> SRef s a

Since 0.2.0

data BRef s a

A boxed vector reference, supporting any monad.

Since 0.2.0

Instances

IsSequence seq => MutablePushBack (BRef s seq)

IsSequence seq => MutablePopBack (BRef s seq)

IsSequence seq => MutablePushFront (BRef s seq)

IsSequence seq => MutablePopFront (BRef s seq)

Monoid w => MutableCollection (BRef s w)

MutableRef (BRef s a)

MutableContainer (BRef s a)

type CollElement (BRef s w) = Element w

type RefElement (BRef s a) = a

type MCState (BRef s a) = s

type IOBRef = BRef (PrimState IO)

A boxed IO vector reference.

asBRef :: BRef s a -> BRef s a

Since 0.2.0

Standard re-exports

data IORef a :: * -> *

A mutable variable in the IO monad

Instances

Eq (IORef a)

IsSequence a => MutablePushBack (IORef a)

IsSequence a => MutablePopBack (IORef a)

IsSequence a => MutablePushFront (IORef a)

IsSequence a => MutablePopFront (IORef a)

Monoid w => MutableCollection (IORef w)

MutableAtomicRef (IORef a)

MutableRef (IORef a)

MutableContainer (IORef a)

type CollElement (IORef w) = Element w

type RefElement (IORef a) = a

type MCState (IORef a) = PrimState IO

asIORef :: IORef a -> IORef a

Since 0.2.0

data STRef s a :: * -> * -> *

a value of type STRef s a is a mutable variable in state thread s, containing a value of type a

Instances

Eq (STRef s a)

IsSequence a => MutablePushBack (STRef s a)

IsSequence a => MutablePopBack (STRef s a)

IsSequence a => MutablePushFront (STRef s a)

IsSequence a => MutablePopFront (STRef s a)

Monoid w => MutableCollection (STRef s w)

MutableRef (STRef s a)

MutableContainer (STRef s a)

type CollElement (STRef s w) = Element w

type RefElement (STRef s a) = a

type MCState (STRef s a) = s

asSTRef :: STRef s a -> STRef s a

Since 0.2.0

data MutVar s a :: * -> * -> *

A MutVar behaves like a single-element mutable array associated with a primitive state token.

Instances

Eq (MutVar s a)

IsSequence a => MutablePushBack (MutVar s a)

IsSequence a => MutablePopBack (MutVar s a)

IsSequence a => MutablePushFront (MutVar s a)

IsSequence a => MutablePopFront (MutVar s a)

Monoid w => MutableCollection (MutVar s w)

MutableAtomicRef (MutVar s a)

MutableRef (MutVar s a)

MutableContainer (MutVar s a)

type CollElement (MutVar s w) = Element w

type RefElement (MutVar s a) = a

type MCState (MutVar s a) = s

asMutVar :: MutVar s a -> MutVar s a

Since 0.2.0

Collections/queues

data Deque v 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

Instances

MVector v a => MutablePushBack (Deque v s a)

MVector v a => MutablePopBack (Deque v s a)

MVector v a => MutablePushFront (Deque v s a)

MVector v a => MutablePopFront (Deque v s a)

MVector v a => MutableCollection (Deque v s a)

MutableContainer (Deque v s a)

type CollElement (Deque v s a) = a

type MCState (Deque v s a) = s

type UDeque = Deque MVector

A Deque specialized to unboxed vectors.

Since 0.2.0

asUDeque :: UDeque s a -> UDeque s a

Since 0.2.0

type SDeque = Deque MVector

A Deque specialized to storable vectors.

Since 0.2.0

asSDeque :: SDeque s a -> SDeque s a

Since 0.2.0

type BDeque = Deque MVector

A Deque specialized to boxed vectors.

Since 0.2.0

asBDeque :: BDeque s a -> BDeque s a

Since 0.2.0

data DLList s a

A doubly-linked list.

Since 0.3.0

Instances

MutablePushBack (DLList s a)

MutablePopBack (DLList s a)

MutablePushFront (DLList s a)

MutablePopFront (DLList s a)

MutableCollection (DLList s a)

MutableContainer (DLList s a)

type CollElement (DLList s a) = a

type MCState (DLList s a) = s

asDLList :: DLList s a -> DLList s a

Since 0.2.0

Type classes

class MutableContainer c

The parent typeclass for all mutable containers.

Since 0.2.0

Associated Types

type MCState c

Associated type giving the primitive state token for the given container, much like PrimState from primitive.

Since 0.2.0

Instances

MutableContainer (IORef a)

MutableContainer (STRef s a)

MutableContainer (MutVar s a)

MutableContainer (URef s a)

MutableContainer (SRef s a)

MutableContainer (PRef s a)

MutableContainer (BRef s a)

MutableContainer (DLList s a)

MutableContainer (Deque v s a)

class MutableContainer c => MutableRef c where

Typeclass for single-cell mutable references.

Since 0.2.0

Associated Types

type RefElement c

Associated type giving the type of the value inside the mutable reference.

Since 0.2.0

Methods

newRef :: (PrimMonad m, PrimState m ~ MCState c) => RefElement c -> m c

Create a new mutable reference with the given value.

Since 0.2.0

readRef :: (PrimMonad m, PrimState m ~ MCState c) => c -> m (RefElement c)

Read the current value in the mutable reference.

Since 0.2.0

writeRef :: (PrimMonad m, PrimState m ~ MCState c) => c -> RefElement c -> m ()

Write a new value to the mutable reference.

Since 0.2.0

modifyRef :: (PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement 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' :: (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

Instances

MutableRef (IORef a)

MutableRef (STRef s a)

MutableRef (MutVar s a)

Unbox a => MutableRef (URef s a)

Storable a => MutableRef (SRef s a)

Prim a => MutableRef (PRef s a)

MutableRef (BRef s a)

class MutableRef c => MutableAtomicRef c where

MutableRefs that provide for atomic modifications of their contents.

Since 0.2.0

Methods

atomicModifyRef :: (PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> (RefElement c, a)) -> m a

Modify the value without necessarily forcing the result.

Since 0.2.0

atomicModifyRef' :: (PrimMonad m, PrimState m ~ MCState c) => c -> (RefElement c -> (RefElement c, a)) -> m a

Modify the value, forcing the result.

Since 0.2.0

Instances

MutableAtomicRef (IORef a)

MutableAtomicRef (MutVar s a)

class MutableContainer c => MutableCollection c where

Containers which contain 0 or more values.

Since 0.2.0

Associated Types

type CollElement c

The type of each value in the collection.

Since 0.2.0

Methods

newColl :: (PrimMonad m, PrimState m ~ MCState c) => m c

Create a new, empty collection.

Since 0.2.0

Instances

Monoid w => MutableCollection (IORef w)

Monoid w => MutableCollection (STRef s w)

Monoid w => MutableCollection (MutVar s w)

Monoid w => MutableCollection (BRef s w)

MutableCollection (DLList s a)

MVector v a => MutableCollection (Deque v s a)

class MutableCollection c => MutablePushFront c where

Place a value at the front of the collection.

Since 0.2.0

Methods

pushFront :: (PrimMonad m, PrimState m ~ MCState c) => c -> CollElement c -> m ()

Place a value at the front of the collection.

Since 0.2.0

Instances

IsSequence a => MutablePushFront (IORef a)

IsSequence a => MutablePushFront (STRef s a)

IsSequence a => MutablePushFront (MutVar s a)

IsSequence seq => MutablePushFront (BRef s seq)

MutablePushFront (DLList s a)

MVector v a => MutablePushFront (Deque v s a)

class MutableCollection c => MutablePushBack c where

Place a value at the back of the collection.

Since 0.2.0

Methods

pushBack :: (PrimMonad m, PrimState m ~ MCState c) => c -> CollElement c -> m ()

Place a value at the back of the collection.

Since 0.2.0

Instances

IsSequence a => MutablePushBack (IORef a)

IsSequence a => MutablePushBack (STRef s a)

IsSequence a => MutablePushBack (MutVar s a)

IsSequence seq => MutablePushBack (BRef s seq)

MutablePushBack (DLList s a)

MVector v a => MutablePushBack (Deque v s a)

class MutableCollection c => MutablePopFront c where

Take a value from the front of the collection, if available.

Since 0.2.0

Methods

popFront :: (PrimMonad m, PrimState m ~ MCState c) => c -> m (Maybe (CollElement c))

Take a value from the front of the collection, if available.

Since 0.2.0

Instances

IsSequence a => MutablePopFront (IORef a)

IsSequence a => MutablePopFront (STRef s a)

IsSequence a => MutablePopFront (MutVar s a)

IsSequence seq => MutablePopFront (BRef s seq)

MutablePopFront (DLList s a)

MVector v a => MutablePopFront (Deque v s a)

class MutableCollection c => MutablePopBack c where

Take a value from the back of the collection, if available.

Since 0.2.0

Methods

popBack :: (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

Instances

IsSequence a => MutablePopBack (IORef a)

IsSequence a => MutablePopBack (STRef s a)

IsSequence a => MutablePopBack (MutVar s a)

IsSequence seq => MutablePopBack (BRef s seq)

MutablePopBack (DLList s a)

MVector v a => MutablePopBack (Deque v s a)

Constraint kinds

type MutableQueue c = (MutablePopFront c, MutablePushBack c)

Collections which allow pushing and popping at the front (aka FIFOs).

Since 0.2.0

type MutableStack c = (MutablePopFront c, MutablePushFront c)

Collections which allow pushing at the back and popping at the front (aka FILOs).

Since 0.2.0

type MutableDeque c = (MutableQueue c, MutablePushFront c, MutablePopBack c)

Collections which allow pushing and popping at the front and back.

Since 0.2.0

Convenience re-exports

class Monad m => PrimMonad m

Class of monads which can perform primitive state-transformer actions

Minimal complete definition

primitive

Associated Types

type PrimState m :: *

State token type

Instances

PrimMonad IO

PrimMonad (ST s)

PrimMonad m => PrimMonad (IdentityT m)

PrimMonad m => PrimMonad (ListT m)

PrimMonad m => PrimMonad (MaybeT m)

PrimMonad m => PrimMonad (ReaderT r m)

PrimMonad m => PrimMonad (StateT s m)

PrimMonad m => PrimMonad (StateT s m)

PrimMonad m => PrimMonad (ExceptT e m)

(Error e, PrimMonad m) => PrimMonad (ErrorT e m)

(Monoid w, PrimMonad m) => PrimMonad (WriterT w m)

(Monoid w, PrimMonad m) => PrimMonad (WriterT w m)

(Monoid w, PrimMonad m) => PrimMonad (RWST r w s m)

(Monoid w, PrimMonad m) => PrimMonad (RWST r w s m)

type family PrimState m :: *

State token type

Instances

type PrimState IO = RealWorld

type PrimState (ST s) = s

type PrimState (IdentityT m) = PrimState m

type PrimState (ListT m) = PrimState m

type PrimState (MaybeT m) = PrimState m

type PrimState (ReaderT r m) = PrimState m

type PrimState (StateT s m) = PrimState m

type PrimState (StateT s m) = PrimState m

type PrimState (ExceptT e m) = PrimState m

type PrimState (ErrorT e m) = PrimState m

type PrimState (WriterT w m) = PrimState m

type PrimState (WriterT w m) = PrimState m

type PrimState (RWST r w s m) = PrimState m

type PrimState (RWST r w s m) = PrimState m

data RealWorld :: *

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

class Prim a

Class of types supporting primitive array operations

Minimal complete definition

sizeOf#, alignment#, indexByteArray#, readByteArray#, writeByteArray#, setByteArray#, indexOffAddr#, readOffAddr#, writeOffAddr#, setOffAddr#

Instances

Prim Char

Prim Double

Prim Float

Prim Int

Prim Int8

Prim Int16

Prim Int32

Prim Int64

Prim Word

Prim Word8

Prim Word16

Prim Word32

Prim Word64

Prim Addr

class (Vector Vector a, MVector MVector a) => Unbox a

Instances

Unbox Bool

Unbox Char

Unbox Double

Unbox Float

Unbox Int

Unbox Int8

Unbox Int16

Unbox Int32

Unbox Int64

Unbox Word

Unbox Word8

Unbox Word16

Unbox Word32

Unbox Word64

Unbox ()

(RealFloat a, Unbox a) => Unbox (Complex a)

(Unbox a, Unbox b) => Unbox (a, b)

(Unbox a, Unbox b, Unbox c) => Unbox (a, b, c)

(Unbox a, Unbox b, Unbox c, Unbox d) => Unbox (a, b, c, d)

(Unbox a, Unbox b, Unbox c, Unbox d, Unbox e) => Unbox (a, b, c, d, e)

(Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f) => Unbox (a, b, c, d, e, f)

class Storable 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.

Minimal complete definition

sizeOf, alignment, (peek | peekElemOff | peekByteOff), (poke | pokeElemOff | pokeByteOff)

Instances

Storable Bool

Storable Char

Storable Double

Storable Float

Storable Int

Storable Int8

Storable Int16

Storable Int32

Storable Int64

Storable Word

Storable Word8

Storable Word16

Storable Word32

Storable Word64

Storable Fingerprint

(Storable a, Integral a) => Storable (Ratio a)

Storable (StablePtr a)

Storable (Ptr a)

Storable (FunPtr a)

Storable a => Storable (Complex a)