Distribution.Compat.Prelude

Right to left function composition.

prop> (f . g) x = f (g x)

prop> f . id = f = id . f

Examples

>>> map ((*2) . length) [[], [0, 1, 2], [0]][0,6,2]

>>> foldr (.) id [(+1), (*3), (^3)] 225

>>> let (...) = (.).(.) in ((*2)...(+)) 5 1030

Basic numeric class.

The Haskell Report defines no laws for Num. However, (+) and (*) are customarily expected to define a ring and have the following properties:

Associativity of (+)

(x + y) + z

=

x + (y + z)

Commutativity of (+)

x + y

=

y + x

fromInteger 0 is the additive identity

x + fromInteger 0

=

x

negate gives the additive inverse

x + negate x

=

fromInteger 0

Associativity of (*)

(x * y) * z

=

x * (y * z)

fromInteger 1 is the multiplicative identity

x * fromInteger 1

=

x

and

fromInteger 1 * x

=

x

Distributivity of (*) with respect to (+)

a * (b + c)

=

(a * b) + (a * c)

and

(b + c) * a

=

(b * a) + (c * a)

Coherence with toInteger

if the type also implements

GHC.Real.Integral

, then

fromInteger

is a left inverse for

toInteger

, i.e.

fromInteger (toInteger i) == i

Note that it isn't customarily expected that a type instance of both Num and Ord implement an ordered ring. Indeed, in base only Integer and Rational do.

Does the element occur in the structure?

Note: elem is often used in infix form.

Examples

Basic usage:

>>> 3 `elem` []False

>>> 3 `elem` [1,2]False

>>> 3 `elem` [1,2,3,4,5]True

For infinite structures, the default implementation of elem terminates if the sought-after value exists at a finite distance from the left side of the structure:

>>> 3 `elem` [1..]True

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

Left-associative fold of a structure, lazy in the accumulator. This is rarely what you want, but can work well for structures with efficient right-to-left sequencing and an operator that is lazy in its left argument.

In the case of lists, foldl, when applied to a binary operator, a starting value (typically the left-identity of the operator), and a list, reduces the list using the binary operator, from left to right:

foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn

Note that to produce the outermost application of the operator the entire input list must be traversed. Like all left-associative folds, foldl will diverge if given an infinite list.

If you want an efficient strict left-fold, you probably want to use foldl' instead of foldl. The reason for this is that the latter does not force the inner results (e.g. z `f` x1 in the above example) before applying them to the operator (e.g. to (`f` x2)). This results in a thunk chain O(n) elements long, which then must be evaluated from the outside-in.

For a general Foldable structure this should be semantically identical to:

foldl f z = foldl f z . toList

Examples

The first example is a strict fold, which in practice is best performed with foldl'.

>>> foldl (+) 42 [1,2,3,4]52

Though the result below is lazy, the input is reversed before prepending it to the initial accumulator, so corecursion begins only after traversing the entire input string.

>>> foldl (\acc c -> c : acc) "abcd" "efgh""hgfeabcd"

A left fold of a structure that is infinite on the right cannot terminate, even when for any finite input the fold just returns the initial accumulator:

>>> foldl (\a _ -> a) 0 $ repeat 1* Hangs forever *

WARNING: When it comes to lists, you always want to use either foldl' or foldr instead.

The largest element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the maximum in faster than linear time.

Examples

Basic usage:

>>> maximum [1..10]10

>>> maximum []*** Exception: Prelude.maximum: empty list

>>> maximum Nothing*** Exception: maximum: empty structure

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

The least element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the minimum in faster than linear time.

Examples

Basic usage:

>>> minimum [1..10]1

>>> minimum []*** Exception: Prelude.minimum: empty list

>>> minimum Nothing*** Exception: minimum: empty structure

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

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

Examples

Basic usage:

>>> product []1

>>> product [42]42

>>> product [1..10]3628800

>>> product [4.1, 2.0, 1.7]13.939999999999998

>>> product [1..]* Hangs forever *

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

Examples

Basic usage:

>>> sum []0

>>> sum [42]42

>>> sum [1..10]55

>>> sum [4.1, 2.0, 1.7]7.8

>>> sum [1..]* Hangs forever *

A functor with application, providing operations to

• embed pure expressions (pure), and

• sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id

liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

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 = (id <$ u) <*> v

• u <* v = liftA2 const u v

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

• fmap f x = pure f <*> x

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

• (*>) = (>>)

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

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:

Left identity

return a >>= k = k a

Right identity

m >>= return = m

Associativity

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

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

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

The above laws imply:

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

• (>>) = (*>)

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

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

The character type Char represents Unicode codespace and its elements are code points as in definitions D9 and D10 of the Unicode Standard.

Character literals in Haskell are single-quoted: 'Q', 'Я' or 'Ω'. To represent a single quote itself use '\'', and to represent a backslash use '\\'. The full grammar can be found in the section 2.6 of the Haskell 2010 Language Report.

To specify a character by its code point one can use decimal, hexadecimal or octal notation: '\65', '\x41' and '\o101' are all alternative forms of 'A'. The largest code point is '\x10ffff'.

There is a special escape syntax for ASCII control characters:

Data.Char provides utilities to work with Char.

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

The type Either String Int is the type of values which can be either a String or an Int. The Left constructor can be used only on Strings, and the Right constructor can be used only on Ints:

>>> let s = Left "foo" :: Either String Int>>> sLeft "foo">>> let n = Right 3 :: Either String Int>>> nRight 3>>> :type ss :: Either String Int>>> :type nn :: Either String Int

The fmap from our Functor instance will ignore Left values, but will apply the supplied function to values contained in a Right:

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

The Monad instance for Either allows us to chain together multiple actions which may fail, and fail overall if any of the individual steps failed. First we'll write a function that can either parse an Int from a Char, or fail.

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

The following should work, since both '1' and '2' can be parsed as Ints.

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

>>> parseMultipleRight 3

But the following should fail overall, since the first operation where we attempt to parse 'm' as an Int will fail:

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

>>> parseMultipleLeft "parse error"

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 Prelude.minBound and Prelude.maxBound from the Prelude.Bounded class.

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

Ord, as defined by the Haskell report, implements a total order and has the following properties:

Comparability

x <= y || y <= x

=

True

Transitivity

if

x <= y && y <= z

=

True

, then

x <= z

=

True

Reflexivity

x <= x

=

True

Antisymmetry

if

x <= y && y <= x

=

True

, then

x == y

=

True

The following operator interactions are expected to hold:

1. x >= y = y <= x

2. x < y = x <= y && x /= y

3. x > y = y < x

4. x < y = compare x y == LT

5. x > y = compare x y == GT

6. x == y = compare x y == EQ

7. min x y == if x <= y then x else y = True

8. max x y == if x >= y then x else y = True

Note that (7.) and (8.) do not require min and max to return either of their arguments. The result is merely required to equal one of the arguments in terms of (==).

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