System.Directory.Internal.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

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 Foldable class represents data structures that can be reduced to a summary value one element at a time. Strict left-associative folds are a good fit for space-efficient reduction, while lazy right-associative folds are a good fit for corecursive iteration, or for folds that short-circuit after processing an initial subsequence of the structure's elements.

Instances can be derived automatically by enabling the DeriveFoldable extension. For example, a derived instance for a binary tree might be:

{-# LANGUAGE DeriveFoldable #-}
data Tree a = Empty
            | Leaf a
            | Node (Tree a) a (Tree a)
    deriving Foldable

A more detailed description can be found in the Overview section of Data.Foldable#overview.

For the class laws see the Laws section of Data.Foldable#laws.

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 class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

Right identity

x <> mempty = x

Left identity

mempty <> x = x

Associativity

x <> (y <> z) = (x <> y) <> z

(

Semigroup

law)

Concatenation

mconcat = foldr (<>) mempty

You can alternatively define mconcat instead of mempty, in which case the laws are:

Unit

mconcat (pure x) = x

Multiplication

mconcat (join xss) = mconcat (fmap mconcat xss)

Subclass

mconcat (toList xs) = sconcat xs

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. Data.Semigroup.Sum and Data.Semigroup.Product.

NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

Functors representing data structures that can be transformed to structures of the same shape by performing an Applicative (or, therefore, Monad) action on each element from left to right.

A more detailed description of what same shape means, the various methods, how traversals are constructed, and example advanced use-cases can be found in the Overview section of Data.Traversable#overview.

For the class laws see the Laws section of Data.Traversable#laws.

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 Prelude.>> and Prelude.>>= operations from the Prelude.Monad class.

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.

The class of semigroups (types with an associative binary operation).

Instances should satisfy the following:

Associativity

x <> (y <> z) = (x <> y) <> z

You can alternatively define sconcat instead of (<>), in which case the laws are:

Unit

sconcat (pure x) = x

Multiplication

sconcat (join xss) = sconcat (fmap sconcat xss)

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

In Haskell 2010, this is an opaque type.

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)

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.

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

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

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.

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"

Identity function.

id x = x

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

Examples

>>> length $ filter id [True, True, False, True]3

>>> Just (Just 3) >>= idJust 3

>>> foldr id 0 [(^3), (*5), (+2)]1000

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

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

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

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.

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

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)

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

Splits the argument into a list of lines stripped of their terminating \n characters. The \n terminator is optional in a final non-empty line of the argument string.

When the argument string is empty, or ends in a \n character, it can be recovered by passing the result of lines to the unlines function. Otherwise, unlines appends the missing terminating \n. This makes unlines . lines idempotent:

(unlines . lines) . (unlines . lines) = (unlines . lines)

Examples

>>> lines ""           -- empty input contains no lines[]

>>> lines "\n"         -- single empty line[""]

>>> lines "one"        -- single unterminated line["one"]

>>> lines "one\n"      -- single non-empty line["one"]

>>> lines "one\n\n"    -- second line is empty["one",""]

>>> lines "one\ntwo"   -- second line is unterminated["one","two"]

>>> lines "one\ntwo\n" -- two non-empty lines["one","two"]

Appends a \n character to each input string, then concatenates the results. Equivalent to foldMap (s -> s ++ "\n").

Examples

>>> unlines ["Hello", "World", "!"]"Hello\nWorld\n!\n"

Note that unlines . lines /= id when the input is not \n-terminated:

>>> unlines . lines $ "foo\nbar""foo\nbar\n"

unwords joins words with separating spaces (U+0020 SPACE).

unwords is neither left nor right inverse of words:

>>> words (unwords [" "])[]>>> unwords (words "foo\nbar")"foo bar"

Examples

>>> unwords ["Lorem", "ipsum", "dolor"]"Lorem ipsum dolor"

>>> unwords ["foo", "bar", "", "baz"]"foo bar  baz"

words breaks a string up into a list of words, which were delimited by white space (as defined by isSpace). This function trims any white spaces at the beginning and at the end.

Examples

>>> words "Lorem ipsum\ndolor"["Lorem","ipsum","dolor"]

>>> words " foo bar "["foo","bar"]

Convert an uncurried function to a curried function.

Examples

>>> curry fst 1 21

Extract the first component of a pair.

Extract the second component of a pair.

uncurry converts a curried function to a function on pairs.

Examples

>>> uncurry (+) (1,2)3

>>> uncurry ($) (show, 1)"1"

>>> map (uncurry max) [(1,2), (3,4), (6,8)][2,4,8]

error stops execution and displays an error message.

A variant of error that does not produce a stack trace.

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.

Raise an IOError in the IO monad.

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

WARNING: This function is partial, and should only be used if you are sure that the indexing will not fail. Otherwise, use !?.

WARNING: This function takes linear time in the index.

Examples

>>> ['a', 'b', 'c'] !! 0'a'

>>> ['a', 'b', 'c'] !! 2'c'

>>> ['a', 'b', 'c'] !! 3*** Exception: Prelude.!!: index too large

>>> ['a', 'b', 'c'] !! (-1)*** Exception: Prelude.!!: negative index

break, applied to a predicate p and a list xs, returns a tuple where first element is longest prefix (possibly empty) of xs of elements that do not satisfy p and second element is the remainder of the list:

break p is equivalent to span (not . p) and consequently to (takeWhile (not . p) xs, dropWhile (not . p) xs), even if p is _|_.

Laziness

>>> break undefined []([],[])

>>> fst (break (const True) undefined)*** Exception: Prelude.undefined

>>> fst (break (const True) (undefined : undefined))[]

>>> take 1 (fst (break (const False) (1 : undefined)))[1]

break produces the first component of the tuple lazily:

>>> take 10 (fst (break (const False) [1..]))[1,2,3,4,5,6,7,8,9,10]

Examples

>>> break (> 3) [1,2,3,4,1,2,3,4]([1,2,3],[4,1,2,3,4])

>>> break (< 9) [1,2,3]([],[1,2,3])

>>> break (> 9) [1,2,3]([1,2,3],[])

cycle ties a finite list into a circular one, or equivalently, the infinite repetition of the original list. It is the identity on infinite lists.

Examples

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

>>> take 10 (cycle [42])[42,42,42,42,42,42,42,42,42,42]

>>> take 10 (cycle [2, 5, 7])[2,5,7,2,5,7,2,5,7,2]

>>> take 1 (cycle (42 : undefined))[42]

drop n xs returns the suffix of xs after the first n elements, or [] if n >= length xs.

It is an instance of the more general genericDrop, in which n may be of any integral type.

Examples

>>> drop 6 "Hello World!""World!"

>>> drop 3 [1,2,3,4,5][4,5]

>>> drop 3 [1,2][]

>>> drop 3 [][]

>>> drop (-1) [1,2][1,2]

>>> drop 0 [1,2][1,2]

dropWhile p xs returns the suffix remaining after takeWhile p xs.

Examples

>>> dropWhile (< 3) [1,2,3,4,5,1,2,3][3,4,5,1,2,3]

>>> dropWhile (< 9) [1,2,3][]

>>> dropWhile (< 0) [1,2,3][1,2,3]

\mathcal{O}(1). Extract the first element of a list, which must be non-empty.

To disable the warning about partiality put {-# OPTIONS_GHC -Wno-x-partial -Wno-unrecognised-warning-flags #-} at the top of the file. To disable it throughout a package put the same options into ghc-options section of Cabal file. To disable it in GHCi put :set -Wno-x-partial -Wno-unrecognised-warning-flags into ~/.ghci config file. See also the migration guide.

Examples

>>> head [1, 2, 3]1

>>> head [1..]1

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

\mathcal{O}(n). Return all the elements of a list except the last one. The list must be non-empty.

WARNING: This function is partial. Consider using unsnoc instead.

Examples

>>> init [1, 2, 3][1,2]

>>> init [1][]

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

iterate f x returns an infinite list of repeated applications of f to x:

iterate f x == [x, f x, f (f x), ...]

Laziness

Note that iterate is lazy, potentially leading to thunk build-up if the consumer doesn't force each iterate. See iterate' for a strict variant of this function.

>>> take 1 $ iterate undefined 42[42]

Examples

>>> take 10 $ iterate not True[True,False,True,False,True,False,True,False,True,False]

>>> take 10 $ iterate (+3) 42[42,45,48,51,54,57,60,63,66,69]

iterate id == repeat:

>>> take 10 $ iterate id 1[1,1,1,1,1,1,1,1,1,1]

\mathcal{O}(n). Extract the last element of a list, which must be finite and non-empty.

WARNING: This function is partial. Consider using unsnoc instead.

Examples

>>> last [1, 2, 3]3

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

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

\mathcal{O}(n). lookup key assocs looks up a key in an association list. For the result to be Nothing, the list must be finite.

Examples

>>> lookup 2 []Nothing

>>> lookup 2 [(1, "first")]Nothing

>>> lookup 2 [(1, "first"), (2, "second"), (3, "third")]Just "second"

repeat x is an infinite list, with x the value of every element.

Examples

>>> take 10 $ repeat 17[17,17,17,17,17,17,17,17,17, 17]

>>> repeat undefined[*** Exception: Prelude.undefined

replicate n x is a list of length n with x the value of every element. It is an instance of the more general genericReplicate, in which n may be of any integral type.

Examples

>>> replicate 0 True[]

>>> replicate (-1) True[]

>>> replicate 4 True[True,True,True,True]

\mathcal{O}(n). reverse xs returns the elements of xs in reverse order. xs must be finite.

Laziness

reverse is lazy in its elements.

>>> head (reverse [undefined, 1])1

>>> reverse (1 : 2 : undefined)*** Exception: Prelude.undefined

Examples

>>> reverse [][]

>>> reverse [42][42]

>>> reverse [2,5,7][7,5,2]

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

\mathcal{O}(n). scanl is similar to foldl, but returns a list of successive reduced values from the left:

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

Note that

last (scanl f z xs) == foldl f z xs

Examples

>>> scanl (+) 0 [1..4][0,1,3,6,10]

>>> scanl (+) 42 [][42]

>>> scanl (-) 100 [1..4][100,99,97,94,90]

>>> scanl (\reversedString nextChar -> nextChar : reversedString) "foo" ['a', 'b', 'c', 'd']["foo","afoo","bafoo","cbafoo","dcbafoo"]

>>> take 10 (scanl (+) 0 [1..])[0,1,3,6,10,15,21,28,36,45]