Boolean "and"

Boolean "or"

Boolean "not"

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

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

The Maybe type encapsulates an optional value. A value of type Maybe a either contains a value of type a (represented as Just a), or it is empty (represented as Nothing). Using Maybe is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error.

The Maybe type is also a monad. It is a simple kind of error monad, where all errors are represented by Nothing. A richer error monad can be built using the Either type.

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

The isNothing function returns True iff its argument is Nothing.

Examples

>>> isNothing (Just 3)
False

>>> isNothing (Just ())
False

>>> isNothing Nothing
True

>>> isNothing (Just Nothing)
False

The isJust function returns True iff its argument is of the form Just _.

Examples

>>> isJust (Just 3)
True

>>> isJust (Just ())
True

>>> isJust Nothing
False

>>> isJust (Just Nothing)
True

The Either type represents values with two possibilities: a value of type Either a b is either Left a or Right b.

The Either type is sometimes used to represent a value which is either correct or an error; by convention, the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value (mnemonic: "right" also means "correct").

Examples

>>> let s = Left "foo" :: Either String Int
>>> s
Left "foo"
>>> let n = Right 3 :: Either String Int
>>> n
Right 3
>>> :type s
s :: Either String Int
>>> :type n
n :: Either String Int

>>> let s = Left "foo" :: Either String Int
>>> let n = Right 3 :: Either String Int
>>> fmap (*2) s
Left "foo"
>>> fmap (*2) n
Right 6

>>> import Data.Char ( digitToInt, isDigit )
>>> :{
    let parseEither :: Char -> Either String Int
        parseEither c
          | isDigit c = Right (digitToInt c)
          | otherwise = Left "parse error"
>>> :}

>>> :{
    let parseMultiple :: Either String Int
        parseMultiple = do
          x <- parseEither '1'
          y <- parseEither '2'
          return (x + y)
>>> :}

>>> parseMultiple
Right 3

>>> :{
    let parseMultiple :: Either String Int
        parseMultiple = do
          x <- parseEither 'm'
          y <- parseEither '2'
          return (x + y)
>>> :}

>>> parseMultiple
Left "parse error"

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

Examples

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

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

Since: 4.7.0.0

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

Examples

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

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

Since: 4.7.0.0

Extract the first component of a pair.

Extract the second component of a pair.

curry converts an uncurried function to a curried function.

uncurry converts a curried function to a function on pairs.

Extract the first element of a list, which must be non-empty.

Extract the last element of a list, which must be finite and non-empty.

Extract the elements after the head of a list, which must be non-empty.

Return all the elements of a list except the last one. The list must be non-empty.

Test whether the structure is empty. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.

Returns the size/length of a finite structure as an Int. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.

List index (subscript) operator, starting from 0. It is an instance of the more general genericIndex, which takes an index of any integral type.

reverse xs returns the elements of xs in reverse order. xs must be finite.

A class for categories. id and (.) must form a monoid.

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following laws:

• mappend mempty x = x

• mappend x mempty = x

• mappend x (mappend y z) = mappend (mappend x y) z

• mconcat = foldr mappend mempty

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Sum and Product.

An infix synonym for mappend.

Since: 4.5.0.0

The Functor class is used for types that can be mapped over. Instances of Functor should satisfy the following laws:

fmap id  ==  id
fmap (f . g)  ==  fmap f . fmap g

The instances of Functor for lists, Maybe and IO satisfy these laws.

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

An infix synonym for fmap.

Examples

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

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

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

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

Flipped version of <$.

Examples

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

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

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

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

Since: 4.7.0.0

A functor with application, providing operations to

• embed pure expressions (pure), and
• sequence computations and combine their results (<*>).

A minimal complete definition must include implementations of these functions satisfying the following laws:

identity

pure id <*> v = v

composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

homomorphism

pure f <*> pure x = pure (f x)

interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

• u *> v = pure (const id) <*> u <*> v

• u <* v = pure const <*> u <*> v

As a consequence of these laws, the Functor instance for f will satisfy

• fmap f x = pure f <*> x

If f is also a Monad, it should satisfy

• pure = return

• (<*>) = ap

(which implies that pure and <*> satisfy the applicative functor laws).

A variant of <*> with the arguments reversed.

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions.

Instances of Monad should satisfy the following laws:

• return a >>= k  =  k a

• m >>= return  =  m

• m >>= (x -> k x >>= h)  =  (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• (<*>) = ap

The above laws imply:

• fmap f xs  =  xs >>= return . f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws.

The instances of Monad for lists, Maybe and IO defined in the Prelude satisfy these laws.

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

Left-to-right Kleisli composition of monads.

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

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.

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

• some v = (:) <$> v <*> many v

• many v = some v <|> pure []

One or none.

The sum of a collection of actions, generalizing concat.

Monads that also support choice and failure.

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

The sum of a collection of actions, generalizing concat. As of base 4.8.0.0, msum is just asum, specialized to MonadPlus.

Direct MonadPlus equivalent of filter filter = (mfilter:: (a -> Bool) -> [a] -> [a] applicable to any MonadPlus, for example mfilter odd (Just 1) == Just 1 mfilter odd (Just 2) == Nothing

Data structures that can be folded.

For example, given a data type

data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)

a suitable instance would be

instance Foldable Tree where
   foldMap f Empty = mempty
   foldMap f (Leaf x) = f x
   foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r

This is suitable even for abstract types, as the monoid is assumed to satisfy the monoid laws. Alternatively, one could define foldr:

instance Foldable Tree where
   foldr f z Empty = z
   foldr f z (Leaf x) = f x z
   foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l

Foldable instances are expected to satisfy the following laws:

foldr f z t = appEndo (foldMap (Endo . f) t ) z

foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z

fold = foldMap id

sum, product, maximum, and minimum should all be essentially equivalent to foldMap forms, such as

sum = getSum . foldMap Sum

but may be less defined.

If the type is also a Functor instance, it should satisfy

foldMap f = fold . fmap f

which implies that

foldMap f . fmap g = foldMap (f . g)

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

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

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

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.

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.

Determines whether any element of the structure satisfies the predicate.

Determines whether all elements of the structure satisfy the predicate.

The sum function computes the sum of the numbers of a structure.

The product function computes the product of the numbers of a structure.

The largest element of a non-empty structure.

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

The least element of a non-empty structure.

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

Does the element occur in the structure?

notElem is the negation of elem.

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.

Functors representing data structures that can be traversed from left to right.

A definition of traverse must satisfy the following laws:

naturality

t . traverse f = traverse (t . f) for every applicative transformation t

identity

traverse Identity = Identity

composition

traverse (Compose . fmap g . f) = Compose . fmap (traverse g) . traverse f

A definition of sequenceA must satisfy the following laws:

naturality

t . sequenceA = sequenceA . fmap t for every applicative transformation t

identity

sequenceA . fmap Identity = Identity

composition

sequenceA . fmap Compose = Compose . fmap sequenceA . sequenceA

where an applicative transformation is a function

t :: (Applicative f, Applicative g) => f a -> g a

preserving the Applicative operations, i.e.

• t (pure x) = pure x

• t (x <*> y) = t x <*> t y

and the identity functor Identity and composition of functors Compose are defined as

  newtype Identity a = Identity a

  instance Functor Identity where
    fmap f (Identity x) = Identity (f x)

  instance Applicative Indentity where
    pure x = Identity x
    Identity f <*> Identity x = Identity (f x)

  newtype Compose f g a = Compose (f (g a))

  instance (Functor f, Functor g) => Functor (Compose f g) where
    fmap f (Compose x) = Compose (fmap (fmap f) x)

  instance (Applicative f, Applicative g) => Applicative (Compose f g) where
    pure x = Compose (pure (pure x))
    Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)

(The naturality law is implied by parametricity.)

Instances are similar to Functor, e.g. given a data type

data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)

a suitable instance would be

instance Traversable Tree where
   traverse f Empty = pure Empty
   traverse f (Leaf x) = Leaf <$> f x
   traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r

This is suitable even for abstract types, as the laws for <*> imply a form of associativity.

The superclass instances should satisfy the following:

• In the Functor instance, fmap should be equivalent to traversal with the identity applicative functor (fmapDefault).
• In the Foldable instance, foldMap should be equivalent to traversal with a constant applicative functor (foldMapDefault).

for is traverse with its arguments flipped. For a version that ignores the results see for_.

The Eq class defines equality (==) and inequality (/=). All the basic datatypes exported by the Prelude are instances of Eq, and Eq may be derived for any datatype whose constituents are also instances of Eq.

Minimal complete definition: either == or /=.

The Ord class is used for totally ordered datatypes.

Instances of Ord can be derived for any user-defined datatype whose constituent types are in Ord. The declared order of the constructors in the data declaration determines the ordering in derived Ord instances. The Ordering datatype allows a single comparison to determine the precise ordering of two objects.

Minimal complete definition: either compare or <=. Using compare can be more efficient for complex types.

Class Enum defines operations on sequentially ordered types.

The enumFrom... methods are used in Haskell's translation of arithmetic sequences.

Instances of Enum may be derived for any enumeration type (types whose constructors have no fields). The nullary constructors are assumed to be numbered left-to-right by fromEnum from 0 through n-1. See Chapter 10 of the Haskell Report for more details.

For any type that is an instance of class Bounded as well as Enum, the following should hold:

• The calls succ maxBound and pred minBound should result in a runtime error.
• fromEnum and toEnum should give a runtime error if the result value is not representable in the result type. For example, toEnum 7 :: Bool is an error.
• enumFrom and enumFromThen should be defined with an implicit bound, thus:

   enumFrom     x   = enumFromTo     x maxBound
   enumFromThen x y = enumFromThenTo x y bound
     where
       bound | fromEnum y >= fromEnum x = maxBound
             | otherwise                = minBound

The Bounded class is used to name the upper and lower limits of a type. Ord is not a superclass of Bounded since types that are not totally ordered may also have upper and lower bounds.

The Bounded class may be derived for any enumeration type; minBound is the first constructor listed in the data declaration and maxBound is the last. Bounded may also be derived for single-constructor datatypes whose constituent types are in Bounded.

Constant function.

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

Application operator. This operator is redundant, since ordinary application (f x) means the same as (f $ x). However, $ has low, right-associative binding precedence, so it sometimes allows parentheses to be omitted; for example:

    f $ g $ h x  =  f (g (h x))

It is also useful in higher-order situations, such as map ($ 0) xs, or zipWith ($) fs xs.

until p f yields the result of applying f until p holds.

asTypeOf is a type-restricted version of const. It is usually used as an infix operator, and its typing forces its first argument (which is usually overloaded) to have the same type as the second.

error stops execution and displays an error message.

A special case of error. It is expected that compilers will recognize this and insert error messages which are more appropriate to the context in which undefined appears.

The value of seq a b is bottom if a is bottom, and otherwise equal to b. seq is usually introduced to improve performance by avoiding unneeded laziness.

A note on evaluation order: the expression seq a b does not guarantee that a will be evaluated before b. The only guarantee given by seq is that the both a and b will be evaluated before seq returns a value. In particular, this means that b may be evaluated before a. If you need to guarantee a specific order of evaluation, you must use the function pseq from the "parallel" package.

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.

The character type Char is an enumeration whose values represent Unicode (or equivalently ISO/IEC 10646) characters (see http://www.unicode.org/ for details). This set extends the ISO 8859-1 (Latin-1) character set (the first 256 characters), which is itself an extension of the ASCII character set (the first 128 characters). A character literal in Haskell has type Char.

To convert a Char to or from the corresponding Int value defined by Unicode, use toEnum and fromEnum from the Enum class respectively (or equivalently ord and chr).

A String is a list of characters. String constants in Haskell are values of type String.

The shows functions return a function that prepends the output String to an existing String. This allows constant-time concatenation of results using function composition.

Conversion of values to readable Strings.

Derived instances of Show have the following properties, which are compatible with derived instances of Read:

• The result of show is a syntactically correct Haskell expression containing only constants, given the fixity declarations in force at the point where the type is declared. It contains only the constructor names defined in the data type, parentheses, and spaces. When labelled constructor fields are used, braces, commas, field names, and equal signs are also used.
• If the constructor is defined to be an infix operator, then showsPrec will produce infix applications of the constructor.
• the representation will be enclosed in parentheses if the precedence of the top-level constructor in x is less than d (associativity is ignored). Thus, if d is 0 then the result is never surrounded in parentheses; if d is 11 it is always surrounded in parentheses, unless it is an atomic expression.
• If the constructor is defined using record syntax, then show will produce the record-syntax form, with the fields given in the same order as the original declaration.

For example, given the declarations

infixr 5 :^:
data Tree a =  Leaf a  |  Tree a :^: Tree a

the derived instance of Show is equivalent to

instance (Show a) => Show (Tree a) where

       showsPrec d (Leaf m) = showParen (d > app_prec) $
            showString "Leaf " . showsPrec (app_prec+1) m
         where app_prec = 10

       showsPrec d (u :^: v) = showParen (d > up_prec) $
            showsPrec (up_prec+1) u .
            showString " :^: "      .
            showsPrec (up_prec+1) v
         where up_prec = 5

Note that right-associativity of :^: is ignored. For example,

• show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".

equivalent to showsPrec with a precedence of 0.

utility function converting a Char to a show function that simply prepends the character unchanged.

utility function converting a String to a show function that simply prepends the string unchanged.

utility function that surrounds the inner show function with parentheses when the Bool parameter is True.

A parser for a type a, represented as a function that takes a String and returns a list of possible parses as (a,String) pairs.

Note that this kind of backtracking parser is very inefficient; reading a large structure may be quite slow (cf ReadP).

Parsing of Strings, producing values.

Derived instances of Read make the following assumptions, which derived instances of Show obey:

• If the constructor is defined to be an infix operator, then the derived Read instance will parse only infix applications of the constructor (not the prefix form).
• Associativity is not used to reduce the occurrence of parentheses, although precedence may be.
• If the constructor is defined using record syntax, the derived Read will parse only the record-syntax form, and furthermore, the fields must be given in the same order as the original declaration.
• The derived Read instance allows arbitrary Haskell whitespace between tokens of the input string. Extra parentheses are also allowed.

For example, given the declarations

infixr 5 :^:
data Tree a =  Leaf a  |  Tree a :^: Tree a

the derived instance of Read in Haskell 2010 is equivalent to

instance (Read a) => Read (Tree a) where

        readsPrec d r =  readParen (d > app_prec)
                         (\r -> [(Leaf m,t) |
                                 ("Leaf",s) <- lex r,
                                 (m,t) <- readsPrec (app_prec+1) s]) r

                      ++ readParen (d > up_prec)
                         (\r -> [(u:^:v,w) |
                                 (u,s) <- readsPrec (up_prec+1) r,
                                 (":^:",t) <- lex s,
                                 (v,w) <- readsPrec (up_prec+1) t]) r

          where app_prec = 10
                up_prec = 5

Note that right-associativity of :^: is unused.

The derived instance in GHC is equivalent to

instance (Read a) => Read (Tree a) where

        readPrec = parens $ (prec app_prec $ do
                                 Ident "Leaf" <- lexP
                                 m <- step readPrec
                                 return (Leaf m))

                     +++ (prec up_prec $ do
                                 u <- step readPrec
                                 Symbol ":^:" <- lexP
                                 v <- step readPrec
                                 return (u :^: v))

          where app_prec = 10
                up_prec = 5

        readListPrec = readListPrecDefault

equivalent to readsPrec with a precedence of 0.

readParen True p parses what p parses, but surrounded with parentheses.

readParen False p parses what p parses, but optionally surrounded with parentheses.

The read function reads input from a string, which must be completely consumed by the input process.

The lex function reads a single lexeme from the input, discarding initial white space, and returning the characters that constitute the lexeme. If the input string contains only white space, lex returns a single successful `lexeme' consisting of the empty string. (Thus lex "" = [("","")].) If there is no legal lexeme at the beginning of the input string, lex fails (i.e. returns []).

This lexer is not completely faithful to the Haskell lexical syntax in the following respects:

• Qualified names are not handled properly
• Octal and hexadecimal numerics are not recognized as a single token
• Comments are not treated properly

A value of type IO a is a computation which, when performed, does some I/O before returning a value of type a.

There is really only one way to "perform" an I/O action: bind it to Main.main in your program. When your program is run, the I/O will be performed. It isn't possible to perform I/O from an arbitrary function, unless that function is itself in the IO monad and called at some point, directly or indirectly, from Main.main.

IO is a monad, so IO actions can be combined using either the do-notation or the >> and >>= operations from the Monad class.

Write a character to the standard output device (same as hPutChar stdout).

Write a string to the standard output device (same as hPutStr stdout).

The same as putStr, but adds a newline character.

The print function outputs a value of any printable type to the standard output device. Printable types are those that are instances of class Show; print converts values to strings for output using the show operation and adds a newline.

For example, a program to print the first 20 integers and their powers of 2 could be written as:

main = print ([(n, 2^n) | n <- [0..19]])

Read a character from the standard input device (same as hGetChar stdin).

Read a line from the standard input device (same as hGetLine stdin).

The getContents operation returns all user input as a single string, which is read lazily as it is needed (same as hGetContents stdin).

The interact function takes a function of type String->String as its argument. The entire input from the standard input device is passed to this function as its argument, and the resulting string is output on the standard output device.

File and directory names are values of type String, whose precise meaning is operating system dependent. Files can be opened, yielding a handle which can then be used to operate on the contents of that file.

The readFile function reads a file and returns the contents of the file as a string. The file is read lazily, on demand, as with getContents.

The computation writeFile file str function writes the string str, to the file file.

The computation appendFile file str function appends the string str, to the file file.

Note that writeFile and appendFile write a literal string to a file. To write a value of any printable type, as with print, use the show function to convert the value to a string first.

main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])

The readIO function is similar to read except that it signals parse failure to the IO monad instead of terminating the program.

The readLn function combines getLine and readIO.

The Haskell 2010 type for exceptions in the IO monad. Any I/O operation may raise an IOError instead of returning a result. For a more general type of exception, including also those that arise in pure code, see Control.Exception.Exception.

In Haskell 2010, this is an opaque type.

Raise an IOError in the IO monad.

Construct an IOError value with a string describing the error. The fail method of the IO instance of the Monad class raises a userError, thus:

instance Monad IO where
  ...
  fail s = ioError (userError s)

A fixed-precision integer type with at least the range [-2^29 .. 2^29-1]. The exact range for a given implementation can be determined by using minBound and maxBound from the Bounded class.

Invariant: Jn# and Jp# are used iff value doesn't fit in S#

Useful properties resulting from the invariants:

• abs (S# _) <= abs (Jp# _)

• abs (S# _) <  abs (Jn# _)

Single-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE single-precision type.

Double-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE double-precision type.

Arbitrary-precision rational numbers, represented as a ratio of two Integer values. A rational number may be constructed using the % operator.

Basic numeric class.

Integral numbers, supporting integer division.

Fractional numbers, supporting real division.

Trigonometric and hyperbolic functions and related functions.

Extracting components of fractions.

Efficient, machine-independent access to the components of a floating-point number.