base-4.18.1.0: Basic libraries

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | stable
Portability | non-portable (uses Control.Monad.ST)
Safe Haskell | Trustworthy
Language | Haskell2010

Data.STRef

Contents

- STRefs

Description

Mutable references in the (strict) ST monad.

Synopsis

- data STRef s a
- newSTRef :: a -> ST s (STRef s a)
- readSTRef :: STRef s a -> ST s a
- writeSTRef :: STRef s a -> a -> ST s ()
- modifySTRef :: STRef s a -> (a -> a) -> ST s ()
- modifySTRef' :: STRef s a -> (a -> a) -> ST s ()

# STRefs

data STRef s a Source #

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"

#### Instances

Instances details

Eq (STRef s a) Source # | Pointer equality. Since: base-2.1
Instance details Defined in GHC.STRef Methods (==) :: STRef s a -> STRef s a -> Bool Source # (/=) :: STRef s a -> STRef s a -> Bool Source #

newSTRef :: a -> ST s (STRef s a) Source #

Build a new `STRef` in the current state thread

readSTRef :: STRef s a -> ST s a Source #

Read the value of an `STRef`

writeSTRef :: STRef s a -> a -> ST s () Source #

Write a new value into an `STRef`

modifySTRef :: STRef s a -> (a -> a) -> ST s () Source #

Mutate the contents of an `STRef`.

    >>> :{
    runST (do
        ref <- newSTRef ""
        modifySTRef ref (const "world")
        modifySTRef ref (++ "!")
        modifySTRef ref ("Hello, " ++)
        readSTRef ref )
    :}
    "Hello, world!"

Be warned that `modifySTRef` does not apply the function strictly. This means if the program calls `modifySTRef` many times, but seldom uses the value, thunks will pile up in memory resulting in a space leak. This is a common mistake made when using an `STRef` as a counter. For example, the following will leak memory and may produce a stack overflow:

    >>> import Control.Monad (replicateM_)
    >>> :{
    print (runST (do
        ref <- newSTRef 0
        replicateM_ 1000 $ modifySTRef ref (+1)
        readSTRef ref ))
    :}
    1000

To avoid this problem, use `modifySTRef'` instead.

modifySTRef' :: STRef s a -> (a -> a) -> ST s () Source #

Strict version of `modifySTRef`

Since: base-4.6.0.0