RIO.Prelude

Boolean "or", lazy in the second argument

Boolean "and", lazy in the second argument

Boolean "not"

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

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

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

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

Get a First value with a default fallback

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

Examples

Basic usage:

>>> isJust (Just 3)True

>>> isJust (Just ())True

>>> isJust NothingFalse

Only the outer constructor is taken into consideration:

>>> isJust (Just Nothing)True

The isNothing function returns True iff its argument is Nothing.

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

Applicative mapMaybe.

Monadic mapMaybe.

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

Apply a function to a Left constructor

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]

Extract the first component of a pair.

Extract the second component of a pair.

Convert an uncurried function to a curried function.

Examples

>>> curry fst 1 21

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]

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

The Down type allows you to reverse sort order conveniently. A value of type Down a contains a value of type a (represented as Down a).

If a has an Ord instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: then sortWith by Down x.

>>> compare True FalseGT

>>> compare (Down True) (Down False)LT

If a has a Bounded instance then the wrapped instance also respects the reversed ordering by exchanging the values of minBound and maxBound.

>>> minBound :: Int-9223372036854775808

>>> minBound :: Down IntDown 9223372036854775807

All other instances of Down a behave as they do for a.

Convert to an Int. It is implementation-dependent what fromEnum returns when applied to a value that is too large to fit in an Int.

raise a number to a non-negative integral power

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.

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.

Rational equivalent of its real argument with full precision.

Integer division truncated toward zero.

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Integer remainder, satisfying

(x `quot` y)*y + (x `rem` y) == x

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Integer division truncated toward negative infinity.

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Integer modulus, satisfying

(x `div` y)*y + (x `mod` y) == x

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Simultaneous quot and rem.

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

simultaneous div and mod.

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Conversion to Integer.

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.

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.

Fractional division.

raise a number to an integral power

Reciprocal fraction.

Conversion from a Rational (that is Ratio Integer). A floating literal stands for an application of fromRational to a value of type Rational, so such literals have type (Fractional a) => a.

General coercion to Fractional types.

WARNING: This function goes through the Rational type, which does not have values for NaN for example. This means it does not round-trip.

For Double it also behaves differently with or without -O0:

Prelude> realToFrac nan -- With -O0
-Infinity
Prelude> realToFrac nan
NaN

The function properFraction takes a real fractional number x and returns a pair (n,f) such that x = n+f, and:

• n is an integral number with the same sign as x; and

• f is a fraction with the same type and sign as x, and with absolute value less than 1.

The default definitions of the ceiling, floor, truncate and round functions are in terms of properFraction.

truncate x returns the integer nearest x between zero and x

round x returns the nearest integer to x; the even integer if x is equidistant between two integers

ceiling x returns the least integer not less than x

floor x returns the greatest integer not greater than x

a constant function, returning the radix of the representation (often 2)

a constant function, returning the number of digits of floatRadix in the significand

a constant function, returning the lowest and highest values the exponent may assume

The function decodeFloat applied to a real floating-point number returns the significand expressed as an Integer and an appropriately scaled exponent (an Int). If decodeFloat x yields (m,n), then x is equal in value to m*b^^n, where b is the floating-point radix, and furthermore, either m and n are both zero or else b^(d-1) <= abs m < b^d, where d is the value of floatDigits x. In particular, decodeFloat 0 = (0,0). If the type contains a negative zero, also decodeFloat (-0.0) = (0,0). The result of decodeFloat x is unspecified if either of isNaN x or isInfinite x is True.

encodeFloat performs the inverse of decodeFloat in the sense that for finite x with the exception of -0.0, uncurry encodeFloat (decodeFloat x) = x. encodeFloat m n is one of the two closest representable floating-point numbers to m*b^^n (or ±Infinity if overflow occurs); usually the closer, but if m contains too many bits, the result may be rounded in the wrong direction.

exponent corresponds to the second component of decodeFloat. exponent 0 = 0 and for finite nonzero x, exponent x = snd (decodeFloat x) + floatDigits x. If x is a finite floating-point number, it is equal in value to significand x * b ^^ exponent x, where b is the floating-point radix. The behaviour is unspecified on infinite or NaN values.

The first component of decodeFloat, scaled to lie in the open interval (-1,1), either 0.0 or of absolute value >= 1/b, where b is the floating-point radix. The behaviour is unspecified on infinite or NaN values.

multiplies a floating-point number by an integer power of the radix

True if the argument is an IEEE "not-a-number" (NaN) value

True if the argument is an IEEE infinity or negative infinity

True if the argument is too small to be represented in normalized format

True if the argument is an IEEE negative zero

True if the argument is an IEEE floating point number

a version of arctangent taking two real floating-point arguments. For real floating x and y, atan2 y x computes the angle (from the positive x-axis) of the vector from the origin to the point (x,y). atan2 y x returns a value in the range [-pi, pi]. It follows the Common Lisp semantics for the origin when signed zeroes are supported. atan2 y 1, with y in a type that is RealFloat, should return the same value as atan y. A default definition of atan2 is provided, but implementors can provide a more accurate implementation.

Reverse order of bytes in Word16.

Reverse order of bytes in Word32.

Reverse order of bytes in Word64.

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!

Identity of mappend

Examples

>>> "Hello world" <> mempty"Hello world"

>>> mempty <> [1, 2, 3][1,2,3]

An associative operation

NOTE: This method is redundant and has the default implementation mappend = (<>) since base-4.11.0.0. Should it be implemented manually, since mappend is a synonym for (<>), it is expected that the two functions are defined the same way. In a future GHC release mappend will be removed from Monoid.

Fold a list using the monoid.

For most types, the default definition for mconcat will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

>>> mconcat ["Hello", " ", "Haskell", "!"]"Hello Haskell!"

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)

An infix synonym for fmap.

The name of this operator is an allusion to $. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas $ 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)

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

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

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

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

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

Sequence actions, discarding the value of the second argument.

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

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

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]

Lift a ternary function to actions.

Repeat an action indefinitely.

Examples

A common use of forever is to process input from network sockets, System.IO.Handles, and channels (e.g. Control.Concurrent.MVar.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.

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

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

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

This generalizes the list-based 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]

Like replicateM, but discards the result.

Examples

>>> replicateM_ 3 (putStr "a")aaa

The zipWithM function generalizes zipWith to arbitrary applicative functors.

zipWithM_ is the extension of zipWithM which ignores the final result.

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.

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.

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

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

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

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

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

Strict version of Data.Functor.<$>.

Promote a function to a monad. This is equivalent to fmap but specialised to Monads.

Promote a function to a monad, scanning the monadic arguments from left to right.

Examples

>>> liftM2 (+) [0,1] [0,2][0,2,1,3]

>>> liftM2 (+) (Just 1) NothingNothing

>>> liftM2 (+) (+ 3) (* 2) 518

Run the second value if the first value returns True

Run the second value if the first value returns False

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.

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.

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.

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

foldM f a1 [x1, x2, ..., xm]

==

do
  a2 <- f a1 x1
  a3 <- f a2 x2
  ...
  f am xm

If right-to-left evaluation is required, the input list should be reversed.

Note: foldM is the same as foldlM

Like foldM, but discards the result.

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

Given a structure with elements whose type is a Monoid, combine them via the monoid's (<>) operator. This fold is right-associative and lazy in the accumulator. When you need a strict left-associative fold, use foldMap' instead, with id as the map.

Examples

Basic usage:

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

>>> fold $ Node (Leaf (Sum 1)) (Sum 3) (Leaf (Sum 5))Sum {getSum = 9}

Folds of unbounded structures do not terminate when the monoid's (<>) operator is strict:

>>> fold (repeat Nothing)* Hangs forever *

Lazy corecursive folds of unbounded structures are fine:

>>> take 12 $ fold $ map (\i -> [i..i+2]) [0..][0,1,2,1,2,3,2,3,4,3,4,5]>>> sum $ take 4000000 $ fold $ map (\i -> [i..i+2]) [0..]2666668666666

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"

Extend foldMap to allow side effects.

Internally, this is implemented using a strict left fold. This is used for performance reasons. It also necessitates that this function has a Monad constraint and not just an Applicative constraint. For more information, see https://github.com/commercialhaskell/rio/pull/99#issuecomment-394179757.

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 *

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 *

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 *

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 *

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 *

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 *

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 *

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 *

List of elements of a structure, from left to right. If the entire list is intended to be reduced via a fold, just fold the structure directly bypassing the list.

Examples

Basic usage:

>>> toList Nothing[]

>>> toList (Just 42)[42]

>>> toList (Left "foo")[]

>>> toList (Node (Leaf 5) 17 (Node Empty 12 (Leaf 8)))[5,17,12,8]

For lists, toList is the identity:

>>> toList [1, 2, 3][1,2,3]

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

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

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.

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

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

An associative binary operation

One or more.

Examples

>>> some (putStr "la")lalalalalalalalala... * goes on forever *

>>> some Nothingnothing

>>> take 5 <$> some (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case some parser will attempt to parse parser one or more times until it fails.

Zero or more.

Examples

>>> many (putStr "la")lalalalalalalalala... * goes on forever *

>>> many NothingJust []

>>> take 5 <$> many (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case many parser will attempt to parse parser zero or more times until it fails.

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

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"

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)

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:

The reverse of when.

Examples

>>> do x <- getLine       unless (x == "hi") (putStrLn "hi!")comingupwithexamplesisdifficulthi!

>>> unless (pi > exp 1) NothingJust ()

Map over both arguments at the same time.

bimap f g ≡ first f . second g

Examples

>>> bimap toUpper (+1) ('j', 3)('J',4)

>>> bimap toUpper (+1) (Left 'j')Left 'J'

>>> bimap toUpper (+1) (Right 3)Right 4

Map covariantly over the first argument.

first f ≡ bimap f id

Examples

>>> first toUpper ('j', 3)('J',3)

>>> first toUpper (Left 'j')Left 'J'

Map covariantly over the second argument.

second ≡ bimap id

Examples

>>> second (+1) ('j', 3)('j',4)

>>> second (+1) (Right 3)Right 4

Combines the elements of a structure using a monoid.

bifold ≡ bifoldMap id id

Examples

Basic usage:

>>> bifold (Right [1, 2, 3])[1,2,3]

>>> bifold (Left [5, 6])[5,6]

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

>>> bifold (Product 6, Product 7)Product {getProduct = 42}

>>> bifold (Sum 6, Sum 7)Sum {getSum = 13}

Combines the elements of a structure, given ways of mapping them to a common monoid.

bifoldMap f g ≡ bifoldr (mappend . f) (mappend . g) mempty

Examples

Basic usage:

>>> bifoldMap (take 3) (fmap digitToInt) ([1..], "89")[1,2,3,8,9]

>>> bifoldMap (take 3) (fmap digitToInt) (Left [1..])[1,2,3]

>>> bifoldMap (take 3) (fmap digitToInt) (Right "89")[8,9]

Combines the elements of a structure in a right associative manner. Given a hypothetical function toEitherList :: p a b -> [Either a b] yielding a list of all elements of a structure in order, the following would hold:

bifoldr f g z ≡ foldr (either f g) z . toEitherList

Examples

Basic usage:

> bifoldr (+) (*) 3 (5, 7)
26 -- 5 + (7 * 3)

> bifoldr (+) (*) 3 (7, 5)
22 -- 7 + (5 * 3)

> bifoldr (+) (*) 3 (Right 5)
15 -- 5 * 3

> bifoldr (+) (*) 3 (Left 5)
8 -- 5 + 3

Combines the elements of a structure in a left associative manner. Given a hypothetical function toEitherList :: p a b -> [Either a b] yielding a list of all elements of a structure in order, the following would hold:

bifoldl f g z
     ≡ foldl (acc -> either (f acc) (g acc)) z . toEitherList

Note that if you want an efficient left-fold, you probably want to use bifoldl' instead of bifoldl. The reason is that the latter does not force the "inner" results, resulting in a thunk chain which then must be evaluated from the outside-in.

Examples

Basic usage:

> bifoldl (+) (*) 3 (5, 7)
56 -- (5 + 3) * 7

> bifoldl (+) (*) 3 (7, 5)
50 -- (7 + 3) * 5

> bifoldl (+) (*) 3 (Right 5)
15 -- 5 * 3

> bifoldl (+) (*) 3 (Left 5)
8 -- 5 + 3

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

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

Examples

Basic usage:

>>> bifoldr1 (+) (5, 7)12

>>> bifoldr1 (+) (Right 7)7

>>> bifoldr1 (+) (Left 5)5

> bifoldr1 (+) (BiList [1, 2] [3, 4])
10 -- 1 + (2 + (3 + 4))

>>> bifoldr1 (+) (BiList [1, 2] [])3

On empty structures, this function throws an exception:

>>> bifoldr1 (+) (BiList [] [])*** Exception: bifoldr1: empty structure...

Right associative monadic bifold over a structure.

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

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

Examples

Basic usage:

>>> bifoldl1 (+) (5, 7)12

>>> bifoldl1 (+) (Right 7)7

>>> bifoldl1 (+) (Left 5)5

> bifoldl1 (+) (BiList [1, 2] [3, 4])
10 -- ((1 + 2) + 3) + 4

>>> bifoldl1 (+) (BiList [1, 2] [])3

On empty structures, this function throws an exception:

>>> bifoldl1 (+) (BiList [] [])*** Exception: bifoldl1: empty structure...

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

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"

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"

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"

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

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

Examples

Basic usage:

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

>>> biList (Left 18)[18]

Test whether the structure is empty.

Examples

Basic usage:

>>> binull (18, 42)False

>>> binull (Right 42)False

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

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 *

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 largest element of a non-empty structure.

Examples

Basic usage:

>>> bimaximum (42, 17)42

>>> bimaximum (Right 42)42

>>> bimaximum (BiList [13, 29, 4] [18, 1, 7])29

>>> bimaximum (BiList [13, 29, 4] [])29

On empty structures, this function throws an exception:

>>> bimaximum (BiList [] [])*** Exception: bimaximum: empty structure...

The least element of a non-empty structure.

Examples

Basic usage:

>>> biminimum (42, 17)17

>>> biminimum (Right 42)42

>>> biminimum (BiList [13, 29, 4] [18, 1, 7])1

>>> biminimum (BiList [13, 29, 4] [])4

On empty structures, this function throws an exception:

>>> biminimum (BiList [] [])*** Exception: biminimum: empty structure...

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

Examples

Basic usage:

>>> bisum (42, 17)59

>>> bisum (Right 42)42

>>> bisum (BiList [13, 29, 4] [18, 1, 7])72

>>> bisum (BiList [13, 29, 4] [])46

>>> bisum (BiList [] [])0

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

Examples

Basic usage:

>>> biproduct (42, 17)714

>>> biproduct (Right 42)42

>>> biproduct (BiList [13, 29, 4] [18, 1, 7])190008

>>> biproduct (BiList [13, 29, 4] [])1508

>>> biproduct (BiList [] [])1

Reduces a structure of lists to the concatenation of those lists.

Examples

Basic usage:

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

>>> biconcat (Left [1, 2, 3])[1,2,3]

>>> biconcat (BiList [[1, 2, 3, 4, 5], [6, 7, 8]] [[9]])[1,2,3,4,5,6,7,8,9]

Given a means of mapping the elements of a structure to lists, computes the concatenation of all such lists in order.

Examples

Basic usage:

>>> biconcatMap (take 3) (fmap digitToInt) ([1..], "89")[1,2,3,8,9]

>>> biconcatMap (take 3) (fmap digitToInt) (Left [1..])[1,2,3]

>>> biconcatMap (take 3) (fmap digitToInt) (Right "89")[8,9]

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 *

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 *

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

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

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

Examples

Basic usage:

>>> bimaximumBy compare (42, 17)42

>>> bimaximumBy compare (Left 17)17

>>> bimaximumBy compare (BiList [42, 17, 23] [-5, 18])42

On empty structures, this function throws an exception:

>>> bimaximumBy compare (BiList [] [])*** Exception: bifoldr1: empty structure...