mutable-containers-0.3.2.1: 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 Source

A primitive ByteArray reference, supporting any monad.

Since 0.2.0

Instances

Prim a => MutableRef (PRef s a) Source 
MutableContainer (PRef s a) Source 
type RefElement (PRef s a) = a Source 
type MCState (PRef s a) = s Source 

type IOPRef = PRef (PrimState IO) Source

A primitive ByteArray IO reference.

asPRef :: PRef s a -> PRef s a Source

Since 0.2.0

data URef s a Source

An unboxed vector reference, supporting any monad.

Since 0.2.0

Instances

Unbox a => MutableRef (URef s a) Source 
MutableContainer (URef s a) Source 
type RefElement (URef s a) = a Source 
type MCState (URef s a) = s Source 

type IOURef = URef (PrimState IO) Source

An unboxed IO vector reference.

asURef :: URef s a -> URef s a Source

Since 0.2.0

data SRef s a Source

A storable vector reference, supporting any monad.

Since 0.2.0

Instances

Storable a => MutableRef (SRef s a) Source 
MutableContainer (SRef s a) Source 
type RefElement (SRef s a) = a Source 
type MCState (SRef s a) = s Source 

type IOSRef = SRef (PrimState IO) Source

A storable IO vector reference.

asSRef :: SRef s a -> SRef s a Source

Since 0.2.0

data BRef s a Source

A boxed vector reference, supporting any monad.

Since 0.2.0

type IOBRef = BRef (PrimState IO) Source

A boxed IO vector reference.

asBRef :: BRef s a -> BRef s a Source

Since 0.2.0

Standard re-exports

asIORef :: IORef a -> IORef a Source

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

asSTRef :: STRef s a -> STRef s a Source

Since 0.2.0

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

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

asMutVar :: MutVar s a -> MutVar s a Source

Since 0.2.0

Collections/queues

data Deque v s a Source

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

type UDeque = Deque MVector Source

A Deque specialized to unboxed vectors.

Since 0.2.0

asUDeque :: UDeque s a -> UDeque s a Source

Since 0.2.0

type SDeque = Deque MVector Source

A Deque specialized to storable vectors.

Since 0.2.0

asSDeque :: SDeque s a -> SDeque s a Source

Since 0.2.0

type BDeque = Deque MVector Source

A Deque specialized to boxed vectors.

Since 0.2.0

asBDeque :: BDeque s a -> BDeque s a Source

Since 0.2.0

data DLList s a Source

A doubly-linked list.

Since 0.3.0

asDLList :: DLList s a -> DLList s a Source

Since 0.2.0

Type classes

class MutableContainer c Source

The parent typeclass for all mutable containers.

Since 0.2.0

Associated Types

type MCState c Source

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

Since 0.2.0

class MutableContainer c => MutableRef c where Source

Typeclass for single-cell mutable references.

Since 0.2.0

Associated Types

type RefElement c Source

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 Source

Create a new mutable reference with the given value.

Since 0.2.0

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

Read the current value in the mutable reference.

Since 0.2.0

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

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 () Source

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 () Source

Modify the value in the mutable reference, forcing the result.

Since 0.2.0

class MutableRef c => MutableAtomicRef c where Source

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 Source

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 Source

Modify the value, forcing the result.

Since 0.2.0

class MutableContainer c => MutableCollection c where Source

Containers which contain 0 or more values.

Since 0.2.0

Associated Types

type CollElement c Source

The type of each value in the collection.

Since 0.2.0

Methods

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

Create a new, empty collection.

Since 0.2.0

class MutableCollection c => MutablePushFront c where Source

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 () Source

Place a value at the front of the collection.

Since 0.2.0

class MutableCollection c => MutablePushBack c where Source

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 () Source

Place a value at the back of the collection.

Since 0.2.0

class MutableCollection c => MutablePopFront c where Source

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)) Source

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

Since 0.2.0

class MutableCollection c => MutablePopBack c where Source

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)) Source

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

Since 0.2.0

Constraint kinds

type MutableQueue c = (MutablePopFront c, MutablePushBack c) Source

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

Since 0.2.0

type MutableStack c = (MutablePopFront c, MutablePushFront c) Source

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) Source

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 (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)