Nix.Prelude

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

Collects the list of elements of a structure, from left to right.

Examples

Basic usage:

>>> biList (18, 42)[18,42]

>>> biList (Left 18)[18]

Determines whether all elements of the structure satisfy their appropriate predicate argument. Empty structures yield True.

Examples

Basic usage:

>>> biall even isDigit (27, 't')False

>>> biall even isDigit (26, '8')True

>>> biall even isDigit (Left 27)False

>>> biall even isDigit (Left 26)True

>>> biall even isDigit (BiList [26, 52] ['3', '8'])True

Empty structures yield True:

>>> biall even isDigit (BiList [] [])True

biand 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:

>>> biand (True, False)False

>>> biand (True, True)True

>>> biand (Left True)True

Empty structures yield True:

>>> biand (BiList [] [])True

A False value finitely far from the left end yields False (short circuit):

>>> biand (BiList [True, True, False, True] (repeat True))False

A False value infinitely far from the left end hangs:

> biand (BiList (repeat True) [False])
* Hangs forever *

An infinitely True value hangs:

> biand (BiList (repeat True) [])
* Hangs forever *

Determines whether any element of the structure satisfies its appropriate predicate argument. Empty structures yield False.

Examples

Basic usage:

>>> biany even isDigit (27, 't')False

>>> biany even isDigit (27, '8')True

>>> biany even isDigit (26, 't')True

>>> biany even isDigit (Left 27)False

>>> biany even isDigit (Left 26)True

>>> biany even isDigit (BiList [27, 53] ['t', '8'])True

Empty structures yield False:

>>> biany even isDigit (BiList [] [])False

The sum of a collection of actions, generalizing biconcat.

Examples

Basic usage:

>>> biasum (Nothing, Nothing)Nothing

>>> biasum (Nothing, Just 42)Just 42

>>> biasum (Just 18, Nothing)Just 18

>>> biasum (Just 18, Just 42)Just 18

Does the element occur in the structure?

Examples

Basic usage:

>>> bielem 42 (17, 42)True

>>> bielem 42 (17, 43)False

>>> bielem 42 (Left 42)True

>>> bielem 42 (Right 13)False

>>> bielem 42 (BiList [1..5] [1..100])True

>>> bielem 42 (BiList [1..5] [1..41])False

The bifind 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:

>>> bifind even (27, 53)Nothing

>>> bifind even (27, 52)Just 52

>>> bifind even (26, 52)Just 26

Empty structures always yield Nothing:

>>> bifind even (BiList [] [])Nothing

As bifoldl, but strict in the result of the reduction functions at each step.

This ensures that each step of the bifold is forced to weak head normal form before being applied, avoiding the collection of thunks that would otherwise occur. This is often what you want to strictly reduce a finite structure to a single, monolithic result (e.g., bilength).

Left associative monadic bifold over a structure.

Examples

Basic usage:

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 ("Hello", True)"Hello""True"42

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Right True)"True"42

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Left "Hello")"Hello"42

As bifoldr, but strict in the result of the reduction functions at each step.

Right associative monadic bifold over a structure.

As bitraverse_, but with the structure as the primary argument. For a version that doesn't ignore the results, see bifor.

Examples

Basic usage:

>>> bifor_ ("Hello", True) print (print . show)"Hello""True"

>>> bifor_ (Right True) print (print . show)"True"

>>> bifor_ (Left "Hello") print (print . show)"Hello"

Returns the size/length of a finite structure as an Int.

Examples

Basic usage:

>>> bilength (True, 42)2

>>> bilength (Right 42)1

>>> bilength (BiList [1,2,3] [4,5])5

>>> bilength (BiList [] [])0

On infinite structures, this function hangs:

> bilength (BiList [1..] [])
* Hangs forever *

Test whether the structure is empty.

Examples

Basic usage:

>>> binull (18, 42)False

>>> binull (Right 42)False

>>> binull (BiList [] [])True

bior 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:

>>> bior (True, False)True

>>> bior (False, False)False

>>> bior (Left True)True

Empty structures yield False:

>>> bior (BiList [] [])False

A True value finitely far from the left end yields True (short circuit):

>>> bior (BiList [False, False, True, False] (repeat False))True

A True value infinitely far from the left end hangs:

> bior (BiList (repeat False) [True])
* Hangs forever *

An infinitely False value hangs:

> bior (BiList (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 bisequence.

Examples

Basic usage:

>>> bisequence_ (print "Hello", print "World")"Hello""World"

>>> bisequence_ (Left (print "Hello"))"Hello"

>>> bisequence_ (Right (print "World"))"World"

Map each element of a structure using one of two actions, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results, see bitraverse.

Examples

Basic usage:

>>> bitraverse_ print (print . show) ("Hello", True)"Hello""True"

>>> bitraverse_ print (print . show) (Right True)"True"

>>> bitraverse_ print (print . show) (Left "Hello")"Hello"

A default definition of bifoldMap in terms of the Bitraversable operations.

bifoldMapDefault f g ≡
    getConst . bitraverse (Const . f) (Const . g)

bifor is bitraverse with the structure as the first argument. For a version that ignores the results, see bifor_.

Examples

Basic usage:

>>> bifor (Left []) listToMaybe (find even)Nothing

>>> bifor (Left [1, 2, 3]) listToMaybe (find even)Just (Left 1)

>>> bifor (Right [4, 5]) listToMaybe (find even)Just (Right 4)

>>> bifor ([1, 2, 3], [4, 5]) listToMaybe (find even)Just (1,4)

>>> bifor ([], [4, 5]) listToMaybe (find even)Nothing

A default definition of bimap in terms of the Bitraversable operations.

bimapDefault f g ≡
     runIdentity . bitraverse (Identity . f) (Identity . g)

Sequences all the actions in a structure, building a new structure with the same shape using the results of the actions. For a version that ignores the results, see bisequence_.

bisequence ≡ bitraverse id id

Examples

Basic usage:

>>> bisequence (Just 4, Nothing)Nothing

>>> bisequence (Just 4, Just 5)Just (4,5)

>>> bisequence ([1, 2, 3], [4, 5])[(1,4),(1,5),(2,4),(2,5),(3,4),(3,5)]

Case analysis for the Bool type. bool f t p evaluates to f when p is False, and evaluates to t when p is True.

This is equivalent to if p then t else f; that is, one can think of it as an if-then-else construct with its arguments reordered.

Examples

Basic usage:

>>> bool "foo" "bar" True"bar">>> bool "foo" "bar" False"foo"

Confirm that bool f t p and if p then t else f are equivalent:

>>> let p = True; f = "bar"; t = "foo">>> bool f t p == if p then t else fTrue>>> let p = False>>> bool f t p == if p then t else fTrue

This is >$ with its arguments flipped.

This is an infix version of contramap with the arguments flipped.

This is an infix alias for contramap.

Compare using compare.

Check for equivalence with ==.

Note: The instances for Double and Float violate reflexivity for NaN.

If f is both Functor and Contravariant then by the time you factor in the laws of each of those classes, it can't actually use its argument in any meaningful capacity.

This method is surprisingly useful. Where both instances exist and are lawful we have the following laws:

fmap      f ≡ phantom
contramap f ≡ phantom

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

A generalization of cycle to an arbitrary Semigroup. May fail to terminate for some values in some semigroups.

Examples

>>> take 10 $ cycle1 [1, 2, 3][1,2,3,1,2,3,1,2,3,1]

>>> cycle1 (Right 1)Right 1

>>> cycle1 (Left 1)* Hangs forever *

Repeat a value n times.

mtimesDefault n a = a <> a <> ... <> a  -- using <> (n-1) times

In many cases, stimes 0 a for a Monoid will produce mempty. However, there are situations when it cannot do so. In particular, the following situation is fairly common:

data T a = ...

class Constraint1 a
class Constraint1 a => Constraint2 a

instance Constraint1 a => Semigroup (T a)
instance Constraint2 a => Monoid (T a)

Since Constraint1 is insufficient to implement mempty, stimes for T a cannot do so.

When working with such a type, or when working polymorphically with Semigroup instances, mtimesDefault should be used when the multiplier might be zero. It is implemented using stimes when the multiplier is nonzero and mempty when it is zero.

Examples

>>> mtimesDefault 0 "bark"""

>>> mtimesDefault 3 "meow""meowmeowmeow"

O(n). Convert a ShortByteString into a ByteString.

O(n). Convert a ByteString into a ShortByteString.

This makes a copy, so does not retain the input string.

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.

deepseq: fully evaluates the first argument, before returning the second.

The name deepseq is used to illustrate the relationship to seq: where seq is shallow in the sense that it only evaluates the top level of its argument, deepseq traverses the entire data structure evaluating it completely.

deepseq can be useful for forcing pending exceptions, eradicating space leaks, or forcing lazy I/O to happen. It is also useful in conjunction with parallel Strategies (see the parallel package).

There is no guarantee about the ordering of evaluation. The implementation may evaluate the components of the structure in any order or in parallel. To impose an actual order on evaluation, use pseq from Control.Parallel in the parallel package.

($) 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]

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

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

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

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 ternary function to actions.

\mathcal{O}(n). map f xs is the list obtained by applying f to each element of xs, i.e.,

map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
map f [x1, x2, ...] == [f x1, f x2, ...]

this means that map id == id

Examples

>>> map (+1) [1, 2, 3][2,3,4]

>>> map id [1, 2, 3][1,2,3]

>>> map (\n -> 3 * n + 1) [1, 2, 3][4,7,10]

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:

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

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.

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]

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) == pure (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.

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]

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.

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

fix f is the least fixed point of the function f, i.e. the least defined x such that f x = x.

When f is strict, this means that because, by the definition of strictness, f ⊥ = ⊥ and such the least defined fixed point of any strict function is ⊥.

Examples

We can write the factorial function using direct recursion as

>>> let fac n = if n <= 1 then 1 else n * fac (n-1) in fac 5120

This uses the fact that Haskell’s let introduces recursive bindings. We can rewrite this definition using fix,

Instead of making a recursive call, we introduce a dummy parameter rec; when used within fix, this parameter then refers to fix’s argument, hence the recursion is reintroduced.

>>> fix (\rec n -> if n <= 1 then 1 else n * rec (n-1)) 5120

Using fix, we can implement versions of repeat as fix . (:) and cycle as fix . (++)

>>> take 10 $ fix (0:)[0,0,0,0,0,0,0,0,0,0]

>>> map (fix (\rec n -> if n < 2 then n else rec (n - 1) + rec (n - 2))) [1..10][1,1,2,3,5,8,13,21,34,55]

Implementation Details

The current implementation of fix uses structural sharing

fix f = let x = f x in x

A more straightforward but non-sharing version would look like

fix f = f (fix f)

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]

>>> maybeToList Nothing[]

One can use maybeToList to avoid pattern matching when combined with a function that (safely) works on lists:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> sum $ maybeToList (readMaybe "3")3>>> sum $ maybeToList (readMaybe "")0

The genericDrop function is an overloaded version of drop, which accepts any Integral value as the number of elements to drop.

\mathcal{O}(n). The genericLength function is an overloaded version of length. In particular, instead of returning an Int, it returns any type which is an instance of Num. It is, however, less efficient than length.

Examples

>>> genericLength [1, 2, 3] :: Int3>>> genericLength [1, 2, 3] :: Float3.0

Users should take care to pick a return type that is wide enough to contain the full length of the list. If the width is insufficient, the overflow behaviour will depend on the (+) implementation in the selected Num instance. The following example overflows because the actual list length of 200 lies outside of the Int8 range of -128..127.

>>> genericLength [1..200] :: Int8-56

The genericReplicate function is an overloaded version of replicate, which accepts any Integral value as the number of repetitions to make.

The genericSplitAt function is an overloaded version of splitAt, which accepts any Integral value as the position at which to split.

The genericTake function is an overloaded version of take, which accepts any Integral value as the number of elements to take.

The group function takes a list and returns a list of lists such that the concatenation of the result is equal to the argument. Moreover, each sublist in the result is non-empty, all elements are equal to the first one, and consecutive equal elements of the input end up in the same element of the output list.

group is a special case of groupBy, which allows the programmer to supply their own equality test.

It's often preferable to use Data.List.NonEmpty.group, which provides type-level guarantees of non-emptiness of inner lists. A common idiom to squash repeating elements map head . group is better served by map Data.List.NonEmpty.head . Data.List.NonEmpty.group because it avoids partial functions.

Examples

>>> group "Mississippi"["M","i","ss","i","ss","i","pp","i"]

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

The inits function returns all initial segments of the argument, shortest first.

inits is semantically equivalent to map reverse . scanl (flip (:)) [], but under the hood uses a queue to amortize costs of reverse.

Laziness

Note that inits has the following strictness property: inits (xs ++ _|_) = inits xs ++ _|_

In particular, inits _|_ = [] : _|_

Examples

>>> inits "abc"["","a","ab","abc"]

>>> inits [][[]]

inits is productive on infinite lists:

>>> take 5 $ inits [1..][[],[1],[1,2],[1,2,3],[1,2,3,4]]

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.

Laziness

intercalate has the following properties:

>>> take 5 (intercalate undefined ("Lorem" : undefined))"Lorem"

>>> take 6 (intercalate ", " ("Lorem" : undefined))"Lorem*** Exception: Prelude.undefined

Examples

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

>>> intercalate [0, 1] [[2, 3], [4, 5, 6], []][2,3,0,1,4,5,6,0,1]

>>> intercalate [1, 2, 3] [[], []][1,2,3]

\mathcal{O}(n). The intersperse function takes an element and a list and `intersperses' that element between the elements of the list.

Laziness

intersperse has the following properties

>>> take 1 (intersperse undefined ('a' : undefined))"a"

>>> take 2 (intersperse ',' ('a' : undefined))"a*** Exception: Prelude.undefined

Examples

>>> intersperse ',' "abcde""a,b,c,d,e"

>>> intersperse 1 [3, 4, 5][3,1,4,1,5]

\mathcal{O}(\min(m,n)). The isPrefixOf function takes two lists and returns True iff the first list is a prefix of the second.

Examples

>>> "Hello" `isPrefixOf` "Hello World!"True

>>> "Hello" `isPrefixOf` "Wello Horld!"False

For the result to be True, the first list must be finite; False, however, results from any mismatch:

>>> [0..] `isPrefixOf` [1..]False

>>> [0..] `isPrefixOf` [0..99]False

>>> [0..99] `isPrefixOf` [0..]True

>>> [0..] `isPrefixOf` [0..]* Hangs forever *

isPrefixOf shortcuts when the first argument is empty:

>>> isPrefixOf [] undefinedTrue

The permutations function returns the list of all permutations of the argument.

Note that the order of permutations is not lexicographic. It satisfies the following property:

map (take n) (take (product [1..n]) (permutations ([1..n] ++ undefined))) == permutations [1..n]

Laziness

The permutations function is maximally lazy: for each n, the value of permutations xs starts with those permutations that permute take n xs and keep drop n xs.

Examples

>>> permutations "abc"["abc","bac","cba","bca","cab","acb"]

>>> permutations [1, 2][[1,2],[2,1]]

>>> permutations [][[]]

This function is productive on infinite inputs:

>>> take 6 $ map (take 3) $ permutations ['a'..]["abc","bac","cba","bca","cab","acb"]

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.

Elements are arranged from lowest to highest, keeping duplicates in the order they appeared in the input.

The argument must be finite.

Examples

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

>>> sort "haskell""aehklls"

>>> import Data.Semigroup(Arg(..))>>> sort [Arg ":)" 0, Arg ":D" 0, Arg ":)" 1, Arg ":3" 0, Arg ":D" 1][Arg ":)" 0,Arg ":)" 1,Arg ":3" 0,Arg ":D" 0,Arg ":D" 1]

The sortBy function is the non-overloaded version of sort. The argument must be finite.

The supplied comparison relation is supposed to be reflexive and antisymmetric, otherwise, e. g., for _ _ -> GT, the ordered list simply does not exist. The relation is also expected to be transitive: if it is not then sortBy might fail to find an ordered permutation, even if it exists.

Examples

>>> sortBy (\(a,_) (b,_) -> compare a b) [(2, "world"), (4, "!"), (1, "Hello")][(1,"Hello"),(2,"world"),(4,"!")]

Sort a list by comparing the results of a key function applied to each element. sortOn f is equivalent to sortBy (comparing f), but has the performance advantage of only evaluating f once for each element in the input list. This is called the decorate-sort-undecorate paradigm, or Schwartzian transform.

Elements are arranged from lowest to highest, keeping duplicates in the order they appeared in the input.

The argument must be finite.

Examples

>>> sortOn fst [(2, "world"), (4, "!"), (1, "Hello")][(1,"Hello"),(2,"world"),(4,"!")]

>>> sortOn length ["jim", "creed", "pam", "michael", "dwight", "kevin"]["jim","pam","creed","kevin","dwight","michael"]

Performance notes

This function minimises the projections performed, by materialising the projections in an intermediate list.

For trivial projections, you should prefer using sortBy with comparing, for example:

>>> sortBy (comparing fst) [(3, 1), (2, 2), (1, 3)][(1,3),(2,2),(3,1)]

Or, for the exact same API as sortOn, you can use `sortBy . comparing`:

>>> (sortBy . comparing) fst [(3, 1), (2, 2), (1, 3)][(1,3),(2,2),(3,1)]

However, sortOn may still be faster for instances with a more efficient implementation of (>) than compare.

The subsequences function returns the list of all subsequences of the argument.

Laziness

subsequences does not look ahead unless it must:

>>> take 1 (subsequences undefined)[[]]>>> take 2 (subsequences ('a' : undefined))["","a"]

Examples

>>> subsequences "abc"["","a","b","ab","c","ac","bc","abc"]

This function is productive on infinite inputs:

>>> take 8 $ subsequences ['a'..]["","a","b","ab","c","ac","bc","abc"]

\mathcal{O}(n). The tails function returns all final segments of the argument, longest first.

Laziness

Note that tails has the following strictness property: tails _|_ = _|_ : _|_

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

>>> drop 1 (tails [undefined, 1, 2])[[1, 2], [2], []]

Examples

>>> tails "abc"["abc","bc","c",""]

>>> tails [1, 2, 3][[1,2,3],[2,3],[3],[]]

>>> tails [][[]]

The transpose function transposes the rows and columns of its argument.

Laziness

transpose is lazy in its elements

>>> take 1 (transpose ['a' : undefined, 'b' : undefined])["ab"]

Examples

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

If some of the rows are shorter than the following rows, their elements are skipped:

>>> transpose [[10,11],[20],[],[30,31,32]][[10,20,30],[11,31],[32]]

For this reason the outer list must be finite; otherwise transpose hangs:

>>> transpose (repeat [])* Hangs forever *

The unfoldr function is a `dual' to foldr: while foldr reduces a list to a summary value, unfoldr builds a list from a seed value. The function takes the element and returns Nothing if it is done producing the list or returns Just (a,b), in which case, a is a prepended to the list and b is used as the next element in a recursive call. For example,

iterate f == unfoldr (\x -> Just (x, f x))

In some cases, unfoldr can undo a foldr operation:

unfoldr f' (foldr f z xs) == xs

if the following holds:

f' (f x y) = Just (x,y)
f' z       = Nothing

Laziness

>>> take 1 (unfoldr (\x -> Just (x, undefined)) 'a')"a"

Examples

>>> unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10[10,9,8,7,6,5,4,3,2,1]

>>> take 10 $ unfoldr (\(x, y) -> Just (x, (y, x + y))) (0, 1)[0,1,1,2,3,5,8,13,21,54]

comparing p x y = compare (p x) (p y)

Useful combinator for use in conjunction with the xxxBy family of functions from Data.List, for example:

  ... sortBy (comparing fst) ...

This is a valid definition of stimes for an idempotent Semigroup.

When x <> x = x, this definition should be preferred, because it works in \mathcal{O}(1) rather than \mathcal{O}(\log n).

This is a valid definition of stimes for an idempotent Monoid.

When x <> x = x, this definition should be preferred, because it works in \mathcal{O}(1) rather than \mathcal{O}(\log n)

This is a valid definition of stimes for a Monoid.

Unlike the default definition of stimes, it is defined for 0 and so it should be preferred where possible.

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

The mapAccumL function behaves like a combination of fmap and foldl; it applies a function to each element of a structure, passing an accumulating parameter from left to right, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumL (\a b -> (a + b, a)) 0 [1..10](55,[0,1,3,6,10,15,21,28,36,45])

>>> mapAccumL (\a b -> (a <> show b, a)) "0" [1..5]("012345",["0","01","012","0123","01234"])

The mapAccumR function behaves like a combination of fmap and foldr; it applies a function to each element of a structure, passing an accumulating parameter from right to left, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumR (\a b -> (a + b, a)) 0 [1..10](55,[54,52,49,45,40,34,27,19,10,0])

>>> mapAccumR (\a b -> (a <> show b, a)) "0" [1..5]("054321",["05432","0543","054","05","0"])

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.

Swap the components 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]

Get a trace of the current execution stack state.

Returns Nothing if stack trace support isn't available on host machine.

Get a string representation of the current execution stack state.

The sortWith function sorts a list of elements using the user supplied function to project something out of each element

In general if the user supplied function is expensive to compute then you should probably be using sortOn, as it only needs to compute it once for each element. sortWith, on the other hand must compute the mapping function for every comparison that it performs.

stderr is a handle managing the programs standard error.

stdin is a handle managing the programs standard input.

stdout is a handle managing the programs standard output.

The computation withFile path mode action opens the file and runs action with the obtained handle before closing the file.

Even when an exception is raised within the action, the file will still be closed. This is why withFile path mode act is preferable to

openFile path mode >>= (\hdl -> act hdl >>= System.IO.hClose hdl)

See also: System.IO.bracket

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],[])

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}(n). filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; i.e.,

filter p xs = [ x | x <- xs, p x]

Examples

>>> filter odd [1, 2, 3][1,3]

>>> filter (\l -> length l > 3) ["Hello", ", ", "World", "!"]["Hello","World"]

>>> filter (/= 3) [1, 2, 3, 4, 3, 2, 1][1,2,4,2,1]

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 element. See iterate' for a strict variant of this function.

>>> let xs = iterate (\x -> if x == 0 then undefined else x - 1) 2>>> xs[2,1,0,*** Exception: Prelude.undefined>>> length (take 10 xs)10

In xs every element following 0 is bottom, but the list itself is infinitely long because it is generated without forcing its elements.

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]

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]

>>> take 1 (scanl undefined 'a' undefined)"a"

\mathcal{O}(n). A strict version of scanl.

\mathcal{O}(n). scanl1 is a variant of scanl that has no starting value argument:

scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]

Examples

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

>>> scanl1 (+) [][]

>>> scanl1 (-) [1..4][1,-1,-4,-8]

>>> scanl1 (&&) [True, False, True, True][True,False,False,False]

>>> scanl1 (||) [False, False, True, True][False,False,True,True]

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

>>> take 1 (scanl1 undefined ('a' : undefined))"a"

\mathcal{O}(n). scanr is the right-to-left dual of scanl. Note that the order of parameters on the accumulating function are reversed compared to scanl. Also note that

head (scanr f z xs) == foldr f z xs.

Examples

>>> scanr (+) 0 [1..4][10,9,7,4,0]

>>> scanr (+) 42 [][42]

>>> scanr (-) 100 [1..4][98,-97,99,-96,100]

>>> scanr (\nextChar reversedString -> nextChar : reversedString) "foo" ['a', 'b', 'c', 'd']["abcdfoo","bcdfoo","cdfoo","dfoo","foo"]

>>> force $ scanr (+) 0 [1..]*** Exception: stack overflow

\mathcal{O}(n). scanr1 is a variant of scanr that has no starting value argument.

Examples

>>> scanr1 (+) [1..4][10,9,7,4]

>>> scanr1 (+) [][]

>>> scanr1 (-) [1..4][-2,3,-1,4]

>>> scanr1 (&&) [True, False, True, True][False,False,True,True]

>>> scanr1 (||) [True, True, False, False][True,True,False,False]

>>> force $ scanr1 (+) [1..]*** Exception: stack overflow

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

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

Laziness

>>> span undefined []([],[])>>> fst (span (const False) undefined)*** Exception: Prelude.undefined>>> fst (span (const False) (undefined : undefined))[]>>> take 1 (fst (span (const True) (1 : undefined)))[1]

span produces the first component of the tuple lazily:

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

Examples

>>> span (< 3) [1,2,3,4,1,2,3,4]([1,2],[3,4,1,2,3,4])

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

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

splitAt n xs returns a tuple where first element is xs prefix of length n and second element is the remainder of the list:

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

Laziness

It is equivalent to (take n xs, drop n xs) unless n is _|_: splitAt _|_ xs = _|_, not (_|_, _|_)).

The first component of the tuple is produced lazily:

>>> fst (splitAt 0 undefined)[]

>>> take 1 (fst (splitAt 10 (1 : undefined)))[1]

Examples

>>> splitAt 6 "Hello World!"("Hello ","World!")

>>> splitAt 3 [1,2,3,4,5]([1,2,3],[4,5])

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

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

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

>>> splitAt 0 [1,2,3]([],[1,2,3])

>>> splitAt (-1) [1,2,3]([],[1,2,3])

take n, applied to a list xs, returns the prefix of xs of length n, or xs itself if n >= length xs.

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

Laziness

>>> take 0 undefined[]>>> take 2 (1 : 2 : undefined)[1,2]

Examples

>>> take 5 "Hello World!""Hello"

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

>>> take 3 [1,2][1,2]

>>> take 3 [][]

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

>>> take 0 [1,2][]

takeWhile, applied to a predicate p and a list xs, returns the longest prefix (possibly empty) of xs of elements that satisfy p.

Laziness

>>> takeWhile (const False) undefined*** Exception: Prelude.undefined

>>> takeWhile (const False) (undefined : undefined)[]

>>> take 1 (takeWhile (const True) (1 : undefined))[1]

Examples

>>> takeWhile (< 3) [1,2,3,4,1,2,3,4][1,2]

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

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

\mathcal{O}(1). Decompose a list into its head and tail.

• If the list is empty, returns Nothing.

• If the list is non-empty, returns Just (x, xs), where x is the head of the list and xs its tail.

Examples

>>> uncons []Nothing

>>> uncons [1]Just (1,[])

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

unzip transforms a list of pairs into a list of first components and a list of second components.

Examples

>>> unzip []([],[])

>>> unzip [(1, 'a'), (2, 'b')]([1,2],"ab")

The unzip3 function takes a list of triples and returns three lists of the respective components, analogous to unzip.

Examples

>>> unzip3 []([],[],[])

>>> unzip3 [(1, 'a', True), (2, 'b', False)]([1,2],"ab",[True,False])

\mathcal{O}(\min(m,n)). zip takes two lists and returns a list of corresponding pairs.

zip is right-lazy:

>>> zip [] undefined[]>>> zip undefined []*** Exception: Prelude.undefined...

zip is capable of list fusion, but it is restricted to its first list argument and its resulting list.

Examples

>>> zip [1, 2, 3] ['a', 'b', 'c'][(1,'a'),(2,'b'),(3,'c')]

If one input list is shorter than the other, excess elements of the longer list are discarded, even if one of the lists is infinite:

>>> zip [1] ['a', 'b'][(1,'a')]

>>> zip [1, 2] ['a'][(1,'a')]

>>> zip [] [1..][]

>>> zip [1..] [][]

zip3 takes three lists and returns a list of triples, analogous to zip. It is capable of list fusion, but it is restricted to its first list argument and its resulting list.

\mathcal{O}(\min(m,n)). zipWith generalises zip by zipping with the function given as the first argument, instead of a tupling function.

zipWith (,) xs ys == zip xs ys
zipWith f [x1,x2,x3..] [y1,y2,y3..] == [f x1 y1, f x2 y2, f x3 y3..]

zipWith is right-lazy:

>>> let f = undefined>>> zipWith f [] undefined[]

zipWith is capable of list fusion, but it is restricted to its first list argument and its resulting list.

Examples

zipWith (+) can be applied to two lists to produce the list of corresponding sums:

>>> zipWith (+) [1, 2, 3] [4, 5, 6][5,7,9]

>>> zipWith (++) ["hello ", "foo"] ["world!", "bar"]["hello world!","foobar"]

the same as flip (-).

Because - is treated specially in the Haskell grammar, (- e) is not a section, but an application of prefix negation. However, (subtract exp) is equivalent to the disallowed section.

raise a number to a non-negative integral power

raise a number to an integral power

Extract the denominator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

General coercion from Integral types.

WARNING: This function performs silent truncation if the result type is not at least as big as the argument's type.

gcd x y is the non-negative factor of both x and y of which every common factor of x and y is also a factor; for example gcd 4 2 = 2, gcd (-4) 6 = 2, gcd 0 4 = 4. gcd 0 0 = 0. (That is, the common divisor that is "greatest" in the divisibility preordering.)

Note: Since for signed fixed-width integer types, abs minBound < 0, the result may be negative if one of the arguments is minBound (and necessarily is if the other is 0 or minBound) for such types.

lcm x y is the smallest positive integer that both x and y divide.

Extract the numerator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

General coercion to Fractional types.

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.

Create a new TVar holding a value supplied

Return the current value stored in a TVar.

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.

Write the supplied value into a TVar.

Return the current CallStack.

Does *not* include the call-site of callStack.

Pretty print a CallStack.

Pretty print a SrcLoc.

Perform some computation without adding new entries to the CallStack.

Returns a [String] representing the current call stack. This can be useful for debugging.

The implementation uses the call-stack simulation maintained by the profiler, so it only works if the program was compiled with -prof and contains suitable SCC annotations (e.g. by using -fprof-auto). Otherwise, the list returned is likely to be empty or uninformative.

Extract a list of call-sites from the CallStack.

The list is ordered by most recent call.

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

>>> readMaybe "123" :: Maybe IntJust 123

>>> readMaybe "hello" :: Maybe IntNothing

equivalent to readsPrec with a precedence of 0.

Convert an integer into an unknown type-level natural.

Reverse order of bytes in Word16.

Reverse order of bytes in Word32.

Reverse order of bytes in Word64.