Documentation

A class of types that can be fully evaluated.

Since: 1.1.0.0

& 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 $.

Since: 4.8.0.0

Conditional execution of Applicative expressions. For example,

when debug (putStrLn "Debugging")

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

The reverse of when.

forM is mapM with its arguments flipped. For a version that ignores the results see forM_.

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

As of base 4.8.0.0, forM_ is just for_, specialized to Monad.

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

Examples

>>> void Nothing
Nothing
>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309
>>> void (Right 8675309)
Right ()

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

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

>>> mapM print [1,2]
1
2
[(),()]
>>> void $ mapM print [1,2]
1
2

replicateM n act performs the action n times, gathering the results.

forever act repeats the action infinitely.

guard b is pure () if b is True, and empty if b is False.

Identity functor and monad. (a non-strict monad)

Since: 4.8.0.0

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Lift a computation from the argument monad to the constructed monad.

A state monad parameterized by the type s of the state to carry.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

A state transformer monad parameterized by:

• s - The state.
• m - The inner monad.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

modify f is an action that updates the state to the result of applying f to the current state.

• modify f = get >>= (put . f)

Unwrap a state monad computation as a function. (The inverse of state.)

Evaluate a state computation with the given initial state and return the final value, discarding the final state.

• evalState m s = fst (runState m s)

Evaluate a state computation with the given initial state and return the final state, discarding the final value.

• execState m s = snd (runState m s)

Evaluate a state computation with the given initial state and return the final value, discarding the final state.

• evalStateT m s = liftM fst (runStateT m s)

Evaluate a state computation with the given initial state and return the final state, discarding the final value.

• execStateT m s = liftM snd (runStateT m s)

A writer monad parameterized by the type w of output to accumulate.

The return function produces the output mempty, while >>= combines the outputs of the subcomputations using mappend.

A writer monad parameterized by:

• w - the output to accumulate.
• m - The inner monad.

The return function produces the output mempty, while >>= combines the outputs of the subcomputations using mappend.

tell w is an action that produces the output w.

Unwrap a writer computation as a (result, output) pair. (The inverse of writer.)

Extract the output from a writer computation.

• execWriter m = snd (runWriter m)

Extract the output from a writer computation.

• execWriterT m = liftM snd (runWriterT m)

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

Examples

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

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

Examples

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

List of elements of a structure, from left to right.

(*) `on` f = \x y -> f x * f y.

Typical usage: sortBy (compare `on` fst).

Algebraic properties:

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

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

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

The sort function implements a stable sorting algorithm. It is a special case of sortBy, which allows the programmer to supply their own comparison function.

The sortBy function is the non-overloaded version of sort.

The least element of a non-empty structure with respect to the given comparison function.

The largest element of a non-empty structure with respect to the given comparison function.

Left-associative fold of a structure. but with strict application of the operator.

foldl f z = foldl' f z . toList

intercalate xs xss is equivalent to (concat (intersperse xs xss)). It inserts the list xs in between the lists in xss and concatenates the result.

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

Examples

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

>>> import 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 fromJust function extracts the element out of a Just and throws an error if its argument is Nothing.

Examples

>>> fromJust (Just 1)
1

>>> 2 * (fromJust (Just 10))
20

>>> 2 * (fromJust Nothing)
*** Exception: Maybe.fromJust: Nothing

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

Examples

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

>>> fromMaybe "" Nothing
""

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

An infix synonym for mappend.

Since: 4.5.0.0

getDirectoryContents dir returns a list of all entries in dir.

The operation may fail with:

• HardwareFault A physical I/O error has occurred. [EIO]
• InvalidArgument The operand is not a valid directory name. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing The directory does not exist. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied The process has insufficient privileges to perform the operation. [EACCES]
• ResourceExhausted Insufficient resources are available to perform the operation. [EMFILE, ENFILE]
• InappropriateType The path refers to an existing non-directory object. [ENOTDIR]

Computation getArgs returns a list of the program's command line arguments (not including the program name).

Join two values with a path separator. For examples and caveats see the equivalent function combine.

Posix:   "/directory" </> "file.ext" == "/directory/file.ext"
Windows: "/directory" </> "file.ext" == "/directory\\file.ext"

Add an extension, even if there is already one there, equivalent to addExtension.

"/directory/path" <.> "ext" == "/directory/path.ext"
"/directory/path" <.> ".ext" == "/directory/path.ext"

withFile name mode act opens a file using openFile and passes the resulting handle to the computation act. The handle will be closed on exit from withFile, whether by normal termination or by raising an exception. If closing the handle raises an exception, then this exception will be raised by withFile rather than any exception raised by act.

See openFile

Computation hPutStr hdl s writes the string s to the file or channel managed by hdl.

This operation may fail with:

• isFullError if the device is full; or
• isPermissionError if another system resource limit would be exceeded.

The same as hPutStr, but adds a newline character.

Format a variable number of arguments with the C-style formatting string. The return value is either String or (IO a) (which should be (IO '()'), but Haskell's type system makes this hard).

The format string consists of ordinary characters and conversion specifications, which specify how to format one of the arguments to printf in the output string. A format specification is introduced by the % character; this character can be self-escaped into the format string using %%. A format specification ends with a /format character/ that provides the primary information about how to format the value. The rest of the conversion specification is optional. In order, one may have flag characters, a width specifier, a precision specifier, and type-specific modifier characters.

Unlike C printf(3), the formatting of this printf is driven by the argument type; formatting is type specific. The types formatted by printf "out of the box" are:

• Integral types, including Char
• String
• RealFloat types

printf is also extensible to support other types: see below.

A conversion specification begins with the character %, followed by zero or more of the following flags:

   -      left adjust (default is right adjust)
   +      always use a sign (+ or -) for signed conversions
   space  leading space for positive numbers in signed conversions
   0      pad with zeros rather than spaces
   #      use an \"alternate form\": see below

When both flags are given, - overrides 0 and + overrides space. A negative width specifier in a * conversion is treated as positive but implies the left adjust flag.

The "alternate form" for unsigned radix conversions is as in C printf(3):

   %o           prefix with a leading 0 if needed
   %x           prefix with a leading 0x if nonzero
   %X           prefix with a leading 0X if nonzero
   %b           prefix with a leading 0b if nonzero
   %[eEfFgG]    ensure that the number contains a decimal point

Any flags are followed optionally by a field width:

   num    field width
   *      as num, but taken from argument list

The field width is a minimum, not a maximum: it will be expanded as needed to avoid mutilating a value.

Any field width is followed optionally by a precision:

   .num   precision
   .      same as .0
   .*     as num, but taken from argument list

Negative precision is taken as 0. The meaning of the precision depends on the conversion type.

   Integral    minimum number of digits to show
   RealFloat   number of digits after the decimal point
   String      maximum number of characters

The precision for Integral types is accomplished by zero-padding. If both precision and zero-pad are given for an Integral field, the zero-pad is ignored.

Any precision is followed optionally for Integral types by a width modifier; the only use of this modifier being to set the implicit size of the operand for conversion of a negative operand to unsigned:

   hh     Int8
   h      Int16
   l      Int32
   ll     Int64
   L      Int64

The specification ends with a format character:

   c      character               Integral
   d      decimal                 Integral
   o      octal                   Integral
   x      hexadecimal             Integral
   X      hexadecimal             Integral
   b      binary                  Integral
   u      unsigned decimal        Integral
   f      floating point          RealFloat
   F      floating point          RealFloat
   g      general format float    RealFloat
   G      general format float    RealFloat
   e      exponent format float   RealFloat
   E      exponent format float   RealFloat
   s      string                  String
   v      default format          any type

The "%v" specifier is provided for all built-in types, and should be provided for user-defined type formatters as well. It picks a "best" representation for the given type. For the built-in types the "%v" specifier is converted as follows:

   c      Char
   u      other unsigned Integral
   d      other signed Integral
   g      RealFloat
   s      String

Mismatch between the argument types and the format string, as well as any other syntactic or semantic errors in the format string, will cause an exception to be thrown at runtime.

Note that the formatting for RealFloat types is currently a bit different from that of C printf(3), conforming instead to showEFloat, showFFloat and showGFloat (and their alternate versions showFFloatAlt and showGFloatAlt). This is hard to fix: the fixed versions would format in a backward-incompatible way. In any case the Haskell behavior is generally more sensible than the C behavior. A brief summary of some key differences:

• Haskell printf never uses the default "6-digit" precision used by C printf.
• Haskell printf treats the "precision" specifier as indicating the number of digits after the decimal point.
• Haskell printf prints the exponent of e-format numbers without a gratuitous plus sign, and with the minimum possible number of digits.
• Haskell printf will place a zero after a decimal point when possible.

Examples

  > printf "%d\n" (23::Int)
  23
  > printf "%s %s\n" "Hello" "World"
  Hello World
  > printf "%.2f\n" pi
  3.14