mutable-containers-0.3.2: Abstactions and concrete implementations of mutable containers

Safe HaskellNone
LanguageHaskell2010

Data.Mutable

Contents

Description

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.

Synopsis

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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