Test.Hspec.Discover

Unary negation.

Absolute value.

Sign of a number. The functions abs and signum should satisfy the law:

abs x * signum x == x

For real numbers, the signum is either -1 (negative), 0 (zero) or 1 (positive).

Conversion from an Integer. An integer literal represents the application of the function fromInteger to the appropriate value of type Integer, so such literals have type (Num a) => a.

Map each element of the structure into a monoid, and combine the results with (<>). This fold is right-associative and lazy in the accumulator. For strict left-associative folds consider foldMap' instead.

Examples

Basic usage:

>>> foldMap Sum [1, 3, 5]Sum {getSum = 9}

>>> foldMap Product [1, 3, 5]Product {getProduct = 15}

>>> foldMap (replicate 3) [1, 2, 3][1,1,1,2,2,2,3,3,3]

When a Monoid's (<>) is lazy in its second argument, foldMap can return a result even from an unbounded structure. For example, lazy accumulation enables Data.ByteString.Builder to efficiently serialise large data structures and produce the output incrementally:

>>> import qualified Data.ByteString.Lazy as L>>> import qualified Data.ByteString.Builder as B>>> let bld :: Int -> B.Builder; bld i = B.intDec i <> B.word8 0x20>>> let lbs = B.toLazyByteString $ foldMap bld [0..]>>> L.take 64 lbs"0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24"

Right-associative fold of a structure, lazy in the accumulator.

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

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

Note that since the head of the resulting expression is produced by an application of the operator to the first element of the list, given an operator lazy in its right argument, foldr can produce a terminating expression from an unbounded list.

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

foldr f z = foldr f z . toList

Examples

Basic usage:

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

>>> foldr (||) False []False

>>> foldr (\c acc -> acc ++ [c]) "foo" ['a', 'b', 'c', 'd']"foodcba"

Infinite structures

⚠️ Applying foldr to infinite structures usually doesn't terminate.

It may still terminate under one of the following conditions:

• the folding function is short-circuiting

• the folding function is lazy on its second argument

Short-circuiting

(||) short-circuits on True values, so the following terminates because there is a True value finitely far from the left side:

>>> foldr (||) False (True : repeat False)True

But the following doesn't terminate:

>>> foldr (||) False (repeat False ++ [True])* Hangs forever *

Laziness in the second argument

Applying foldr to infinite structures terminates when the operator is lazy in its second argument (the initial accumulator is never used in this case, and so could be left undefined, but [] is more clear):

>>> take 5 $ foldr (\i acc -> i : fmap (+3) acc) [] (repeat 1)[1,4,7,10,13]

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.

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

This ensures that each step of the fold 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 strict result (e.g. sum).

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

foldl' f z = foldl' f z . toList

A variant of foldr that has no base case, and thus may only be applied to non-empty structures.

This function is non-total and will raise a runtime exception if the structure happens to be empty.

Examples

Basic usage:

>>> foldr1 (+) [1..4]10

>>> foldr1 (+) []Exception: Prelude.foldr1: empty list

>>> foldr1 (+) Nothing*** Exception: foldr1: empty structure

>>> foldr1 (-) [1..4]-2

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

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

>>> foldr1 (+) [1..]* Hangs forever *

A variant of foldl that has no base case, and thus may only be applied to non-empty structures.

This function is non-total and will raise a runtime exception if the structure happens to be empty.

foldl1 f = foldl1 f . toList

Examples

Basic usage:

>>> foldl1 (+) [1..4]10

>>> foldl1 (+) []*** Exception: Prelude.foldl1: empty list

>>> foldl1 (+) Nothing*** Exception: foldl1: empty structure

>>> foldl1 (-) [1..4]-8

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

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

>>> foldl1 (+) [1..]* Hangs forever *

Test whether the structure is empty. The default implementation is Left-associative and lazy in both the initial element and the accumulator. Thus optimised for structures where the first element can be accessed in constant time. Structures where this is not the case should have a non-default implementation.

Examples

Basic usage:

>>> null []True

>>> null [1]False

null is expected to terminate even for infinite structures. The default implementation terminates provided the structure is bounded on the left (there is a leftmost element).

>>> null [1..]False

Returns the size/length of a finite structure as an Int. The default implementation just counts elements starting with the leftmost. Instances for structures that can compute the element count faster than via element-by-element counting, should provide a specialised implementation.

Examples

Basic usage:

>>> length []0

>>> length ['a', 'b', 'c']3>>> length [1..]* Hangs forever *

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 *

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

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 *

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

'as >>= bs' can be understood as the do expression

do a <- as
   bs a

An alternative name for this function is 'bind', but some people may refer to it as 'flatMap', which results from it being equivialent to

\x f -> join (fmap f x) :: Monad m => m a -> (a -> m b) -> m b

which can be seen as mapping a value with Monad m => m a -> m (m b) and then 'flattening' m (m b) to m b using join.

Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages.

'as >> bs' can be understood as the do expression

do as
   bs

or in terms of (>>=) as

as >>= const bs

Inject a value into the monadic type. This function should not be different from its default implementation as pure. The justification for the existence of this function is merely historic.

Lift a value into the Structure.

Examples

>>> pure 1 :: Maybe IntJust 1

>>> pure 'z' :: [Char]"z"

>>> pure (pure ":D") :: Maybe [String]Just [":D"]

Sequential application.

A few functors support an implementation of <*> that is more efficient than the default one.

Example

Used in combination with (Data.Functor.<$>), (<*>) can be used to build a record.

>>> data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}

>>> produceFoo :: Applicative f => f Foo>>> produceBar :: Applicative f => f Bar>>> produceBaz :: Applicative f => f Baz

>>> mkState :: Applicative f => f MyState>>> mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz

Lift a binary function to actions.

Some functors support an implementation of liftA2 that is more efficient than the default one. In particular, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap over the structure and then use <*>.

This became a typeclass method in 4.10.0.0. Prior to that, it was a function defined in terms of <*> and fmap.

Example

>>> liftA2 (,) (Just 3) (Just 5)Just (3,5)

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

Sequence actions, discarding the value of the first argument.

Examples

If used in conjunction with the Applicative instance for Maybe, you can chain Maybe computations, with a possible "early return" in case of Nothing.

>>> Just 2 *> Just 3Just 3

>>> Nothing *> Just 3Nothing

Of course a more interesting use case would be to have effectful computations instead of just returning pure values.

>>> import Data.Char>>> import GHC.Internal.Text.ParserCombinators.ReadP>>> let p = string "my name is " *> munch1 isAlpha <* eof>>> readP_to_S p "my name is Simon"[("Simon","")]

Sequence actions, discarding the value of the second argument.

An associative operation.

Examples

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

>>> Just [1, 2, 3] <> Just [4, 5, 6]Just [1,2,3,4,5,6]

>>> putStr "Hello, " <> putStrLn "World!"Hello, World!

Map each element of a structure to an action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see traverse_.

Examples

Basic usage:

In the first two examples we show each evaluated action mapping to the output structure.

>>> traverse Just [1,2,3,4]Just [1,2,3,4]

>>> traverse id [Right 1, Right 2, Right 3, Right 4]Right [1,2,3,4]

In the next examples, we show that Nothing and Left values short circuit the created structure.

>>> traverse (const Nothing) [1,2,3,4]Nothing

>>> traverse (\x -> if odd x then Just x else Nothing)  [1,2,3,4]Nothing

>>> traverse id [Right 1, Right 2, Right 3, Right 4, Left 0]Left 0

Evaluate each action in the structure from left to right, and collect the results. For a version that ignores the results see sequenceA_.

Examples

Basic usage:

For the first two examples we show sequenceA fully evaluating a a structure and collecting the results.

>>> sequenceA [Just 1, Just 2, Just 3]Just [1,2,3]

>>> sequenceA [Right 1, Right 2, Right 3]Right [1,2,3]

The next two example show Nothing and Just will short circuit the resulting structure if present in the input. For more context, check the Traversable instances for Either and Maybe.

>>> sequenceA [Just 1, Just 2, Just 3, Nothing]Nothing

>>> sequenceA [Right 1, Right 2, Right 3, Left 4]Left 4

Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see Data.Foldable.mapM_.

Examples

mapM is literally a traverse with a type signature restricted to Monad. Its implementation may be more efficient due to additional power of Monad.

Evaluate each monadic action in the structure from left to right, and collect the results. For a version that ignores the results see Data.Foldable.sequence_.

Examples

Basic usage:

The first two examples are instances where the input and and output of sequence are isomorphic.

>>> sequence $ Right [1,2,3,4][Right 1,Right 2,Right 3,Right 4]

>>> sequence $ [Right 1,Right 2,Right 3,Right 4]Right [1,2,3,4]

The following examples demonstrate short circuit behavior for sequence.

>>> sequence $ Left [1,2,3,4]Left [1,2,3,4]

>>> sequence $ [Left 0, Right 1,Right 2,Right 3,Right 4]Left 0

fmap is used to apply a function of type (a -> b) to a value of type f a, where f is a functor, to produce a value of type f b. Note that for any type constructor with more than one parameter (e.g., Either), only the last type parameter can be modified with fmap (e.g., b in `Either a b`).

Some type constructors with two parameters or more have a Data.Bifunctor instance that allows both the last and the penultimate parameters to be mapped over.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> fmap show NothingNothing>>> fmap show (Just 3)Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> fmap show (Left 17)Left 17>>> fmap show (Right 17)Right "17"

Double each element of a list:

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

Apply even to the second element of a pair:

>>> fmap even (2,2)(2,True)

It may seem surprising that the function is only applied to the last element of the tuple compared to the list example above which applies it to every element in the list. To understand, remember that tuples are type constructors with multiple type parameters: a tuple of 3 elements (a,b,c) can also be written (,,) a b c and its Functor instance is defined for Functor ((,,) a b) (i.e., only the third parameter is free to be mapped over with fmap).

It explains why fmap can be used with tuples containing values of different types as in the following example:

>>> fmap even ("hello", 1.0, 4)("hello",1.0,True)

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

Perform a computation with Maybe and replace the result with a constant value if it is Just:

>>> 'a' <$ Just 2Just 'a'>>> 'a' <$ NothingNothing