Cardano.Prelude

Spawn an asynchronous action in a separate thread.

Like for forkIO, the action may be left running unintentionally (see module-level documentation for details).

Use withAsync style functions wherever you can instead!

Like async but using forkOS internally.

Like async but using forkOn internally.

Cancel an asynchronous action by throwing the AsyncCancelled exception to it, and waiting for the Async thread to quit. Has no effect if the Async has already completed.

cancel a = throwTo (asyncThreadId a) AsyncCancelled <* waitCatch a

Note that cancel will not terminate until the thread the Async refers to has terminated. This means that cancel will block for as long said thread blocks when receiving an asynchronous exception.

For example, it could block if:

• It's executing a foreign call, and thus cannot receive the asynchronous exception;

• It's executing some cleanup handler after having received the exception, and the handler is blocking.

Cancel an asynchronous action by throwing the supplied exception to it.

cancelWith a x = throwTo (asyncThreadId a) x

The notes about the synchronous nature of cancel also apply to cancelWith.

Run two IO actions concurrently, and return both results. If either action throws an exception at any time, then the other action is cancelled, and the exception is re-thrown by concurrently.

concurrently left right =
  withAsync left $ \a ->
  withAsync right $ \b ->
  waitBoth a b

To run more than two actions concurrently, see mapConcurrently.

Link the given Async to the current thread, such that if the Async raises an exception, that exception will be re-thrown in the current thread, wrapped in ExceptionInLinkedThread.

link ignores AsyncCancelled exceptions thrown in the other thread, so that it's safe to cancel a thread you're linked to. If you want different behaviour, use linkOnly.

Link two Asyncs together, such that if either raises an exception, the same exception is re-thrown in the other Async, wrapped in ExceptionInLinkedThread.

link2 ignores AsyncCancelled exceptions, so that it's possible to cancel either thread without cancelling the other. If you want different behaviour, use link2Only.

Check whether an Async has completed yet. If it has not completed yet, then the result is Nothing, otherwise the result is Just e where e is Left x if the Async raised an exception x, or Right a if it returned a value a.

poll = atomically . pollSTM

Run two IO actions concurrently, and return the first to finish. The loser of the race is cancelled.

race left right =
  withAsync left $ \a ->
  withAsync right $ \b ->
  waitEither a b

Like race, but the result is ignored.

Wait for an asynchronous action to complete, and return its value. If the asynchronous action threw an exception, then the exception is re-thrown by wait.

wait = atomically . waitSTM

Wait for any of the supplied Asyncs to complete. If the first to complete throws an exception, then that exception is re-thrown by waitAny. The input list must be non-empty.

If multiple Asyncs complete or have completed, then the value returned corresponds to the first completed Async in the list.

Like waitAny, but also cancels the other asynchronous operations as soon as one has completed.

Wait for any of the supplied asynchronous operations to complete. The value returned is a pair of the Async that completed, and the result that would be returned by wait on that Async. The input list must be non-empty.

If multiple Asyncs complete or have completed, then the value returned corresponds to the first completed Async in the list.

Like waitAnyCatch, but also cancels the other asynchronous operations as soon as one has completed.

Waits for both Asyncs to finish, but if either of them throws an exception before they have both finished, then the exception is re-thrown by waitBoth.

Wait for an asynchronous action to complete, and return either Left e if the action raised an exception e, or Right a if it returned a value a.

waitCatch = atomically . waitCatchSTM

Wait for the first of two Asyncs to finish. If the Async that finished first raised an exception, then the exception is re-thrown by waitEither.

Like waitEither, but also cancels both Asyncs before returning.

Wait for the first of two Asyncs to finish.

Like waitEitherCatch, but also cancels both Asyncs before returning.

Like waitEither, but the result is ignored.

Spawn an asynchronous action in a separate thread, and pass its Async handle to the supplied function. When the function returns or throws an exception, uninterruptibleCancel is called on the Async.

withAsync action inner = mask $ \restore -> do
  a <- async (restore action)
  restore (inner a) `finally` uninterruptibleCancel a

This is a useful variant of async that ensures an Async is never left running unintentionally.

Note: a reference to the child thread is kept alive until the call to withAsync returns, so nesting many withAsync calls requires linear memory.

Like withAsync but uses forkOS internally.

Like withAsync but uses forkOn internally.

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

Fork a thread and call the supplied function when the thread is about to terminate, with an exception or a returned value. The function is called with asynchronous exceptions masked.

forkFinally action and_then =
  mask $ \restore ->
    forkIO $ try (restore action) >>= and_then

This function is useful for informing the parent when a child terminates, for example.

Block the current thread until data is available to read on the given file descriptor (GHC only).

This will throw an IOError if the file descriptor was closed while this thread was blocked. To safely close a file descriptor that has been used with threadWaitRead, use closeFdWith.

Returns an STM action that can be used to wait for data to read from a file descriptor. The second returned value is an IO action that can be used to deregister interest in the file descriptor.

Block the current thread until data can be written to the given file descriptor (GHC only).

This will throw an IOError if the file descriptor was closed while this thread was blocked. To safely close a file descriptor that has been used with threadWaitWrite, use closeFdWith.

Returns an STM action that can be used to wait until data can be written to a file descriptor. The second returned value is an IO action that can be used to deregister interest in the file descriptor.

Convert a single digit Char to the corresponding Int. This function fails unless its argument satisfies isHexDigit, but recognises both upper- and lower-case hexadecimal digits (that is, '0'..'9', 'a'..'f', 'A'..'F').

Examples

Characters '0' through '9' are converted properly to 0..9:

>>> map digitToInt ['0'..'9'][0,1,2,3,4,5,6,7,8,9]

Both upper- and lower-case 'A' through 'F' are converted as well, to 10..15.

>>> map digitToInt ['a'..'f'][10,11,12,13,14,15]>>> map digitToInt ['A'..'F'][10,11,12,13,14,15]

Anything else throws an exception:

>>> digitToInt 'G'*** Exception: Char.digitToInt: not a digit 'G'>>> digitToInt '♥'*** Exception: Char.digitToInt: not a digit '\9829'

Selects alphabetic Unicode characters (lower-case, upper-case and title-case letters, plus letters of caseless scripts and modifiers letters). This function is equivalent to isAlpha.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• UppercaseLetter

• LowercaseLetter

• TitlecaseLetter

• ModifierLetter

• OtherLetter

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Letter".

Examples

Basic usage:

>>> isLetter 'a'True>>> isLetter 'A'True>>> isLetter 'λ'True>>> isLetter '0'False>>> isLetter '%'False>>> isLetter '♥'False>>> isLetter '\31'False

Ensure that isLetter and isAlpha are equivalent.

>>> let chars = [(chr 0)..]>>> let letters = map isLetter chars>>> let alphas = map isAlpha chars>>> letters == alphasTrue

Selects Unicode mark characters, for example accents and the like, which combine with preceding characters.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• NonSpacingMark

• SpacingCombiningMark

• EnclosingMark

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Mark".

Examples

Basic usage:

>>> isMark 'a'False>>> isMark '0'False

Combining marks such as accent characters usually need to follow another character before they become printable:

>>> map isMark "ò"[False,True]

Puns are not necessarily supported:

>>> isMark '✓'False

Selects Unicode numeric characters, including digits from various scripts, Roman numerals, et cetera.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• DecimalNumber

• LetterNumber

• OtherNumber

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Number".

Examples

Basic usage:

>>> isNumber 'a'False>>> isNumber '%'False>>> isNumber '3'True

ASCII '0' through '9' are all numbers:

>>> and $ map isNumber ['0'..'9']True

Unicode Roman numerals are "numbers" as well:

>>> isNumber 'Ⅸ'True

Selects Unicode space and separator characters.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• Space

• LineSeparator

• ParagraphSeparator

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Separator".

Examples

Basic usage:

>>> isSeparator 'a'False>>> isSeparator '6'False>>> isSeparator ' 'True

Warning: newlines and tab characters are not considered separators.

>>> isSeparator '\n'False>>> isSeparator '\t'False

But some more exotic characters are (like HTML's  ):

>>> isSeparator '\160'True

nonEmpty efficiently turns a normal list into a NonEmpty stream, producing Nothing if the input is empty.

This lets you use a difference list of a Semigroup as a Monoid.

Examples

>>> let hello = diff "Hello, "

>>> appEndo hello "World!""Hello, World!"

>>> appEndo (hello <> mempty) "World!""Hello, World!"

>>> appEndo (mempty <> hello) "World!""Hello, World!"

>>> let world = diff "World">>> let excl = diff "!"

>>> appEndo (hello <> (world <> excl)) mempty"Hello, World!"

>>> appEndo ((hello <> world) <> excl) mempty"Hello, World!"

Rename id to identity to allow id as a variable name

We can pass several things here, as long as they have length.

Explicit output with Text since that is what we want most of the time. We don't want to look at the type errors or warnings arising.

The && operator lifted to a monad. If the first argument evaluates to False the second argument will not be evaluated.

&& lifted to an Applicative. Unlike &&^ the operator is not short-circuiting.

|| lifted to an Applicative. Unlike ||^ the operator is not short-circuiting.

The || operator lifted to a monad. If the first argument evaluates to True the second argument will not be evaluated.

Convert a Buildable error into an aeson parser error

Convert a Buildable error into a cborg decoder error

A helper for lifting unless to MonadError

By using this function infix we can move error handling to the end of a Bool expression, hopefully improving readability.

Convert an Either-encoded error to an aeson parser error

Convert an Either-encoded failure to a cborg decoder failure

A helper for lifting an Either to a MonadError

By using this function infix we can move the error handling to the end of an expression, hopefully improving readability.

A Builder for a ByteString that performs base 16 encoding

A Format for a ByteString that performs base 16 encoding

A Format for Foldable containers that outputs a JSON-style list

A Format similar to listJson that prints each value on a new line with indent spaces of indentation

A Format for Exts.IsList containers of Buildable key-value pairs that outputs a JSON-style colon-separated map

A Builder for a pair of Buildable values (a, b)

A Format for a pair of Buildable values (a, b)

The function isNormalForm checks whether its argument is fully evaluated and deeply evaluated.

NOTE: The normal form check can be quite brittle, especially with -O0. For example, writing something like

let !(Value x) = ... in ....

might translate to

let !.. = ... in ... (case ... of Value x -> x)

which would trivially be False. In general, isNormalForm should probably only be used with -O1, but even then the answer may still depend on internal decisions made by ghc during compilation.

Compute the size of the given closure

This is a wrapper around computeHeapSize' which sets some defaults for the capacity of worklist and the visited set: it uses a worklist capacity of 10k (which, assuming balanced data structures, should be more than enough), an initial visited set capacity of 250k, and a maximum visited set capacity of 16M. This means that this will use between 2 MB and 128 MB of heaps space.

It also does NOT perform GC before counting, for improved performance. Client code can call performMajorGC manually or use computeHeapSize'.

Should these limits not be sufficient, or conversely, the memory requirements be too large, use computeHeapSize' directly.

Compute the size of the given closure

The size of the worklist should be set to the maximum expected depth of the closure; the size of the visited set should be set to the maximum /number of nodes/ in the closure.

computeHeapSizeWorkList can be used to estimate the size of the worklist required.

Upper bound on the required work list size to compute closure size

NOTE: This ignores sharing, and so provides an upper bound only.

The size of a closure with no nested pointers can be computed without any stack space.

When we have a closure with (N + 1) nested pointers

p0 p1 .. pN

We will

• Push pN, .., p1, p0 onto the stack

• Pop off p0 and count its children

• Pop off p1 and count its children

• ..

until we have processed all children. This means that the stack space required will be the maximum of

[ N + 1 -- For the initial list
, requiredWorkList p0 + (N + 1) - 1
, requiredWorkList p1 + (N + 1) - 2
, ..
, requiredWorkList pN + (N + 1) - (N + 1)
]

For example, for a list, we would get that

requiredWorkList []     == 0
requiredWorkList (x:xs) == max [ 2
                               , requiredWorkList x + 1
                               , requiredWorkList xs
                               ]

which, for a list of Int (which requires only a stack of size 1), equals 2 (unless the list is empty).

Similarly, for binary trees, we get

requiredWorkList Leaf           == 0
requiredWorkList (Branch l x r) == max [ 3
                                       , requiredWorkList l + 2
                                       , requiredWorkList x + 1
                                       , requiredWorkList r
                                       ]

which, for a tree of Int, is bound by (height * 2) + 1.

Given a Haskell expression, build a Tree which reflects its heap object representation and render it as Text.

Given a Haskell expression, build a Tree which reflects its heap object representation.

Attempt to parse a value of type a from the body of a JSString using parser

Force all of the elements of a Foldable to weak head normal form.

In order to ensure that all of the elements of a Foldable are strict, we can simply foldMap over it and seq each value with (). However, ()'s mappend implementation is actually completely lazy: _ <> _ = () So, in order to work around this, we instead utilize this newly defined StrictUnit whose mappend implementation is specifically strict.

The deep analogue of $!. f $!! x fully evaluates x before returning f x.

There is no guarantee about the ordering of evaluation. f x may be evaluated before x is fully evaluated. To impose an actual order on evaluation, use pseq from Control.Parallel in the parallel package.

A variant of deepseq that is useful in some circumstances:

force x = x `deepseq` x

force x fully evaluates x, and then returns it. Note that force x only performs evaluation when the value of force x itself is demanded, so essentially it turns shallow evaluation into deep evaluation.

force can be conveniently used in combination with ViewPatterns:

{-# LANGUAGE BangPatterns, ViewPatterns #-}
import Control.DeepSeq

someFun :: ComplexData -> SomeResult
someFun (force -> !arg) = {- 'arg' will be fully evaluated -}

Another useful application is to combine force with evaluate in order to force deep evaluation relative to other IO operations:

import Control.Exception (evaluate)
import Control.DeepSeq

main = do
  result <- evaluate $ force $ pureComputation
  {- 'result' will be fully evaluated at this point -}
  return ()

Finally, here's an exception safe variant of the readFile' example:

readFile' :: FilePath -> IO String
readFile' fn = bracket (openFile fn ReadMode) hClose $ \h ->
                       evaluate . force =<< hGetContents h

A version of concatMap that works with a monadic predicate.

($) is the function application operator.

Applying ($) to a function f and an argument x gives the same result as applying f to x directly. The definition is akin to this:

($) :: (a -> b) -> a -> b
($) f x = f x

This is id specialized from a -> a to (a -> b) -> (a -> b) which by the associativity of (->) is the same as (a -> b) -> a -> b.

On the face of it, this may appear pointless! But it's actually one of the most useful and important operators in Haskell.

The order of operations is very different between ($) and normal function application. Normal function application has precedence 10 - higher than any operator - and associates to the left. So these two definitions are equivalent:

expr = min 5 1 + 5
expr = ((min 5) 1) + 5

($) has precedence 0 (the lowest) and associates to the right, so these are equivalent:

expr = min 5 $ 1 + 5
expr = (min 5) (1 + 5)

Examples

A common use cases of ($) is to avoid parentheses in complex expressions.

For example, instead of using nested parentheses in the following Haskell function:

-- | Sum numbers in a string: strSum "100  5 -7" == 98
strSum :: String -> Int
strSum s = sum (mapMaybe readMaybe (words s))

we can deploy the function application operator:

-- | Sum numbers in a string: strSum "100  5 -7" == 98
strSum :: String -> Int
strSum s = sum $ mapMaybe readMaybe $ words s

($) is also used as a section (a partially applied operator), in order to indicate that we wish to apply some yet-unspecified function to a given value. For example, to apply the argument 5 to a list of functions:

applyFive :: [Int]
applyFive = map ($ 5) [(+1), (2^)]
>>> [6, 32]

Technical Remark (Representation Polymorphism)

($) is fully representation-polymorphic. This allows it to also be used with arguments of unlifted and even unboxed kinds, such as unboxed integers:

fastMod :: Int -> Int -> Int
fastMod (I# x) (I# m) = I# $ remInt# x m

Strict (call-by-value) application operator. It takes a function and an argument, evaluates the argument to weak head normal form (WHNF), then calls the function with that value.

(++) appends two lists, i.e.,

[x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
[x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]

If the first list is not finite, the result is the first list.

Performance considerations

This function takes linear time in the number of elements of the first list. Thus it is better to associate repeated applications of (++) to the right (which is the default behaviour): xs ++ (ys ++ zs) or simply xs ++ ys ++ zs, but not (xs ++ ys) ++ zs. For the same reason GHC.Internal.Data.List.concat = GHC.Internal.Data.List.foldr (++) [] has linear performance, while GHC.Internal.Data.List.foldl (++) [] is prone to quadratic slowdown

Examples

>>> [1, 2, 3] ++ [4, 5, 6][1,2,3,4,5,6]

>>> [] ++ [1, 2, 3][1,2,3]

>>> [3, 2, 1] ++ [][3,2,1]

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Same as >>=, but with the arguments interchanged.

as >>= f == f =<< as

Since Void values logically don't exist, this witnesses the logical reasoning tool of "ex falso quodlibet".

>>> let x :: Either Void Int; x = Right 5>>> :{case x of    Right r -> r    Left l  -> absurd l:}5

In many situations, the liftM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftM<n> f x1 x2 ... xn

Examples

>>> pure (\x y z -> x + y * z) `ap` Just 1 `ap` Just 5 `ap` Just 10Just 51

const x y always evaluates to x, ignoring its second argument.

const x = \_ -> x

This function might seem useless at first glance, but it can be very useful in a higher order context.

Examples

>>> const 42 "hello"42

>>> map (const 42) [0..3][42,42,42,42]

flip f takes its (first) two arguments in the reverse order of f.

prop> flip f x y = f y x

prop> flip . flip = id

Examples

>>> flip (++) "hello" "world""worldhello"

>>> let (.>) = flip (.) in (+1) .> show $ 5"6"

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

>>> join [[1, 2, 3], [4, 5, 6], [7, 8, 9]][1,2,3,4,5,6,7,8,9]

>>> join (Just (Just 3))Just 3

A common use of join is to run an IO computation returned from an GHC.Conc.STM transaction, since GHC.Conc.STM transactions can't perform IO directly. Recall that

GHC.Internal.Conc.atomically :: STM a -> IO a

is used to run GHC.Conc.STM transactions atomically. So, by specializing the types of GHC.Internal.Conc.atomically and join to

GHC.Internal.Conc.atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

we can compose them as

join . GHC.Internal.Conc.atomically :: STM (IO b) -> IO b

to run an GHC.Conc.STM transaction and the IO action it returns.

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

Promote a function to a monad. This is equivalent to fmap but specialised to Monads.

Promote a function to a monad, scanning the monadic arguments from left to right.

Examples

>>> liftM2 (+) [0,1] [0,2][0,2,1,3]

>>> liftM2 (+) (Just 1) NothingNothing

>>> liftM2 (+) (+ 3) (* 2) 518

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

The Prelude.fromEnum method restricted to the type Char.

otherwise is defined as the value True. It helps to make guards more readable. eg.

 f x | x < 0     = ...
     | otherwise = ...

If Void is uninhabited then any Functor that holds only values of type Void is holding no values. It is implemented in terms of fmap absurd.

Conditional execution of Applicative expressions. For example,

Examples

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

>>> putStr "pi:" >> when False (print 3.14159)pi:

Default implementation for bit.

Note that: bitDefault i = 1 shiftL i

Default implementation for popCount.

This implementation is intentionally naive. Instances are expected to provide an optimized implementation for their size.

Default implementation for testBit.

Note that: testBitDefault x i = (x .&. bit i) /= 0

Attempt to convert an Integral type a to an Integral type b using the size of the types as measured by Bits methods.

A simpler version of this function is:

toIntegral :: (Integral a, Integral b) => a -> Maybe b
toIntegral x
  | toInteger x == toInteger y = Just y
  | otherwise                  = Nothing
  where
    y = fromIntegral x

This version requires going through Integer, which can be inefficient. However, toIntegralSized is optimized to allow GHC to statically determine the relative type sizes (as measured by bitSizeMaybe and isSigned) and avoid going through Integer for many types. (The implementation uses fromIntegral, which is itself optimized with rules for base types but may go through Integer for some type pairs.)

The Prelude.toEnum method restricted to the type Char.

Boolean "and", lazy in the second argument

Boolean "not"

Boolean "or", lazy in the second argument

Like forkIO, this sparks off a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread.

However, forkOS creates a bound thread, which is necessary if you need to call foreign (non-Haskell) libraries that make use of thread-local state, such as OpenGL (see Control.Concurrent#boundthreads).

Using forkOS instead of forkIO makes no difference at all to the scheduling behaviour of the Haskell runtime system. It is a common misconception that you need to use forkOS instead of forkIO to avoid blocking all the Haskell threads when making a foreign call; this isn't the case. To allow foreign calls to be made without blocking all the Haskell threads (with GHC), it is only necessary to use the -threaded option when linking your program, and to make sure the foreign import is not marked unsafe.

Like forkIOWithUnmask, but the child thread is a bound thread, as with forkOS.

Returns True if the calling thread is bound, that is, if it is safe to use foreign libraries that rely on thread-local state from the calling thread.

True if bound threads are supported. If rtsSupportsBoundThreads is False, isCurrentThreadBound will always return False and both forkOS and runInBoundThread will fail.

Run the IO computation passed as the first argument. If the calling thread is not bound, a bound thread is created temporarily. runInBoundThread doesn't finish until the IO computation finishes.

You can wrap a series of foreign function calls that rely on thread-local state with runInBoundThread so that you can use them without knowing whether the current thread is bound.

Run the IO computation passed as the first argument. If the calling thread is bound, an unbound thread is created temporarily using forkIO. runInBoundThread doesn't finish until the IO computation finishes.

Use this function only in the rare case that you have actually observed a performance loss due to the use of bound threads. A program that doesn't need its main thread to be bound and makes heavy use of concurrency (e.g. a web server), might want to wrap its main action in runInUnboundThread.

Note that exceptions which are thrown to the current thread are thrown in turn to the thread that is executing the given computation. This ensures there's always a way of killing the forked thread.

Suspends the current thread for a given number of microseconds (GHC only).

There is no guarantee that the thread will be rescheduled promptly when the delay has expired, but the thread will never continue to run earlier than specified.

Be careful not to exceed maxBound :: Int, which on 32-bit machines is only 2147483647 μs, less than 36 minutes. Consider using Control.Concurrent.Thread.Delay.delay from unbounded-delays package.

Perform a series of STM actions atomically.

Using atomically inside an unsafePerformIO or unsafeInterleaveIO subverts some of guarantees that STM provides. It makes it possible to run a transaction inside of another transaction, depending on when the thunk is evaluated. If a nested transaction is attempted, an exception is thrown by the runtime. It is possible to safely use atomically inside unsafePerformIO or unsafeInterleaveIO, but the typechecker does not rule out programs that may attempt nested transactions, meaning that the programmer must take special care to prevent these.

However, there are functions for creating transactional variables that can always be safely called in unsafePerformIO. See: newTVarIO, newTChanIO, newBroadcastTChanIO, newTQueueIO, newTBQueueIO, and newTMVarIO.

Using unsafePerformIO inside of atomically is also dangerous but for different reasons. See unsafeIOToSTM for more on this.

Exception handling within STM actions.

catchSTM m f catches any exception thrown by m using throwSTM, using the function f to handle the exception. If an exception is thrown, any changes made by m are rolled back, but changes prior to m persist.

Creates a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread.

The new thread will be a lightweight, unbound thread. Foreign calls made by this thread are not guaranteed to be made by any particular OS thread; if you need foreign calls to be made by a particular OS thread, then use forkOS instead.

The new thread inherits the masked state of the parent (see GHC.Control.Exception.mask).

The newly created thread has an exception handler that discards the exceptions BlockedIndefinitelyOnMVar, BlockedIndefinitelyOnSTM, and ThreadKilled, and passes all other exceptions to the uncaught exception handler.

WARNING: Exceptions in the new thread will not be rethrown in the thread that created it. This means that you might be completely unaware of the problem if/when this happens. You may want to use the async library instead.

Like forkIO, but the child thread is passed a function that can be used to unmask asynchronous exceptions. This function is typically used in the following way

 ... mask_ $ forkIOWithUnmask $ \unmask ->
                catch (unmask ...) handler

so that the exception handler in the child thread is established with asynchronous exceptions masked, meanwhile the main body of the child thread is executed in the unmasked state.

Note that the unmask function passed to the child thread should only be used in that thread; the behaviour is undefined if it is invoked in a different thread.

Like forkIO, but lets you specify on which capability the thread should run. Unlike a forkIO thread, a thread created by forkOn will stay on the same capability for its entire lifetime (forkIO threads can migrate between capabilities according to the scheduling policy). forkOn is useful for overriding the scheduling policy when you know in advance how best to distribute the threads.

The Int argument specifies a capability number (see getNumCapabilities). Typically capabilities correspond to physical processors, but the exact behaviour is implementation-dependent. The value passed to forkOn is interpreted modulo the total number of capabilities as returned by getNumCapabilities.

GHC note: the number of capabilities is specified by the +RTS -N option when the program is started. Capabilities can be fixed to actual processor cores with +RTS -qa if the underlying operating system supports that, although in practice this is usually unnecessary (and may actually degrade performance in some cases - experimentation is recommended).

Like forkIOWithUnmask, but the child thread is pinned to the given CPU, as with forkOn.

Returns the number of Haskell threads that can run truly simultaneously (on separate physical processors) at any given time. To change this value, use setNumCapabilities.

killThread raises the ThreadKilled exception in the given thread (GHC only).

killThread tid = throwTo tid ThreadKilled

Make a weak pointer to a ThreadId. It can be important to do this if you want to hold a reference to a ThreadId while still allowing the thread to receive the BlockedIndefinitely family of exceptions (e.g. BlockedIndefinitelyOnMVar). Holding a normal ThreadId reference will prevent the delivery of BlockedIndefinitely exceptions because the reference could be used as the target of throwTo at any time, which would unblock the thread.

Holding a Weak ThreadId, on the other hand, will not prevent the thread from receiving BlockedIndefinitely exceptions. It is still possible to throw an exception to a Weak ThreadId, but the caller must use deRefWeak first to determine whether the thread still exists.

Returns the ThreadId of the calling thread (GHC only).

Compose two alternative STM actions (GHC only).

If the first action completes without retrying then it forms the result of the orElse. Otherwise, if the first action retries, then the second action is tried in its place. If both actions retry then the orElse as a whole retries.

Retry execution of the current memory transaction because it has seen values in TVars which mean that it should not continue (e.g. the TVars represent a shared buffer that is now empty). The implementation may block the thread until one of the TVars that it has read from has been updated. (GHC only)

Set the number of Haskell threads that can run truly simultaneously (on separate physical processors) at any given time. The number passed to forkOn is interpreted modulo this value. The initial value is given by the +RTS -N runtime flag.

This is also the number of threads that will participate in parallel garbage collection. It is strongly recommended that the number of capabilities is not set larger than the number of physical processor cores, and it may often be beneficial to leave one or more cores free to avoid contention with other processes in the machine.

Returns the number of the capability on which the thread is currently running, and a boolean indicating whether the thread is locked to that capability or not. A thread is locked to a capability if it was created with forkOn.

A variant of throw that can only be used within the STM monad.

Throwing an exception in STM aborts the transaction and propagates the exception. If the exception is caught via catchSTM, only the changes enclosed by the catch are rolled back; changes made outside of catchSTM persist.

If the exception is not caught inside of the STM, it is re-thrown by atomically, and the entire STM is rolled back.

Although throwSTM has a type that is an instance of the type of throw, the two functions are subtly different:

throw e    `seq` x  ===> throw e
throwSTM e `seq` x  ===> x

The first example will cause the exception e to be raised, whereas the second one won't. In fact, throwSTM will only cause an exception to be raised when it is used within the STM monad. The throwSTM variant should be used in preference to throw to raise an exception within the STM monad because it guarantees ordering with respect to other STM operations, whereas throw does not.

The yield action allows (forces, in a co-operative multitasking implementation) a context-switch to any other currently runnable threads (if any), and is occasionally useful when implementing concurrency abstractions.

Right-to-left composition. This is a synonym for (.), but it can be useful to make the order of composition more apparent.

Left-to-right composition. This is useful if you want to write a morphism as a pipeline going from left to right.

Make a Weak pointer to an MVar, using the second argument as a finalizer to run when the MVar is garbage-collected

A slight variation on modifyMVar_ that allows a value to be returned (b) in addition to the modified value of the MVar.

Like modifyMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

Like modifyMVar_, but the IO action in the second argument is executed with asynchronous exceptions masked.

An exception-safe wrapper for modifying the contents of an MVar. Like withMVar, modifyMVar will replace the original contents of the MVar if an exception is raised during the operation. This function is only atomic if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time modifyMVar_ gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

Take a value from an MVar, put a new value into the MVar and return the value taken. This function is atomic only if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time swapMVar gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

withMVar is an exception-safe wrapper for operating on the contents of an MVar. This operation is exception-safe: it will replace the original contents of the MVar if an exception is raised (see Control.Exception). However, it is only atomic if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time withMVar gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

Like withMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

When invoked inside mask, this function allows a masked asynchronous exception to be raised, if one exists. It is equivalent to performing an interruptible operation (see #interruptible), but does not involve any actual blocking.

When called outside mask, or inside uninterruptibleMask, this function has no effect.

Sometimes you want to catch two different sorts of exception. You could do something like

f = expr `catch` \ (ex :: ArithException) -> handleArith ex
         `catch` \ (ex :: IOException)    -> handleIO    ex

However, there are a couple of problems with this approach. The first is that having two exception handlers is inefficient. However, the more serious issue is that the second exception handler will catch exceptions in the first, e.g. in the example above, if handleArith throws an IOException then the second exception handler will catch it.

Instead, we provide a function catches, which would be used thus:

f = expr `catches` [Handler (\ (ex :: ArithException) -> handleArith ex),
                    Handler (\ (ex :: IOException)    -> handleIO    ex)]

When you want to acquire a resource, do some work with it, and then release the resource, it is a good idea to use bracket, because bracket will install the necessary exception handler to release the resource in the event that an exception is raised during the computation. If an exception is raised, then bracket will re-raise the exception (after performing the release).

A common example is opening a file:

bracket
  (openFile "filename" ReadMode)
  (hClose)
  (\fileHandle -> do { ... })

The arguments to bracket are in this order so that we can partially apply it, e.g.:

withFile name mode = bracket (openFile name mode) hClose

Bracket wraps the release action with mask, which is sufficient to ensure that the release action executes to completion when it does not invoke any interruptible actions, even in the presence of asynchronous exceptions. For example, hClose is uninterruptible when it is not racing other uses of the handle. Similarly, closing a socket (from "network" package) is also uninterruptible under similar conditions. An example of an interruptible action is killThread. Completion of interruptible release actions can be ensured by wrapping them in uninterruptibleMask_, but this risks making the program non-responsive to Control-C, or timeouts. Another option is to run the release action asynchronously in its own thread:

void $ uninterruptibleMask_ $ forkIO $ do { ... }

The resource will be released as soon as possible, but the thread that invoked bracket will not block in an uninterruptible state.

Like bracket, but only performs the final action if there was an exception raised by the in-between computation.

A variant of bracket where the return value from the first computation is not required.

The function catchJust is like catch, but it takes an extra argument which is an exception predicate, a function which selects which type of exceptions we're interested in.

catchJust (\e -> if isDoesNotExistErrorType (ioeGetErrorType e) then Just () else Nothing)
          (readFile f)
          (\_ -> do hPutStrLn stderr ("No such file: " ++ show f)
                    return "")

Any other exceptions which are not matched by the predicate are re-raised, and may be caught by an enclosing catch, catchJust, etc.

A specialised variant of bracket with just a computation to run afterward.

A version of catch with the arguments swapped around; useful in situations where the code for the handler is shorter. For example:

  do handle (\NonTermination -> exitWith (ExitFailure 1)) $
     ...

A version of catchJust with the arguments swapped around (see handle).

This function maps one exception into another as proposed in the paper "A semantics for imprecise exceptions".

Like finally, but only performs the final action if there was an exception raised by the computation.

Similar to catch, but returns an Either result which is (Right a) if no exception of type e was raised, or (Left ex) if an exception of type e was raised and its value is ex. If any other type of exception is raised then it will be propagated up to the next enclosing exception handler.

 try a = catch (Right `liftM` a) (return . Left)

A variant of try that takes an exception predicate to select which exceptions are caught (c.f. catchJust). If the exception does not match the predicate, it is re-thrown.

Strict version of <$>.

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

or in terms of (>>=) as

bs a >>= cs

This generalizes the list-based Data.List.filter function.

runIdentity (filterM (Identity . p) xs) == filter p xs

Examples

>>> filterM (\x -> do      putStrLn ("Keep: " ++ show x ++ "?")      answer <- getLine      pure (answer == "y"))    [1, 2, 3]Keep: 1?yKeep: 2?nKeep: 3?y[1,3]

>>> filterM (\x -> do      putStr (show x)      x' <- readLn      pure (x == x'))    [1, 2, 3]122233[2,3]

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

foldM f a1 [x1, x2, ..., xm]

==

do
  a2 <- f a1 x1
  a3 <- f a2 x2
  ...
  f am xm

If right-to-left evaluation is required, the input list should be reversed.

Note: foldM is the same as foldlM

Like foldM, but discards the result.

Repeat an action indefinitely.

Examples

A common use of forever is to process input from network sockets, System.IO.Handles, and channels (e.g. MVar and Chan).

For example, here is how we might implement an echo server, using forever both to listen for client connections on a network socket and to echo client input on client connection handles:

echoServer :: Socket -> IO ()
echoServer socket = forever $ do
  client <- accept socket
  forkFinally (echo client) (\_ -> hClose client)
  where
    echo :: Handle -> IO ()
    echo client = forever $
      hGetLine client >>= hPutStrLn client

Note that "forever" isn't necessarily non-terminating. If the action is in a MonadPlus and short-circuits after some number of iterations. then forever actually returns mzero, effectively short-circuiting its caller.

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

Common uses of guard include conditionally signalling an error in an error monad and conditionally rejecting the current choice in an Alternative-based parser.

As an example of signalling an error in the error monad Maybe, consider a safe division function safeDiv x y that returns Nothing when the denominator y is zero and Just (x `div` y) otherwise. For example:

>>> safeDiv 4 0Nothing

>>> safeDiv 4 2Just 2

A definition of safeDiv using guards, but not guard:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

A definition of safeDiv using guard and Monad do-notation:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state monad.

Direct MonadPlus equivalent of Data.List.filter.

Examples

The Data.List.filter function is just mfilter specialized to the list monad:

Data.List.filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )

An example using mfilter with the Maybe monad:

>>> mfilter odd (Just 1)Just 1>>> mfilter odd (Just 2)Nothing

replicateM n act performs the action act n times, and then returns the list of results.

replicateM n (pure x) == replicate n x

Examples

>>> replicateM 3 getLinehiheyahiya["hi","heya","hiya"]

>>> import Control.Monad.State>>> runState (replicateM 3 $ state $ \s -> (s, s + 1)) 1([1,2,3],4)

Like replicateM, but discards the result.

Examples

>>> replicateM_ 3 (putStr "a")aaa

The reverse of when.

Examples

>>> do x <- getLine       unless (x == "hi") (putStrLn "hi!")comingupwithexamplesisdifficulthi!

>>> unless (pi > exp 1) NothingJust ()

The zipWithM function generalizes zipWith to arbitrary applicative functors.

zipWithM_ is the extension of zipWithM which ignores the final result.

Infix version of unsafeShiftL.

Infix version of unsafeShiftR.

Infix version of shiftL.

Infix version of shiftR.

Infix version of xor.

A more concise version of complement zeroBits.

>>> complement (zeroBits :: Word) == (oneBits :: Word)True

>>> complement (oneBits :: Word) == (zeroBits :: Word)True

Note

The constraint on oneBits is arguably too strong. However, as some types (such as Natural) have undefined complement, this is the only safe choice.

Case analysis for the Either type. If the value is Left a, apply the first function to a; if it is Right b, apply the second function to b.

Examples

We create two values of type Either String Int, one using the Left constructor and another using the Right constructor. Then we apply "either" the Prelude.length function (if we have a String) or the "times-two" function (if we have an Int):

>>> let s = Left "foo" :: Either String Int>>> let n = Right 3 :: Either String Int>>> either length (*2) s3>>> either length (*2) n6

Return the contents of a Left-value or a default value otherwise.

Examples

Basic usage:

>>> fromLeft 1 (Left 3)3>>> fromLeft 1 (Right "foo")1

Return the contents of a Right-value or a default value otherwise.

Examples

Basic usage:

>>> fromRight 1 (Right 3)3>>> fromRight 1 (Left "foo")1

Return True if the given value is a Left-value, False otherwise.

Examples

Basic usage:

>>> isLeft (Left "foo")True>>> isLeft (Right 3)False

Assuming a Left value signifies some sort of error, we can use isLeft to write a very simple error-reporting function that does absolutely nothing in the case of success, and outputs "ERROR" if any error occurred.

This example shows how isLeft might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )>>> let report e = when (isLeft e) $ putStrLn "ERROR">>> report (Right 1)>>> report (Left "parse error")ERROR

Return True if the given value is a Right-value, False otherwise.

Examples

Basic usage:

>>> isRight (Left "foo")False>>> isRight (Right 3)True

Assuming a Left value signifies some sort of error, we can use isRight to write a very simple reporting function that only outputs "SUCCESS" when a computation has succeeded.

This example shows how isRight might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )>>> let report e = when (isRight e) $ putStrLn "SUCCESS">>> report (Left "parse error")>>> report (Right 1)SUCCESS

Extracts from a list of Either all the Left elements. All the Left elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> lefts list["foo","bar","baz"]

Partitions a list of Either into two lists. All the Left elements are extracted, in order, to the first component of the output. Similarly the Right elements are extracted to the second component of the output.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list(["foo","bar","baz"],[3,7])

The pair returned by partitionEithers x should be the same pair as (lefts x, rights x):

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list == (lefts list, rights list)True

Extracts from a list of Either all the Right elements. All the Right elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> rights list[3,7]

Determines whether all elements of the structure satisfy the predicate.

Examples

Basic usage:

>>> all (> 3) []True

>>> all (> 3) [1,2]False

>>> all (> 3) [1,2,3,4,5]False

>>> all (> 3) [1..]False

>>> all (> 3) [4..]* Hangs forever *

and returns the conjunction of a container of Bools. For the result to be True, the container must be finite; False, however, results from a False value finitely far from the left end.

Examples

Basic usage:

>>> and []True

>>> and [True]True

>>> and [False]False

>>> and [True, True, False]False

>>> and (False : repeat True) -- Infinite list [False,True,True,True,...False

>>> and (repeat True)* Hangs forever *

Determines whether any element of the structure satisfies the predicate.

Examples

Basic usage:

>>> any (> 3) []False

>>> any (> 3) [1,2]False

>>> any (> 3) [1,2,3,4,5]True

>>> any (> 3) [1..]True

>>> any (> 3) [0, -1..]* Hangs forever *

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

The concatenation of all the elements of a container of lists.

Examples

Basic usage:

>>> concat (Just [1, 2, 3])[1,2,3]

>>> concat (Left 42)[]

>>> concat [[1, 2, 3], [4, 5], [6], []][1,2,3,4,5,6]

Map a function over all the elements of a container and concatenate the resulting lists.

Examples

Basic usage:

>>> concatMap (take 3) [[1..], [10..], [100..], [1000..]][1,2,3,10,11,12,100,101,102,1000,1001,1002]

>>> concatMap (take 3) (Just [1..])[1,2,3]

The find function takes a predicate and a structure and returns the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

Examples

Basic usage:

>>> find (> 42) [0, 5..]Just 45

>>> find (> 12) [1..7]Nothing

Left-to-right monadic fold over the elements of a structure.

Given a structure t with elements (a, b, ..., w, x, y), the result of a fold with an operator function f is equivalent to:

foldlM f z t = do
    aa <- f z a
    bb <- f aa b
    ...
    xx <- f ww x
    yy <- f xx y
    return yy -- Just @return z@ when the structure is empty

For a Monad m, given two functions f1 :: a -> m b and f2 :: b -> m c, their Kleisli composition (f1 >=> f2) :: a -> m c is defined by:

(f1 >=> f2) a = f1 a >>= f2

Another way of thinking about foldlM is that it amounts to an application to z of a Kleisli composition:

foldlM f z t =
    flip f a >=> flip f b >=> ... >=> flip f x >=> flip f y $ z

The monadic effects of foldlM are sequenced from left to right.

If at some step the bind operator (>>=) short-circuits (as with, e.g., mzero in a MonadPlus), the evaluated effects will be from an initial segment of the element sequence. If you want to evaluate the monadic effects in right-to-left order, or perhaps be able to short-circuit after processing a tail of the sequence of elements, you'll need to use foldrM instead.

If the monadic effects don't short-circuit, the outermost application of f is to the rightmost element y, so that, ignoring effects, the result looks like a left fold:

((((z `f` a) `f` b) ... `f` w) `f` x) `f` y

Examples

Basic usage:

>>> let f a e = do { print e ; return $ e : a }>>> foldlM f [] [0..3]0123[3,2,1,0]

Right-to-left monadic fold over the elements of a structure.

Given a structure t with elements (a, b, c, ..., x, y), the result of a fold with an operator function f is equivalent to:

foldrM f z t = do
    yy <- f y z
    xx <- f x yy
    ...
    bb <- f b cc
    aa <- f a bb
    return aa -- Just @return z@ when the structure is empty

For a Monad m, given two functions f1 :: a -> m b and f2 :: b -> m c, their Kleisli composition (f1 >=> f2) :: a -> m c is defined by:

(f1 >=> f2) a = f1 a >>= f2

Another way of thinking about foldrM is that it amounts to an application to z of a Kleisli composition:

foldrM f z t = f y >=> f x >=> ... >=> f b >=> f a $ z

The monadic effects of foldrM are sequenced from right to left, and e.g. folds of infinite lists will diverge.

If at some step the bind operator (>>=) short-circuits (as with, e.g., mzero in a MonadPlus), the evaluated effects will be from a tail of the element sequence. If you want to evaluate the monadic effects in left-to-right order, or perhaps be able to short-circuit after an initial sequence of elements, you'll need to use foldlM instead.

If the monadic effects don't short-circuit, the outermost application of f is to the leftmost element a, so that, ignoring effects, the result looks like a right fold:

a `f` (b `f` (c `f` (... (x `f` (y `f` z))))).

Examples

Basic usage:

>>> let f i acc = do { print i ; return $ i : acc }>>> foldrM f [] [0..3]3210[0,1,2,3]

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see Data.Traversable.forM.

forM_ is just like for_, but specialised to monadic actions.

for_ is traverse_ with its arguments flipped. For a version that doesn't ignore the results see for. This is forM_ generalised to Applicative actions.

for_ is just like forM_, but generalised to Applicative actions.

Examples

Basic usage:

>>> for_ [1..4] print1234

Map each element of a structure to a monadic action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see Data.Traversable.mapM.

mapM_ is just like traverse_, but specialised to monadic actions.

The largest element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple largest elements, the rightmost of them is chosen.

Examples

Basic usage:

>>> maximumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]"Longest"

WARNING: This function is partial for possibly-empty structures like lists.

The least element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple least elements, the leftmost of them is chosen.

Examples

Basic usage:

>>> minimumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]"!"

WARNING: This function is partial for possibly-empty structures like lists.

The sum of a collection of actions using (<|>), generalizing concat.

msum is just like asum, but specialised to MonadPlus.

Examples

Basic usage, using the MonadPlus instance for Maybe:

>>> msum [Just "Hello", Nothing, Just "World"]Just "Hello"

notElem is the negation of elem.

Examples

Basic usage:

>>> 3 `notElem` []True

>>> 3 `notElem` [1,2]True

>>> 3 `notElem` [1,2,3,4,5]False

For infinite structures, notElem terminates if the value exists at a finite distance from the left side of the structure:

>>> 3 `notElem` [1..]False

>>> 3 `notElem` ([4..] ++ [3])* Hangs forever *

or returns the disjunction of a container of Bools. For the result to be False, the container must be finite; True, however, results from a True value finitely far from the left end.

Examples

Basic usage:

>>> or []False

>>> or [True]True

>>> or [False]False

>>> or [True, True, False]True

>>> or (True : repeat False) -- Infinite list [True,False,False,False,...True

>>> or (repeat False)* Hangs forever *

Evaluate each action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see sequenceA.

sequenceA_ is just like sequence_, but generalised to Applicative actions.

Examples

Basic usage:

>>> sequenceA_ [print "Hello", print "world", print "!"]"Hello""world""!"

Evaluate each monadic action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see Data.Traversable.sequence.

sequence_ is just like sequenceA_, but specialised to monadic actions.

Map each element of a structure to an Applicative action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see traverse.

traverse_ is just like mapM_, but generalised to Applicative actions.

Examples

Basic usage:

>>> traverse_ print ["Hello", "world", "!"]"Hello""world""!"

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

This is a version of flip id, where id is specialized from a -> a to (a -> b) -> (a -> b) which by the associativity of (->) is (a -> b) -> a -> b. flipping this yields a -> (a -> b) -> b which is the type signature of &

Examples

>>> 5 & (+1) & show"6"

>>> sqrt $ [1 / n^2 | n <- [1..1000]] & sum & (*6)3.1406380562059946

on b u x y runs the binary function b on the results of applying unary function u to two arguments x and y. From the opposite perspective, it transforms two inputs and combines the outputs.

(op `on` f) x y = f x `op` f y

Examples

>>> sortBy (compare `on` length) [[0, 1, 2], [0, 1], [], [0]][[],[0],[0,1],[0,1,2]]

>>> ((+) `on` length) [1, 2, 3] [-1]4

>>> ((,) `on` (*2)) 2 3(4,6)

Algebraic properties

• (*) `on` id = (*) -- (if (*) ∉ {⊥, const ⊥})

• ((*) `on` f) `on` g = (*) `on` (f . g)

• flip on f . flip on g = flip on (g . f)

Flipped version of <$.

Examples

Replace the contents of a Maybe Int with a constant String:

>>> Nothing $> "foo"Nothing

>>> Just 90210 $> "foo"Just "foo"

Replace the contents of an Either Int Int with a constant String, resulting in an Either Int String:

>>> Left 8675309 $> "foo"Left 8675309

>>> Right 8675309 $> "foo"Right "foo"

Replace each element of a list with a constant String:

>>> [1,2,3] $> "foo"["foo","foo","foo"]

Replace the second element of a pair with a constant String:

>>> (1,2) $> "foo"(1,"foo")

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)(2,True)

Flipped version of <$>.

(<&>) = flip fmap

Examples

Apply (+1) to a list, a Just and a Right:

>>> Just 2 <&> (+1)Just 3

>>> [1,2,3] <&> (+1)[2,3,4]

>>> Right 3 <&> (+1)Right 4

void value discards or ignores the result of evaluation, such as the return value of an System.IO.IO action.

Examples

Replace the contents of a Maybe Int with unit:

>>> void NothingNothing

>>> void (Just 3)Just ()

Replace the contents of an Either Int Int with unit, resulting in an Either Int ():

>>> void (Left 8675309)Left 8675309

>>> void (Right 8675309)Right ()

Replace every element of a list with unit:

>>> void [1,2,3][(),(),()]

Replace the second element of a pair with unit:

>>> void (1,2)(1,())

Discard the result of an System.IO.IO action:

>>> mapM print [1,2]12[(),()]

>>> void $ mapM print [1,2]12

The catMaybes function takes a list of Maybes and returns a list of all the Just values.

Examples

Basic usage:

>>> catMaybes [Just 1, Nothing, Just 3][1,3]

When constructing a list of Maybe values, catMaybes can be used to return all of the "success" results (if the list is the result of a map, then mapMaybe would be more appropriate):

>>> import GHC.Internal.Text.Read ( readMaybe )>>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ][Just 1,Nothing,Just 3]>>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ][1,3]

The fromMaybe function takes a default value and a Maybe value. If the Maybe is Nothing, it returns the default value; otherwise, it returns the value contained in the Maybe.

Examples

Basic usage:

>>> fromMaybe "" (Just "Hello, World!")"Hello, World!"

>>> fromMaybe "" Nothing""

Read an integer from a string using readMaybe. If we fail to parse an integer, we want to return 0 by default:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> fromMaybe 0 (readMaybe "5")5>>> fromMaybe 0 (readMaybe "")0

isJust x returns True when x is of the form Just _ and False otherwise.

Examples

Basic usage:

>>> isJust (Just 3)True

>>> isJust (Just ())True

>>> isJust NothingFalse

Only the outer constructor is taken into consideration:

>>> isJust (Just Nothing)True

isNothing x returns True when x is Nothing and False otherwise.

Examples

Basic usage:

>>> isNothing (Just 3)False

>>> isNothing (Just ())False

>>> isNothing NothingTrue

Only the outer constructor is taken into consideration:

>>> isNothing (Just Nothing)False

The listToMaybe function returns Nothing on an empty list or Just a where a is the first element of the list.

Examples

Basic usage:

>>> listToMaybe []Nothing

>>> listToMaybe [9]Just 9

>>> listToMaybe [1,2,3]Just 1

Composing maybeToList with listToMaybe should be the identity on singleton/empty lists:

>>> maybeToList $ listToMaybe [5][5]>>> maybeToList $ listToMaybe [][]

But not on lists with more than one element:

>>> maybeToList $ listToMaybe [1,2,3][1]

The mapMaybe function is a version of map which can throw out elements. In particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.

Examples

Using mapMaybe f x is a shortcut for catMaybes $ map f x in most cases:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> let readMaybeInt = readMaybe :: String -> Maybe Int>>> mapMaybe readMaybeInt ["1", "Foo", "3"][1,3]>>> catMaybes $ map readMaybeInt ["1", "Foo", "3"][1,3]

If we map the Just constructor, the entire list should be returned:

>>> mapMaybe Just [1,2,3][1,2,3]

The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

Examples

Basic usage:

>>> maybe False odd (Just 3)True

>>> maybe False odd NothingFalse

Read an integer from a string using readMaybe. If we succeed, return twice the integer; that is, apply (*2) to it. If instead we fail to parse an integer, return 0 by default:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> maybe 0 (*2) (readMaybe "5")10>>> maybe 0 (*2) (readMaybe "")0

Apply show to a Maybe Int. If we have Just n, we want to show the underlying Int n. But if we have Nothing, we return the empty string instead of (for example) "Nothing":

>>> maybe "" show (Just 5)"5">>> maybe "" show Nothing""

The maybeToList function returns an empty list when given Nothing or a singleton list when given Just.

Examples

Basic usage:

>>> maybeToList (Just 7)[7]