rio-0.1.22.0: A standard library for Haskell

Safe Haskell | None
Language | Haskell2010

RIO.Prelude

Contents

- `Bool`
- `Maybe`
- `Either`
- Tuples
- `Eq`
- `Ord`
- `Enum`
- `Bounded`
- `Num`
- `Real`
- `Integral`
- `Fractional`
- `Floating`
- `RealFrac`
- `RealFloat`
- `Word`
- `Semigroup`
- `Monoid`
- `Functor`
- `Applicative`
- `Monad`
- `Foldable`
- `Traversable`
- `Alternative`
- `Bifunctor`
- `Bifoldable`
- `Bitraverse`
- `MonadPlus`
- `Arrow`
- `Function`
- Miscellaneous functions
- List
- `String`
  - `Show`
  - `Read`
- `NFData`
- `Void`
- `Reader`
- `ByteString`
- `ShortByteString`
- `Text`
- `PrimMonad`

Synopsis

- (||) :: Bool -> Bool -> Bool
- (&&) :: Bool -> Bool -> Bool
- not :: Bool -> Bool
- otherwise :: Bool
- bool :: a -> a -> Bool -> a
- maybe :: b -> (a -> b) -> Maybe a -> b
- fromMaybe :: a -> Maybe a -> a
- fromFirst :: a -> First a -> a
- isJust :: Maybe a -> Bool
- isNothing :: Maybe a -> Bool
- listToMaybe :: [a] -> Maybe a
- maybeToList :: Maybe a -> [a]
- catMaybes :: [Maybe a] -> [a]
- mapMaybe :: (a -> Maybe b) -> [a] -> [b]
- mapMaybeA :: Applicative f => (a -> f (Maybe b)) -> [a] -> f [b]
- mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]
- forMaybeA :: Applicative f => [a] -> (a -> f (Maybe b)) -> f [b]
- forMaybeM :: Monad m => [a] -> (a -> m (Maybe b)) -> m [b]
- either :: (a -> c) -> (b -> c) -> Either a b -> c
- fromLeft :: a -> Either a b -> a
- fromRight :: b -> Either a b -> b
- isLeft :: Either a b -> Bool
- isRight :: Either a b -> Bool
- mapLeft :: (a1 -> a2) -> Either a1 b -> Either a2 b
- lefts :: [Either a b] -> [a]
- partitionEithers :: [Either a b] -> ([a], [b])
- rights :: [Either a b] -> [b]
- fst :: (a, b) -> a
- snd :: (a, b) -> b
- curry :: ((a, b) -> c) -> a -> b -> c
- uncurry :: (a -> b -> c) -> (a, b) -> c
- (==) :: Eq a => a -> a -> Bool
- (/=) :: Eq a => a -> a -> Bool
- (<) :: Ord a => a -> a -> Bool
- (<=) :: Ord a => a -> a -> Bool
- (>) :: Ord a => a -> a -> Bool
- (>=) :: Ord a => a -> a -> Bool
- max :: Ord a => a -> a -> a
- min :: Ord a => a -> a -> a
- compare :: Ord a => a -> a -> Ordering
- comparing :: Ord a => (b -> a) -> b -> b -> Ordering
- newtype Down a = Down {
  - getDown :: a
  }
- fromEnum :: Enum a => a -> Int
- minBound :: Bounded a => a
- maxBound :: Bounded a => a
- (+) :: Num a => a -> a -> a
- (-) :: Num a => a -> a -> a
- (*) :: Num a => a -> a -> a
- (^) :: (Num a, Integral b) => a -> b -> a
- negate :: Num a => a -> a
- abs :: Num a => a -> a
- signum :: Num a => a -> a
- fromInteger :: Num a => Integer -> a
- subtract :: Num a => a -> a -> a
- toRational :: Real a => a -> Rational
- quot :: Integral a => a -> a -> a
- rem :: Integral a => a -> a -> a
- div :: Integral a => a -> a -> a
- mod :: Integral a => a -> a -> a
- quotRem :: Integral a => a -> a -> (a, a)
- divMod :: Integral a => a -> a -> (a, a)
- toInteger :: Integral a => a -> Integer
- even :: Integral a => a -> Bool
- odd :: Integral a => a -> Bool
- gcd :: Integral a => a -> a -> a
- lcm :: Integral a => a -> a -> a
- fromIntegral :: (Integral a, Num b) => a -> b
- (/) :: Fractional a => a -> a -> a
- (^^) :: (Fractional a, Integral b) => a -> b -> a
- recip :: Fractional a => a -> a
- fromRational :: Fractional a => Rational -> a
- realToFrac :: (Real a, Fractional b) => a -> b
- pi :: Floating a => a
- exp :: Floating a => a -> a
- log :: Floating a => a -> a
- sqrt :: Floating a => a -> a
- (**) :: Floating a => a -> a -> a
- logBase :: Floating a => a -> a -> a
- sin :: Floating a => a -> a
- cos :: Floating a => a -> a
- tan :: Floating a => a -> a
- asin :: Floating a => a -> a
- acos :: Floating a => a -> a
- atan :: Floating a => a -> a
- sinh :: Floating a => a -> a
- cosh :: Floating a => a -> a
- tanh :: Floating a => a -> a
- asinh :: Floating a => a -> a
- acosh :: Floating a => a -> a
- atanh :: Floating a => a -> a
- properFraction :: (RealFrac a, Integral b) => a -> (b, a)
- truncate :: (RealFrac a, Integral b) => a -> b
- round :: (RealFrac a, Integral b) => a -> b
- ceiling :: (RealFrac a, Integral b) => a -> b
- floor :: (RealFrac a, Integral b) => a -> b
- floatRadix :: RealFloat a => a -> Integer
- floatDigits :: RealFloat a => a -> Int
- floatRange :: RealFloat a => a -> (Int, Int)
- decodeFloat :: RealFloat a => a -> (Integer, Int)
- encodeFloat :: RealFloat a => Integer -> Int -> a
- exponent :: RealFloat a => a -> Int
- significand :: RealFloat a => a -> a
- scaleFloat :: RealFloat a => Int -> a -> a
- isNaN :: RealFloat a => a -> Bool
- isInfinite :: RealFloat a => a -> Bool
- isDenormalized :: RealFloat a => a -> Bool
- isNegativeZero :: RealFloat a => a -> Bool
- isIEEE :: RealFloat a => a -> Bool
- atan2 :: RealFloat a => a -> a -> a
- byteSwap16 :: Word16 -> Word16
- byteSwap32 :: Word32 -> Word32
- byteSwap64 :: Word64 -> Word64
- (<>) :: Semigroup a => a -> a -> a
- sappend :: Semigroup s => s -> s -> s
- mempty :: Monoid a => a
- mappend :: Monoid a => a -> a -> a
- mconcat :: Monoid a => [a] -> a
- fmap :: Functor f => (a -> b) -> f a -> f b
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- (<$) :: Functor f => a -> f b -> f a
- ($>) :: Functor f => f a -> b -> f b
- void :: Functor f => f a -> f ()
- (<&>) :: Functor f => f a -> (a -> b) -> f b
- pure :: Applicative f => a -> f a
- (<*>) :: Applicative f => f (a -> b) -> f a -> f b
- (<*) :: Applicative f => f a -> f b -> f a
- (*>) :: Applicative f => f a -> f b -> f b
- liftA :: Applicative f => (a -> b) -> f a -> f b
- liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
- liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
- forever :: Applicative f => f a -> f b
- traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f ()
- for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()
- sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f ()
- filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]
- replicateM_ :: Applicative m => Int -> m a -> m ()
- zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]
- zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()
- return :: Monad m => a -> m a
- join :: Monad m => m (m a) -> m a
- fail :: MonadFail m => String -> m a
- (>>=) :: Monad m => m a -> (a -> m b) -> m b
- (>>) :: Monad m => m a -> m b -> m b
- (=<<) :: Monad m => (a -> m b) -> m a -> m b
- (>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
- (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
- (<$!>) :: Monad m => (a -> b) -> m a -> m b
- liftM :: Monad m => (a1 -> r) -> m a1 -> m r
- liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
- forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
- sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
- foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
- foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
- foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
- foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b
- fold :: (Foldable t, Monoid m) => t m -> m
- foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
- foldMapM :: (Monad m, Monoid w, Foldable t) => (a -> m w) -> t a -> m w
- elem :: (Foldable t, Eq a) => a -> t a -> Bool
- notElem :: (Foldable t, Eq a) => a -> t a -> Bool
- null :: Foldable t => t a -> Bool
- length :: Foldable t => t a -> Int
- sum :: (Foldable t, Num a) => t a -> a
- product :: (Foldable t, Num a) => t a -> a
- all :: Foldable t => (a -> Bool) -> t a -> Bool
- any :: Foldable t => (a -> Bool) -> t a -> Bool
- and :: Foldable t => t Bool -> Bool
- or :: Foldable t => t Bool -> Bool
- toList :: Foldable t => t a -> [a]
- concat :: Foldable t => t [a] -> [a]
- concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
- traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)
- for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)
- sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)
- mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
- forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
- sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
- (<|>) :: Alternative f => f a -> f a -> f a
- some :: Alternative f => f a -> f [a]
- many :: Alternative f => f a -> f [a]
- optional :: Alternative f => f a -> f (Maybe a)
- asum :: (Foldable t, Alternative f) => t (f a) -> f a
- guard :: Alternative f => Bool -> f ()
- when :: Applicative f => Bool -> f () -> f ()
- unless :: Applicative f => Bool -> f () -> f ()
- bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d
- first :: Bifunctor p => (a -> b) -> p a c -> p b c
- second :: Bifunctor p => (b -> c) -> p a b -> p a c
- bifold :: (Bifoldable p, Monoid m) => p m m -> m
- bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
- bifoldr :: Bifoldable p => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
- bifoldl :: Bifoldable p => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
- bifoldr' :: Bifoldable t => (a -> c -> c) -> (b -> c -> c) -> c -> t a b -> c
- bifoldr1 :: Bifoldable t => (a -> a -> a) -> t a a -> a
- bifoldrM :: (Bifoldable t, Monad m) => (a -> c -> m c) -> (b -> c -> m c) -> c -> t a b -> m c
- bifoldl' :: Bifoldable t => (a -> b -> a) -> (a -> c -> a) -> a -> t b c -> a
- bifoldl1 :: Bifoldable t => (a -> a -> a) -> t a a -> a
- bifoldlM :: (Bifoldable t, Monad m) => (a -> b -> m a) -> (a -> c -> m a) -> a -> t b c -> m a
- bitraverse_ :: (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f ()
- bifor_ :: (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f ()
- bisequence_ :: (Bifoldable t, Applicative f) => t (f a) (f b) -> f ()
- biasum :: (Bifoldable t, Alternative f) => t (f a) (f a) -> f a
- biList :: Bifoldable t => t a a -> [a]
- binull :: Bifoldable t => t a b -> Bool
- bilength :: Bifoldable t => t a b -> Int
- bielem :: (Bifoldable t, Eq a) => a -> t a a -> Bool
- bimaximum :: (Bifoldable t, Ord a) => t a a -> a
- biminimum :: (Bifoldable t, Ord a) => t a a -> a
- bisum :: (Bifoldable t, Num a) => t a a -> a
- biproduct :: (Bifoldable t, Num a) => t a a -> a
- biconcat :: Bifoldable t => t [a] [a] -> [a]
- biconcatMap :: Bifoldable t => (a -> [c]) -> (b -> [c]) -> t a b -> [c]
- biand :: Bifoldable t => t Bool Bool -> Bool
- bior :: Bifoldable t => t Bool Bool -> Bool
- biany :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
- biall :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
- bimaximumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a
- biminimumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a
- binotElem :: (Bifoldable t, Eq a) => a -> t a a -> Bool
- bifind :: Bifoldable t => (a -> Bool) -> t a a -> Maybe a
- bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
- bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b)
- bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)
- bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)
- bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)
- mzero :: MonadPlus m => m a
- mplus :: MonadPlus m => m a -> m a -> m a
- msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
- mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
- (&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')
- (***) :: Arrow a => a b c -> a b' c' -> a (b, b') (c, c')
- (>>>) :: forall {k} cat (a :: k) (b :: k) (c :: k). Category cat => cat a b -> cat b c -> cat a c
- id :: a -> a
- const :: a -> b -> a
- (.) :: (b -> c) -> (a -> b) -> a -> c
- ($) :: (a -> b) -> a -> b
- (&) :: a -> (a -> b) -> b
- flip :: (a -> b -> c) -> b -> a -> c
- fix :: (a -> a) -> a
- on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
- ($!) :: (a -> b) -> a -> b
- seq :: a -> b -> b
- error :: HasCallStack => [Char] -> a
- undefined :: HasCallStack => a
- asTypeOf :: a -> a -> a
- asIO :: IO a -> IO a
- (++) :: [a] -> [a] -> [a]
- break :: (a -> Bool) -> [a] -> ([a], [a])
- drop :: Int -> [a] -> [a]
- dropWhile :: (a -> Bool) -> [a] -> [a]
- filter :: (a -> Bool) -> [a] -> [a]
- lookup :: Eq a => a -> [(a, b)] -> Maybe b
- map :: (a -> b) -> [a] -> [b]
- replicate :: Int -> a -> [a]
- reverse :: [a] -> [a]
- span :: (a -> Bool) -> [a] -> ([a], [a])
- take :: Int -> [a] -> [a]
- takeWhile :: (a -> Bool) -> [a] -> [a]
- zip :: [a] -> [b] -> [(a, b)]
- zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]
- nubOrd :: Ord a => [a] -> [a]
- fromString :: IsString a => String -> a
- lines :: String -> [String]
- unlines :: [String] -> String
- unwords :: [String] -> String
- words :: String -> [String]
- show :: Show a => a -> String
- readMaybe :: Read a => String -> Maybe a
- ($!!) :: NFData a => (a -> b) -> a -> b
- rnf :: NFData a => a -> ()
- deepseq :: NFData a => a -> b -> b
- force :: NFData a => a -> a
- absurd :: Void -> a
- lift :: (MonadTrans t, Monad m) => m a -> t m a
- ask :: MonadReader r m => m r
- asks :: MonadReader r m => (r -> a) -> m a
- local :: MonadReader r m => (r -> r) -> m a -> m a
- runReader :: Reader r a -> r -> a
- runReaderT :: ReaderT r m a -> r -> m a
- toStrictBytes :: LByteString -> ByteString
- fromStrictBytes :: ByteString -> LByteString
- toShort :: ByteString -> ShortByteString
- fromShort :: ShortByteString -> ByteString
- tshow :: Show a => a -> Text
- decodeUtf8Lenient :: ByteString -> Text
- decodeUtf8' :: ByteString -> Either UnicodeException Text
- decodeUtf8With :: OnDecodeError -> ByteString -> Text
- encodeUtf8 :: Text -> ByteString
- encodeUtf8Builder :: Text -> Builder
- lenientDecode :: OnDecodeError
- primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
- runST :: (forall s. ST s a) -> a

# `Bool`

Re-exported from Data.Bool:

(||) :: Bool -> Bool -> Bool infixr 2 #

Boolean "or", lazy in the second argument

(&&) :: Bool -> Bool -> Bool infixr 3 #

Boolean "and", lazy in the second argument

not :: Bool -> Bool #

Boolean "not"

otherwise :: Bool #

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

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

bool :: a -> a -> Bool -> a #

Case analysis for the `Bool` type. ``bool` x y p` evaluates to `x` when `p` is `False`, and evaluates to `y` when `p` is `True`.

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

#### Examples

Expand

Basic usage:

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

Confirm that ``bool` x y p` and `if p then y else x` are equivalent:

    >>> let p = True; x = "bar"; y = "foo"
    >>> bool x y p == if p then y else x
    True
    >>> let p = False
    >>> bool x y p == if p then y else x
    True

Since: base-4.7.0.0

# `Maybe`

Re-exported from Data.Maybe:

maybe :: b -> (a -> b) -> Maybe a -> b #

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

Expand

Basic usage:

    >>> maybe False odd (Just 3)
    True

    >>> maybe False odd Nothing
    False

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

fromMaybe :: a -> Maybe a -> a #

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

Expand

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 Text.Read ( readMaybe )
    >>> fromMaybe 0 (readMaybe "5")
    5
    >>> fromMaybe 0 (readMaybe "")
    0

fromFirst :: a -> First a -> a #

Get a `First` value with a default fallback

isJust :: Maybe a -> Bool #

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

#### Examples

Expand

Basic usage:

    >>> isJust (Just 3)
    True

    >>> isJust (Just ())
    True

    >>> isJust Nothing
    False

Only the outer constructor is taken into consideration:

    >>> isJust (Just Nothing)
    True

isNothing :: Maybe a -> Bool #

The `isNothing` function returns `True` iff its argument is `Nothing`.

#### Examples

Expand

Basic usage:

    >>> isNothing (Just 3)
    False

    >>> isNothing (Just ())
    False

    >>> isNothing Nothing
    True

Only the outer constructor is taken into consideration:

    >>> isNothing (Just Nothing)
    False

listToMaybe :: [a] -> Maybe a #

The `listToMaybe` function returns `Nothing` on an empty list or ``Just` a` where `a` is the first element of the list.

#### Examples

Expand

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]

maybeToList :: Maybe a -> [a] #

The `maybeToList` function returns an empty list when given `Nothing` or a singleton list when given `Just`.

#### Examples

Expand

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 Text.Read ( readMaybe )
    >>> sum $ maybeToList (readMaybe "3")
    3
    >>> sum $ maybeToList (readMaybe "")
    0

catMaybes :: [Maybe a] -> [a] #

The `catMaybes` function takes a list of `Maybe`s and returns a list of all the `Just` values.

#### Examples

Expand

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

mapMaybe :: (a -> Maybe b) -> [a] -> [b] #

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

Expand

Using ``mapMaybe` f x` is a shortcut for ``catMaybes` $ `map` f x` in most cases:

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

mapMaybeA :: Applicative f => (a -> f (Maybe b)) -> [a] -> f [b] #

Applicative `mapMaybe`.

mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b] #

Monadic `mapMaybe`.

forMaybeA :: Applicative f => [a] -> (a -> f (Maybe b)) -> f [b] #

    forMaybeA == flip mapMaybeA

forMaybeM :: Monad m => [a] -> (a -> m (Maybe b)) -> m [b] #

    forMaybeM == flip mapMaybeM

# `Either`

Re-exported from Data.Either:

either :: (a -> c) -> (b -> c) -> Either a b -> c #

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

Expand

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) s
    3
    >>> either length (*2) n
    6

fromLeft :: a -> Either a b -> a #

Return the contents of a `Left`-value or a default value otherwise.

#### Examples

Expand

Basic usage:

    >>> fromLeft 1 (Left 3)
    3
    >>> fromLeft 1 (Right "foo")
    1

Since: base-4.10.0.0

fromRight :: b -> Either a b -> b #

Return the contents of a `Right`-value or a default value otherwise.

#### Examples

Expand

Basic usage:

    >>> fromRight 1 (Right 3)
    3
    >>> fromRight 1 (Left "foo")
    1

Since: base-4.10.0.0

isLeft :: Either a b -> Bool #

Return `True` if the given value is a `Left`-value, `False` otherwise.

#### Examples

Expand

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

Since: base-4.7.0.0

isRight :: Either a b -> Bool #

Return `True` if the given value is a `Right`-value, `False` otherwise.

#### Examples

Expand

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

Since: base-4.7.0.0

mapLeft :: (a1 -> a2) -> Either a1 b -> Either a2 b #

Apply a function to a `Left` constructor

lefts :: [Either a b] -> [a] #

Extracts from a list of `Either` all the `Left` elements. All the `Left` elements are extracted in order.

#### Examples

Expand

Basic usage:

    >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
    >>> lefts list
    ["foo","bar","baz"]

partitionEithers :: [Either a b] -> ([a], [b]) #

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

Expand

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

rights :: [Either a b] -> [b] #

Extracts from a list of `Either` all the `Right` elements. All the `Right` elements are extracted in order.

#### Examples

Expand

Basic usage:

    >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
    >>> rights list
    [3,7]

# Tuples

Re-exported from Data.Tuple:

fst :: (a, b) -> a #

Extract the first component of a pair.

snd :: (a, b) -> b #

Extract the second component of a pair.

curry :: ((a, b) -> c) -> a -> b -> c #

`curry` converts an uncurried function to a curried function.

#### Examples

Expand

    >>> curry fst 1 2
    1

uncurry :: (a -> b -> c) -> (a, b) -> c #

`uncurry` converts a curried function to a function on pairs.

#### Examples

Expand

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

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

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

# `Eq`

Re-exported from Data.Eq:

(==) :: Eq a => a -> a -> Bool infix 4 #

(/=) :: Eq a => a -> a -> Bool infix 4 #

# `Ord`

Re-exported from Data.Ord:

(<) :: Ord a => a -> a -> Bool infix 4 #

(<=) :: Ord a => a -> a -> Bool infix 4 #

(>) :: Ord a => a -> a -> Bool infix 4 #

(>=) :: Ord a => a -> a -> Bool infix 4 #

max :: Ord a => a -> a -> a #

min :: Ord a => a -> a -> a #

compare :: Ord a => a -> a -> Ordering #

comparing :: Ord a => (b -> a) -> b -> b -> Ordering #

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

newtype Down a #

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

    >>> 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 Int
    Down 9223372036854775807

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

Since: base-4.6.0.0

Constructors

Down |
Fields getDown :: a Since: base-4.14.0.0

#### Instances

Instances details

MonadFix Down | Since: base-4.12.0.0
Instance details Defined in Control.Monad.Fix Methods mfix :: (a -> Down a) -> Down a #
MonadZip Down | Since: base-4.12.0.0
Instance details Defined in Control.Monad.Zip Methods mzip :: Down a -> Down b -> Down (a, b) # mzipWith :: (a -> b -> c) -> Down a -> Down b -> Down c # munzip :: Down (a, b) -> (Down a, Down b) #
Foldable Down | Since: base-4.12.0.0
Instance details Defined in Data.Foldable Methods fold :: Monoid m => Down m -> m # foldMap :: Monoid m => (a -> m) -> Down a -> m # foldMap' :: Monoid m => (a -> m) -> Down a -> m # foldr :: (a -> b -> b) -> b -> Down a -> b # foldr' :: (a -> b -> b) -> b -> Down a -> b # foldl :: (b -> a -> b) -> b -> Down a -> b # foldl' :: (b -> a -> b) -> b -> Down a -> b # foldr1 :: (a -> a -> a) -> Down a -> a # foldl1 :: (a -> a -> a) -> Down a -> a # toList :: Down a -> [a] # null :: Down a -> Bool # length :: Down a -> Int # elem :: Eq a => a -> Down a -> Bool # maximum :: Ord a => Down a -> a # minimum :: Ord a => Down a -> a # sum :: Num a => Down a -> a # product :: Num a => Down a -> a #
Foldable1 Down | Since: base-4.18.0.0
Instance details Defined in Data.Foldable1 Methods fold1 :: Semigroup m => Down m -> m # foldMap1 :: Semigroup m => (a -> m) -> Down a -> m # foldMap1' :: Semigroup m => (a -> m) -> Down a -> m # toNonEmpty :: Down a -> NonEmpty a # maximum :: Ord a => Down a -> a # minimum :: Ord a => Down a -> a # head :: Down a -> a # last :: Down a -> a # foldrMap1 :: (a -> b) -> (a -> b -> b) -> Down a -> b # foldlMap1' :: (a -> b) -> (b -> a -> b) -> Down a -> b # foldlMap1 :: (a -> b) -> (b -> a -> b) -> Down a -> b # foldrMap1' :: (a -> b) -> (a -> b -> b) -> Down a -> b #
Eq1 Down | Since: base-4.12.0.0
Instance details Defined in Data.Functor.Classes Methods liftEq :: (a -> b -> Bool) -> Down a -> Down b -> Bool #
Ord1 Down | Since: base-4.12.0.0
Instance details Defined in Data.Functor.Classes Methods liftCompare :: (a -> b -> Ordering) -> Down a -> Down b -> Ordering #
Read1 Down | Since: base-4.12.0.0
Instance details Defined in Data.Functor.Classes Methods liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Down a) # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Down a] # liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (Down a) # liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [Down a] #
Show1 Down | Since: base-4.12.0.0
Instance details Defined in Data.Functor.Classes Methods liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Down a -> ShowS # liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Down a] -> ShowS #
Traversable Down | Since: base-4.12.0.0
Instance details Defined in Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Down a -> f (Down b) # sequenceA :: Applicative f => Down (f a) -> f (Down a) # mapM :: Monad m => (a -> m b) -> Down a -> m (Down b) # sequence :: Monad m => Down (m a) -> m (Down a) #
Applicative Down | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods pure :: a -> Down a # (<*>) :: Down (a -> b) -> Down a -> Down b # liftA2 :: (a -> b -> c) -> Down a -> Down b -> Down c # (*>) :: Down a -> Down b -> Down b # (<*) :: Down a -> Down b -> Down a #
Functor Down | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods fmap :: (a -> b) -> Down a -> Down b # (<$) :: a -> Down b -> Down a #
Monad Down | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods (>>=) :: Down a -> (a -> Down b) -> Down b # (>>) :: Down a -> Down b -> Down b # return :: a -> Down a #
NFData1 Down | Since: deepseq-1.4.3.0
Instance details Defined in Control.DeepSeq Methods liftRnf :: (a -> ()) -> Down a -> () #
Generic1 Down |
Instance details Defined in GHC.Generics Associated Types
type Rep1 Down | Since: base-4.12.0.0
Instance details Defined in GHC.Generics type Rep1 Down = D1 ('MetaData "Down" "Data.Ord" "base" 'True) (C1 ('MetaCons "Down" 'PrefixI 'True) (S1 ('MetaSel ('Just "getDown") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
Methods from1 :: Down a -> Rep1 Down a # to1 :: Rep1 Down a -> Down a #
Unbox a => Vector Vector (Down a) |
Instance details Defined in Data.Vector.Unboxed.Base Methods basicUnsafeFreeze :: Mutable Vector s (Down a) -> ST s (Vector (Down a)) # basicUnsafeThaw :: Vector (Down a) -> ST s (Mutable Vector s (Down a)) # basicLength :: Vector (Down a) -> Int # basicUnsafeSlice :: Int -> Int -> Vector (Down a) -> Vector (Down a) # basicUnsafeIndexM :: Vector (Down a) -> Int -> Box (Down a) # basicUnsafeCopy :: Mutable Vector s (Down a) -> Vector (Down a) -> ST s () # elemseq :: Vector (Down a) -> Down a -> b -> b #
Unbox a => MVector MVector (Down a) |
Instance details Defined in Data.Vector.Unboxed.Base Methods basicLength :: MVector s (Down a) -> Int # basicUnsafeSlice :: Int -> Int -> MVector s (Down a) -> MVector s (Down a) # basicOverlaps :: MVector s (Down a) -> MVector s (Down a) -> Bool # basicUnsafeNew :: Int -> ST s (MVector s (Down a)) # basicInitialize :: MVector s (Down a) -> ST s () # basicUnsafeReplicate :: Int -> Down a -> ST s (MVector s (Down a)) # basicUnsafeRead :: MVector s (Down a) -> Int -> ST s (Down a) # basicUnsafeWrite :: MVector s (Down a) -> Int -> Down a -> ST s () # basicClear :: MVector s (Down a) -> ST s () # basicSet :: MVector s (Down a) -> Down a -> ST s () # basicUnsafeCopy :: MVector s (Down a) -> MVector s (Down a) -> ST s () # basicUnsafeMove :: MVector s (Down a) -> MVector s (Down a) -> ST s () # basicUnsafeGrow :: MVector s (Down a) -> Int -> ST s (MVector s (Down a)) #
Data a => Data (Down a) | Since: base-4.12.0.0
Instance details Defined in Data.Data Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Down a -> c (Down a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Down a) # toConstr :: Down a -> Constr # dataTypeOf :: Down a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Down a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Down a)) # gmapT :: (forall b. Data b => b -> b) -> Down a -> Down a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Down a -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Down a -> r # gmapQ :: (forall d. Data d => d -> u) -> Down a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Down a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Down a -> m (Down a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Down a -> m (Down a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Down a -> m (Down a) #
Storable a => Storable (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods sizeOf :: Down a -> Int # alignment :: Down a -> Int # peekElemOff :: Ptr (Down a) -> Int -> IO (Down a) # pokeElemOff :: Ptr (Down a) -> Int -> Down a -> IO () # peekByteOff :: Ptr b -> Int -> IO (Down a) # pokeByteOff :: Ptr b -> Int -> Down a -> IO () # peek :: Ptr (Down a) -> IO (Down a) # poke :: Ptr (Down a) -> Down a -> IO () #
Monoid a => Monoid (Down a) | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods mempty :: Down a # mappend :: Down a -> Down a -> Down a # mconcat :: [Down a] -> Down a #
Semigroup a => Semigroup (Down a) | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods (<>) :: Down a -> Down a -> Down a # sconcat :: NonEmpty (Down a) -> Down a # stimes :: Integral b => b -> Down a -> Down a #
Bits a => Bits (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods (.&.) :: Down a -> Down a -> Down a # (.|.) :: Down a -> Down a -> Down a # xor :: Down a -> Down a -> Down a # complement :: Down a -> Down a # shift :: Down a -> Int -> Down a # rotate :: Down a -> Int -> Down a # zeroBits :: Down a # bit :: Int -> Down a # setBit :: Down a -> Int -> Down a # clearBit :: Down a -> Int -> Down a # complementBit :: Down a -> Int -> Down a # testBit :: Down a -> Int -> Bool # bitSizeMaybe :: Down a -> Maybe Int # bitSize :: Down a -> Int # isSigned :: Down a -> Bool # shiftL :: Down a -> Int -> Down a # unsafeShiftL :: Down a -> Int -> Down a # shiftR :: Down a -> Int -> Down a # unsafeShiftR :: Down a -> Int -> Down a # rotateL :: Down a -> Int -> Down a # rotateR :: Down a -> Int -> Down a # popCount :: Down a -> Int #
FiniteBits a => FiniteBits (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods finiteBitSize :: Down a -> Int # countLeadingZeros :: Down a -> Int # countTrailingZeros :: Down a -> Int #
Bounded a => Bounded (Down a) | Swaps ``minBound`` and ``maxBound`` of the underlying type. Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods minBound :: Down a # maxBound :: Down a #
(Enum a, Bounded a, Eq a) => Enum (Down a) | Swaps ``succ`` and ``pred`` of the underlying type. Since: base-4.18.0.0
Instance details Defined in Data.Ord Methods succ :: Down a -> Down a # pred :: Down a -> Down a # toEnum :: Int -> Down a # fromEnum :: Down a -> Int # enumFrom :: Down a -> [Down a] # enumFromThen :: Down a -> Down a -> [Down a] # enumFromTo :: Down a -> Down a -> [Down a] # enumFromThenTo :: Down a -> Down a -> Down a -> [Down a] #
Floating a => Floating (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods pi :: Down a # exp :: Down a -> Down a # log :: Down a -> Down a # sqrt :: Down a -> Down a # (**) :: Down a -> Down a -> Down a # logBase :: Down a -> Down a -> Down a # sin :: Down a -> Down a # cos :: Down a -> Down a # tan :: Down a -> Down a # asin :: Down a -> Down a # acos :: Down a -> Down a # atan :: Down a -> Down a # sinh :: Down a -> Down a # cosh :: Down a -> Down a # tanh :: Down a -> Down a # asinh :: Down a -> Down a # acosh :: Down a -> Down a # atanh :: Down a -> Down a # log1p :: Down a -> Down a # expm1 :: Down a -> Down a # log1pexp :: Down a -> Down a # log1mexp :: Down a -> Down a #
RealFloat a => RealFloat (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods floatRadix :: Down a -> Integer # floatDigits :: Down a -> Int # floatRange :: Down a -> (Int, Int) # decodeFloat :: Down a -> (Integer, Int) # encodeFloat :: Integer -> Int -> Down a # exponent :: Down a -> Int # significand :: Down a -> Down a # scaleFloat :: Int -> Down a -> Down a # isNaN :: Down a -> Bool # isInfinite :: Down a -> Bool # isDenormalized :: Down a -> Bool # isNegativeZero :: Down a -> Bool # isIEEE :: Down a -> Bool # atan2 :: Down a -> Down a -> Down a #
Generic (Down a) |
Instance details Defined in GHC.Generics Associated Types
type Rep (Down a) | Since: base-4.12.0.0
Instance details Defined in GHC.Generics type Rep (Down a) = D1 ('MetaData "Down" "Data.Ord" "base" 'True) (C1 ('MetaCons "Down" 'PrefixI 'True) (S1 ('MetaSel ('Just "getDown") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))
Methods from :: Down a -> Rep (Down a) x # to :: Rep (Down a) x -> Down a #
Ix a => Ix (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods range :: (Down a, Down a) -> [Down a] # index :: (Down a, Down a) -> Down a -> Int # unsafeIndex :: (Down a, Down a) -> Down a -> Int # inRange :: (Down a, Down a) -> Down a -> Bool # rangeSize :: (Down a, Down a) -> Int # unsafeRangeSize :: (Down a, Down a) -> Int #
Num a => Num (Down a) | Since: base-4.11.0.0
Instance details Defined in Data.Ord Methods (+) :: Down a -> Down a -> Down a # (-) :: Down a -> Down a -> Down a # (*) :: Down a -> Down a -> Down a # negate :: Down a -> Down a # abs :: Down a -> Down a # signum :: Down a -> Down a # fromInteger :: Integer -> Down a #
Read a => Read (Down a) | This instance would be equivalent to the derived instances of the `Down` newtype if the `getDown` field were removed Since: base-4.7.0.0
Instance details Defined in Data.Ord Methods readsPrec :: Int -> ReadS (Down a) # readList :: ReadS [Down a] # readPrec :: ReadPrec (Down a) # readListPrec :: ReadPrec [Down a] #
Fractional a => Fractional (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods (/) :: Down a -> Down a -> Down a # recip :: Down a -> Down a # fromRational :: Rational -> Down a #
Real a => Real (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods toRational :: Down a -> Rational #
RealFrac a => RealFrac (Down a) | Since: base-4.14.0.0
Instance details Defined in Data.Ord Methods properFraction :: Integral b => Down a -> (b, Down a) # truncate :: Integral b => Down a -> b # round :: Integral b => Down a -> b # ceiling :: Integral b => Down a -> b # floor :: Integral b => Down a -> b #
Show a => Show (Down a) | This instance would be equivalent to the derived instances of the `Down` newtype if the `getDown` field were removed Since: base-4.7.0.0
Instance details Defined in Data.Ord Methods showsPrec :: Int -> Down a -> ShowS # show :: Down a -> String # showList :: [Down a] -> ShowS #
NFData a => NFData (Down a) | Since: deepseq-1.4.0.0
Instance details Defined in Control.DeepSeq Methods rnf :: Down a -> () #
Eq a => Eq (Down a) | Since: base-4.6.0.0
Instance details Defined in Data.Ord Methods (==) :: Down a -> Down a -> Bool # (/=) :: Down a -> Down a -> Bool #
Ord a => Ord (Down a) | Since: base-4.6.0.0
Instance details Defined in Data.Ord Methods compare :: Down a -> Down a -> Ordering # (<) :: Down a -> Down a -> Bool # (<=) :: Down a -> Down a -> Bool # (>) :: Down a -> Down a -> Bool # (>=) :: Down a -> Down a -> Bool # max :: Down a -> Down a -> Down a # min :: Down a -> Down a -> Down a #
Prim a => Prim (Down a) | Since: primitive-0.6.5.0
Instance details Defined in Data.Primitive.Types Methods sizeOfType# :: Proxy (Down a) -> Int# # sizeOf# :: Down a -> Int# # alignmentOfType# :: Proxy (Down a) -> Int# # alignment# :: Down a -> Int# # indexByteArray# :: ByteArray# -> Int# -> Down a # readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Down a #) # writeByteArray# :: MutableByteArray# s -> Int# -> Down a -> State# s -> State# s # setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Down a -> State# s -> State# s # indexOffAddr# :: Addr# -> Int# -> Down a # readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, Down a #) # writeOffAddr# :: Addr# -> Int# -> Down a -> State# s -> State# s # setOffAddr# :: Addr# -> Int# -> Int# -> Down a -> State# s -> State# s #
Unbox a => Unbox (Down a) |
Instance details Defined in Data.Vector.Unboxed.Base
type Rep1 Down | Since: base-4.12.0.0
Instance details Defined in GHC.Generics type Rep1 Down = D1 ('MetaData "Down" "Data.Ord" "base" 'True) (C1 ('MetaCons "Down" 'PrefixI 'True) (S1 ('MetaSel ('Just "getDown") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
newtype MVector s (Down a) |
Instance details Defined in Data.Vector.Unboxed.Base newtype MVector s (Down a) = MV_Down (MVector s a)
type Rep (Down a) | Since: base-4.12.0.0
Instance details Defined in GHC.Generics type Rep (Down a) = D1 ('MetaData "Down" "Data.Ord" "base" 'True) (C1 ('MetaCons "Down" 'PrefixI 'True) (S1 ('MetaSel ('Just "getDown") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))
newtype Vector (Down a) |
Instance details Defined in Data.Vector.Unboxed.Base newtype Vector (Down a) = V_Down (Vector a)

# `Enum`

Re-exported from Prelude:

fromEnum :: Enum a => a -> Int #

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

# `Bounded`

Re-exported from Prelude:

minBound :: Bounded a => a #

maxBound :: Bounded a => a #

# `Num`

Re-exported from Prelude:

(+) :: Num a => a -> a -> a infixl 6 #

(-) :: Num a => a -> a -> a infixl 6 #

(*) :: Num a => a -> a -> a infixl 7 #

(^) :: (Num a, Integral b) => a -> b -> a infixr 8 #

raise a number to a non-negative integral power

negate :: Num a => a -> a #

Unary negation.

abs :: Num a => a -> a #

Absolute value.

signum :: Num a => a -> a #

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

fromInteger :: Num a => Integer -> a #

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

subtract :: Num a => a -> 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.

# `Real`

Re-exported from Prelude:

toRational :: Real a => a -> Rational #

the rational equivalent of its real argument with full precision

# `Integral`

Re-exported from Prelude:

quot :: Integral a => a -> a -> a infixl 7 #

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

rem :: Integral a => a -> a -> a infixl 7 #

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

div :: Integral a => a -> a -> a infixl 7 #

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

mod :: Integral a => a -> a -> a infixl 7 #

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

quotRem :: Integral a => a -> a -> (a, a) #

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

divMod :: Integral a => a -> a -> (a, a) #

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

toInteger :: Integral a => a -> Integer #

conversion to `Integer`

even :: Integral a => a -> Bool #

odd :: Integral a => a -> Bool #

gcd :: Integral a => a -> a -> a #

``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 :: Integral a => a -> a -> a #

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

fromIntegral :: (Integral a, Num b) => a -> b #

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`

Re-exported from Prelude:

(/) :: Fractional a => a -> a -> a infixl 7 #

Fractional division.

(^^) :: (Fractional a, Integral b) => a -> b -> a infixr 8 #

raise a number to an integral power

recip :: Fractional a => a -> a #

Reciprocal fraction.

fromRational :: Fractional a => Rational -> a #

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

realToFrac :: (Real a, Fractional b) => a -> b #

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

# `Floating`

Re-exported from Prelude:

pi :: Floating a => a #

exp :: Floating a => a -> a #

log :: Floating a => a -> a #

sqrt :: Floating a => a -> a #

(**) :: Floating a => a -> a -> a infixr 8 #

logBase :: Floating a => a -> a -> a #

sin :: Floating a => a -> a #

cos :: Floating a => a -> a #

tan :: Floating a => a -> a #

asin :: Floating a => a -> a #

acos :: Floating a => a -> a #

atan :: Floating a => a -> a #

sinh :: Floating a => a -> a #

cosh :: Floating a => a -> a #

tanh :: Floating a => a -> a #

asinh :: Floating a => a -> a #

acosh :: Floating a => a -> a #

atanh :: Floating a => a -> a #

# `RealFrac`

Re-exported from Prelude:

properFraction :: (RealFrac a, Integral b) => a -> (b, a) #

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 :: (RealFrac a, Integral b) => a -> b #

``truncate` x` returns the integer nearest `x` between zero and `x`

round :: (RealFrac a, Integral b) => a -> b #

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

ceiling :: (RealFrac a, Integral b) => a -> b #

``ceiling` x` returns the least integer not less than `x`

floor :: (RealFrac a, Integral b) => a -> b #

``floor` x` returns the greatest integer not greater than `x`

# `RealFloat`

Re-exported from Prelude:

floatRadix :: RealFloat a => a -> Integer #

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

floatDigits :: RealFloat a => a -> Int #

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

floatRange :: RealFloat a => a -> (Int, Int) #

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

decodeFloat :: RealFloat a => a -> (Integer, Int) #

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 :: RealFloat a => Integer -> Int -> a #

`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 :: RealFloat a => a -> Int #

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

significand :: RealFloat a => a -> a #

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.

scaleFloat :: RealFloat a => Int -> a -> a #

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

isNaN :: RealFloat a => a -> Bool #

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

isInfinite :: RealFloat a => a -> Bool #

`True` if the argument is an IEEE infinity or negative infinity

isDenormalized :: RealFloat a => a -> Bool #

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

isNegativeZero :: RealFloat a => a -> Bool #

`True` if the argument is an IEEE negative zero

isIEEE :: RealFloat a => a -> Bool #

`True` if the argument is an IEEE floating point number

atan2 :: RealFloat a => a -> a -> a #

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.

# `Word`

Re-exported from Data.Word:

byteSwap16 :: Word16 -> Word16 #

Reverse order of bytes in `Word16`.

Since: base-4.7.0.0

byteSwap32 :: Word32 -> Word32 #

Reverse order of bytes in `Word32`.

Since: base-4.7.0.0

byteSwap64 :: Word64 -> Word64 #

Reverse order of bytes in `Word64`.

Since: base-4.7.0.0

# `Semigroup`

Re-exported from Data.Semigroup:

(<>) :: Semigroup a => a -> a -> a infixr 6 #

An associative operation.

#### Examples

Expand

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

sappend :: Semigroup s => s -> s -> s #

# `Monoid`

Re-exported from Data.Monoid:

mempty :: Monoid a => a #

Identity of `mappend`

#### Examples

Expand

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

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

mappend :: Monoid a => a -> a -> a #

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

mconcat :: Monoid a => [a] -> a #

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

# `Functor`

Re-exported from Data.Functor:

fmap :: Functor f => (a -> b) -> f a -> f b #

`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 ``Bifunctor`` instance that allows both the last and the penultimate parameters to be mapped over.

#### Examples

Expand

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

    >>> fmap show Nothing
    Nothing
    >>> 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)

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

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

Expand

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

    >>> show <$> Nothing
    Nothing
    >>> show <$> Just 3
    Just "3"

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

    >>> show <$> Left 17
    Left 17
    >>> show <$> Right 17
    Right "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)

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

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

Expand

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

    >>> 'a' <$ Just 2
    Just 'a'
    >>> 'a' <$ Nothing
    Nothing

($>) :: Functor f => f a -> b -> f b infixl 4 #

Flipped version of `<$`.

#### Examples

Expand

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

Since: base-4.7.0.0

void :: Functor f => f a -> f () #

``void` value` discards or ignores the result of evaluation, such as the return value of an `IO` action.

#### Examples

Expand

Replace the contents of a ``Maybe` `Int`` with unit:

    >>> void Nothing
    Nothing
    >>> 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 `IO` action:

    >>> mapM print [1,2]
    1
    2
    [(),()]
    >>> void $ mapM print [1,2]
    1
    2

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 #

Flipped version of `<$>`.

    (<&>) = flip fmap

#### Examples

Expand

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

Since: base-4.11.0.0

# `Applicative`

Re-exported from Control.Applicative:

pure :: Applicative f => a -> f a #

Lift a value.

(<*>) :: Applicative f => f (a -> b) -> f a -> f b infixl 4 #

Sequential application.

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

#### Example

Expand

Used in combination with `(`<$>`)`, `(`<*>`)` 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

(<*) :: Applicative f => f a -> f b -> f a infixl 4 #

Sequence actions, discarding the value of the second argument.

(*>) :: Applicative f => f a -> f b -> f b infixl 4 #

Sequence actions, discarding the value of the first argument.

#### Examples

Expand

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

    >>> Nothing *> Just 3
    Nothing

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

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

liftA :: Applicative f => (a -> b) -> f a -> f b #

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

Expand

Using the Applicative instance for Lists:

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

Or the Applicative instance for `Maybe`

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

liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c #

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

Expand

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

liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d #

Lift a ternary function to actions.

forever :: Applicative f => f a -> f b #

Repeat an action indefinitely.

#### Examples

Expand

A common use of `forever` is to process input from network sockets, `Handle`s, 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.

traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f () #

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

Expand

Basic usage:

    >>> traverse_ print ["Hello", "world", "!"]
    "Hello"
    "world"
    "!"

for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f () #

`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

Expand

Basic usage:

    >>> for_ [1..4] print
    1
    2
    3
    4

sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f () #

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

Expand

Basic usage:

    >>> sequenceA_ [print "Hello", print "world", print "!"]
    "Hello"
    "world"
    "!"

filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a] #

This generalizes the list-based `filter` function.

replicateM_ :: Applicative m => Int -> m a -> m () #

Like `replicateM`, but discards the result.

#### Examples

Expand

    >>> replicateM_ 3 (putStrLn "a")
    a
    a
    a

zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c] #

The `zipWithM` function generalizes `zipWith` to arbitrary applicative functors.

zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m () #

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

# `Monad`

Re-exported from Control.Monad:

return :: Monad m => a -> m a #

Inject a value into the monadic type.

join :: Monad m => m (m a) -> m a #

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

Expand

A common use of `join` is to run an `IO` computation returned from an `STM` transaction, since `STM` transactions can't perform `IO` directly. Recall that

    atomically :: STM a -> IO a

is used to run `STM` transactions atomically. So, by specializing the types of `atomically` and `join` to

    atomically :: STM (IO b) -> IO (IO b)
    join       :: IO (IO b)  -> IO b

we can compose them as

    join . atomically :: STM (IO b) -> IO b

to run an `STM` transaction and the `IO` action it returns.

fail :: MonadFail m => String -> m a #

(>>=) :: Monad m => m a -> (a -> m b) -> m b infixl 1 #

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

(>>) :: Monad m => m a -> m b -> m b infixl 1 #

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

(=<<) :: Monad m => (a -> m b) -> m a -> m b infixr 1 #

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

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 #

Left-to-right composition of Kleisli arrows.

'`(bs `>=>` cs) a`' can be understood as the `do` expression

    do b <- bs a
       cs b

(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c infixr 1 #

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

(<$!>) :: Monad m => (a -> b) -> m a -> m b infixl 4 #

Strict version of `<$>`.

Since: base-4.8.0.0

liftM :: Monad m => (a1 -> r) -> m a1 -> m r #

Promote a function to a monad.

liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r #

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

    liftM2 (+) [0,1] [0,2] = [0,2,1,3]
    liftM2 (+) (Just 1) Nothing = Nothing

whenM :: Monad m => m Bool -> m () -> m () #

Run the second value if the first value returns `True`

unlessM :: Monad m => m Bool -> m () -> m () #

Run the second value if the first value returns `False`

mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () #

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

`mapM_` is just like `traverse_`, but specialised to monadic actions.

forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m () #

`forM_` is `mapM_` with its arguments flipped. For a version that doesn't ignore the results see `forM`.

`forM_` is just like `for_`, but specialised to monadic actions.

sequence_ :: (Foldable t, Monad m) => t (m a) -> m () #

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

`sequence_` is just like `sequenceA_`, but specialised to monadic actions.

foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b #

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`

foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m () #

Like `foldM`, but discards the result.

# `Foldable`

Re-exported from Data.Foldable:

foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b #

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

Expand

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]

foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b #

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

Since: base-4.6.0.0

fold :: (Foldable t, Monoid m) => t m -> m #

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

Expand

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

foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m #

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

Expand

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"

foldMapM :: (Monad m, Monoid w, Foldable t) => (a -> m w) -> t a -> m w #

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.

Since: 0.1.3.0

elem :: (Foldable t, Eq a) => a -> t a -> Bool infix 4 #

Does the element occur in the structure?

Note: `elem` is often used in infix form.

#### Examples

Expand

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 *

Since: base-4.8.0.0

notElem :: (Foldable t, Eq a) => a -> t a -> Bool infix 4 #

`notElem` is the negation of `elem`.

#### Examples

Expand

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 *

null :: Foldable t => t a -> Bool #

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

Expand

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

Since: base-4.8.0.0

length :: Foldable t => t a -> Int #

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

Expand

Basic usage:

    >>> length []
    0

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

Since: base-4.8.0.0

sum :: (Foldable t, Num a) => t a -> a #

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

#### Examples

Expand

Basic usage:

    >>> sum []
    0

    >>> sum [42]
    42

    >>> sum [1..10]
    55

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

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

Since: base-4.8.0.0

product :: (Foldable t, Num a) => t a -> a #

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

#### Examples

Expand

Basic usage:

    >>> product []
    1

    >>> product [42]
    42

    >>> product [1..10]
    3628800

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

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

Since: base-4.8.0.0

all :: Foldable t => (a -> Bool) -> t a -> Bool #

Determines whether all elements of the structure satisfy the predicate.

#### Examples

Expand

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 *

any :: Foldable t => (a -> Bool) -> t a -> Bool #

Determines whether any element of the structure satisfies the predicate.

#### Examples

Expand

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 :: Foldable t => t Bool -> Bool #

`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

Expand

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 :: Foldable t => t Bool -> Bool #

`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

Expand

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 *

toList :: Foldable t => t a -> [a] #

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

Expand

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]

Since: base-4.8.0.0

concat :: Foldable t => t [a] -> [a] #

The concatenation of all the elements of a container of lists.

#### Examples

Expand

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]

concatMap :: Foldable t => (a -> [b]) -> t a -> [b] #

Map a function over all the elements of a container and concatenate the resulting lists.

#### Examples

Expand

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]

# `Traversable`

Re-exported from Data.Traversable:

traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b) #

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

Expand

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 :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b) #

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

sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a) #

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

#### Examples

Expand

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

mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b) #

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

#### Examples

Expand

`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 :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b) #

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

sequence :: (Traversable t, Monad m) => t (m a) -> m (t a) #

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

#### Examples

Expand

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

# `Alternative`

Re-exported from Control.Applicative:

(<|>) :: Alternative f => f a -> f a -> f a infixl 3 #

An associative binary operation

some :: Alternative f => f a -> f [a] #

One or more.

many :: Alternative f => f a -> f [a] #

Zero or more.

optional :: Alternative f => f a -> f (Maybe a) #

One or none.

It is useful for modelling any computation that is allowed to fail.

#### Examples

Expand

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 *> final
    Left "it failed"
    >>> runExcept $ optional canFail *> final
    Right 42

asum :: (Foldable t, Alternative f) => t (f a) -> f a #

The sum of a collection of actions using `(<|>)`, generalizing `concat`.

`asum` is just like `msum`, but generalised to `Alternative`.

#### Examples

Expand

Basic usage:

    >>> asum [Just "Hello", Nothing, Just "World"]
    Just "Hello"

guard :: Alternative f => Bool -> f () #

Conditional failure of `Alternative` computations. Defined by

    guard True  = pure ()
    guard False = empty

#### Examples

Expand

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

    >>> safeDiv 4 2
    Just 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)

when :: Applicative f => Bool -> f () -> f () #

Conditional execution of `Applicative` expressions. For example,

    when debug (putStrLn "Debugging")

will output the string `Debugging` if the Boolean value `debug` is `True`, and otherwise do nothing.

unless :: Applicative f => Bool -> f () -> f () #

The reverse of `when`.

# `Bifunctor`

Re-exported from Data.Bifunctor:

bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d #

Map over both arguments at the same time.

    bimap f g ≡ first f . second g

#### Examples

Expand

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

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

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

first :: Bifunctor p => (a -> b) -> p a c -> p b c #

Map covariantly over the first argument.

    first f ≡ bimap f id

#### Examples

Expand

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

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

second :: Bifunctor p => (b -> c) -> p a b -> p a c #

Map covariantly over the second argument.

    second ≡ bimap id

#### Examples

Expand

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

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

# `Bifoldable`

Re-exported from Data.Bifoldable:

bifold :: (Bifoldable p, Monoid m) => p m m -> m #

Combines the elements of a structure using a monoid.

    bifold ≡ bifoldMap id id

#### Examples

Expand

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}

Since: base-4.10.0.0

bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m #

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

Expand

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]

Since: base-4.10.0.0

bifoldr :: Bifoldable p => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c #

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

Expand

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

Since: base-4.10.0.0

bifoldl :: Bifoldable p => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c #

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

Expand

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

Since: base-4.10.0.0

bifoldr' :: Bifoldable t => (a -> c -> c) -> (b -> c -> c) -> c -> t a b -> c #

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

Since: base-4.10.0.0

bifoldr1 :: Bifoldable t => (a -> a -> a) -> t a a -> a #

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

#### Examples

Expand

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

Since: base-4.10.0.0

bifoldrM :: (Bifoldable t, Monad m) => (a -> c -> m c) -> (b -> c -> m c) -> c -> t a b -> m c #

Right associative monadic bifold over a structure.

Since: base-4.10.0.0

bifoldl' :: Bifoldable t => (a -> b -> a) -> (a -> c -> a) -> a -> t b c -> a #

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

Since: base-4.10.0.0

bifoldl1 :: Bifoldable t => (a -> a -> a) -> t a a -> a #

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

#### Examples

Expand

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

Since: base-4.10.0.0

bifoldlM :: (Bifoldable t, Monad m) => (a -> b -> m a) -> (a -> c -> m a) -> a -> t b c -> m a #

Left associative monadic bifold over a structure.

#### Examples

Expand

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

Since: base-4.10.0.0

bitraverse_ :: (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f () #

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

Expand

Basic usage:

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

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

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

Since: base-4.10.0.0

bifor_ :: (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f () #

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

#### Examples

Expand

Basic usage:

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

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

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

Since: base-4.10.0.0

bisequence_ :: (Bifoldable t, Applicative f) => t (f a) (f b) -> f () #

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

Expand

Basic usage:

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

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

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

Since: base-4.10.0.0

biasum :: (Bifoldable t, Alternative f) => t (f a) (f a) -> f a #

The sum of a collection of actions, generalizing `biconcat`.

#### Examples

Expand

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

Since: base-4.10.0.0

biList :: Bifoldable t => t a a -> [a] #

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

#### Examples

Expand

Basic usage:

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

    >>> biList (Left 18)
    [18]

Since: base-4.10.0.0

binull :: Bifoldable t => t a b -> Bool #

Test whether the structure is empty.

#### Examples

Expand

Basic usage:

    >>> binull (18, 42)
    False

    >>> binull (Right 42)
    False

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

Since: base-4.10.0.0

bilength :: Bifoldable t => t a b -> Int #

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

#### Examples

Expand

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 *

Since: base-4.10.0.0

bielem :: (Bifoldable t, Eq a) => a -> t a a -> Bool #

Does the element occur in the structure?

#### Examples

Expand

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

Since: base-4.10.0.0

bimaximum :: (Bifoldable t, Ord a) => t a a -> a #

The largest element of a non-empty structure.

#### Examples

Expand

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

Since: base-4.10.0.0

biminimum :: (Bifoldable t, Ord a) => t a a -> a #

The least element of a non-empty structure.

#### Examples

Expand

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

Since: base-4.10.0.0

bisum :: (Bifoldable t, Num a) => t a a -> a #

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

#### Examples

Expand

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

Since: base-4.10.0.0

biproduct :: (Bifoldable t, Num a) => t a a -> a #

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

#### Examples

Expand

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

Since: base-4.10.0.0

biconcat :: Bifoldable t => t [a] [a] -> [a] #

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

#### Examples

Expand

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]

Since: base-4.10.0.0

biconcatMap :: Bifoldable t => (a -> [c]) -> (b -> [c]) -> t a b -> [c] #

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

#### Examples

Expand

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]

Since: base-4.10.0.0

biand :: Bifoldable t => t Bool Bool -> Bool #

`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

Expand

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 *

Since: base-4.10.0.0

bior :: Bifoldable t => t Bool Bool -> Bool #

`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

Expand

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 *

Since: base-4.10.0.0

biany :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool #

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

#### Examples

Expand

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

Since: base-4.10.0.0

biall :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool #

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

#### Examples

Expand

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

Since: base-4.10.0.0

bimaximumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a #

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

#### Examples

Expand

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

Since: base-4.10.0.0

biminimumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a #

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

#### Examples

Expand

Basic usage:

    >>> biminimumBy compare (42, 17)
    17

    >>> biminimumBy compare (Left 17)
    17

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

On empty structures, this function throws an exception:

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

Since: base-4.10.0.0

binotElem :: (Bifoldable t, Eq a) => a -> t a a -> Bool #

`binotElem` is the negation of `bielem`.

#### Examples

Expand

Basic usage:

    >>> binotElem 42 (17, 42)
    False

    >>> binotElem 42 (17, 43)
    True

    >>> binotElem 42 (Left 42)
    False

    >>> binotElem 42 (Right 13)
    True

    >>> binotElem 42 (BiList [1..5] [1..100])
    False

    >>> binotElem 42 (BiList [1..5] [1..41])
    True

Since: base-4.10.0.0

bifind :: Bifoldable t => (a -> Bool) -> t a a -> Maybe a #

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

Expand

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

Since: base-4.10.0.0

# `Bitraverse`

Re-exported from Data.Bitraversable:

bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d) #

Evaluates the relevant functions at each element in the structure, running the action, and builds a new structure with the same shape, using the results produced from sequencing the actions.

    bitraverse f g ≡ bisequenceA . bimap f g

For a version that ignores the results, see `bitraverse_`.

#### Examples

Expand

Basic usage:

    >>> bitraverse listToMaybe (find odd) (Left [])
    Nothing

    >>> bitraverse listToMaybe (find odd) (Left [1, 2, 3])
    Just (Left 1)

    >>> bitraverse listToMaybe (find odd) (Right [4, 5])
    Just (Right 5)

    >>> bitraverse listToMaybe (find odd) ([1, 2, 3], [4, 5])
    Just (1,5)

    >>> bitraverse listToMaybe (find odd) ([], [4, 5])
    Nothing

Since: base-4.10.0.0

bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b) #

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

Expand

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

Since: base-4.10.0.0

bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d) #

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

#### Examples

Expand

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

Since: base-4.10.0.0

bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) #

The `bimapAccumL` function behaves like a combination of `bimap` and `bifoldl`; it traverses a structure from left to right, threading a state of type `a` and using the given actions to compute new elements for the structure.

#### Examples

Expand

Basic usage:

    >>> bimapAccumL (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
    (8,("True","oof"))

Since: base-4.10.0.0

bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) #

The `bimapAccumR` function behaves like a combination of `bimap` and `bifoldr`; it traverses a structure from right to left, threading a state of type `a` and using the given actions to compute new elements for the structure.

#### Examples

Expand

Basic usage:

    >>> bimapAccumR (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
    (7,("True","oof"))

Since: base-4.10.0.0

# `MonadPlus`

Re-exported from Control.Monad:

mzero :: MonadPlus m => m a #

The identity of `mplus`. It should also satisfy the equations

    mzero >>= f  =  mzero
    v >> mzero   =  mzero

The default definition is

    mzero = empty

mplus :: MonadPlus m => m a -> m a -> m a #

An associative operation. The default definition is

    mplus = (<|>)

msum :: (Foldable t, MonadPlus m) => t (m a) -> m a #

The sum of a collection of actions using `(<|>)`, generalizing `concat`.

`msum` is just like `asum`, but specialised to `MonadPlus`.

#### Examples

Expand

Basic usage, using the `MonadPlus` instance for `Maybe`:

    >>> msum [Just "Hello", Nothing, Just "World"]
    Just "Hello"

mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a #

Direct `MonadPlus` equivalent of `filter`.

#### Examples

Expand

The `filter` function is just `mfilter` specialized to the list monad:

    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

# `Arrow`

Re-exported from Control.Arrow and Control.Category:

(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c') infixr 3 #

Fanout: send the input to both argument arrows and combine their output.

The default definition may be overridden with a more efficient version if desired.

(***) :: Arrow a => a b c -> a b' c' -> a (b, b') (c, c') infixr 3 #

Split the input between the two argument arrows and combine their output. Note that this is in general not a functor.

The default definition may be overridden with a more efficient version if desired.

(>>>) :: forall {k} cat (a :: k) (b :: k) (c :: k). Category cat => cat a b -> cat b c -> cat a c infixr 1 #

Left-to-right composition

# `Function`

Re-exported from Data.Function:

id :: a -> a #

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

Expand

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

    >>> Just (Just 3) >>= id
    Just 3

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

const :: a -> b -> a #

`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

Expand

    >>> const 42 "hello"
    42

    >>> map (const 42) [0..3]
    [42,42,42,42]

(.) :: (b -> c) -> (a -> b) -> a -> c infixr 9 #

Right to left function composition.

    (f . g) x = f (g x)

    f . id = f = id . f

#### Examples

Expand

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

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

    >>> let (...) = (.).(.) in ((*2)...(+)) 5 10
    30

($) :: (a -> b) -> a -> b infixr 0 #

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

Expand

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)

Expand

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

(&) :: a -> (a -> b) -> b infixl 1 #

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

Expand

    >>> 5 & (+1) & show
    "6"

    >>> sqrt $ [1 / n^2 | n <- [1..1000]] & sum & (*6)
    3.1406380562059946

Since: base-4.8.0.0

flip :: (a -> b -> c) -> b -> a -> c #

``flip` f` takes its (first) two arguments in the reverse order of `f`.

    flip f x y = f y x

    flip . flip = id

#### Examples

Expand

    >>> flip (++) "hello" "world"
    "worldhello"

    >>> let (.>) = flip (.) in (+1) .> show $ 5
    "6"

fix :: (a -> a) -> a #

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

Expand

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

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)) 5
    120

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

Expand

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 -> b -> c) -> (a -> b) -> a -> a -> c infixl 0 #

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

Expand

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

Expand

-     (*) `on` id = (*) -- (if (*) ∉ {⊥, const ⊥})

-     ((*) `on` f) `on` g = (*) `on` (f . g)

-     flip on f . flip on g = flip on (g . f)

# Miscellaneous functions

($!) :: (a -> b) -> a -> b infixr 0 #

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.

seq :: a -> b -> b infixr 0 #

The value of ``seq` a b` is bottom if `a` is bottom, and otherwise equal to `b`. In other words, it evaluates the first argument `a` to weak head normal form (WHNF). `seq` is usually introduced to improve performance by avoiding unneeded laziness.

A note on evaluation order: the expression ``seq` a b` does not guarantee that `a` will be evaluated before `b`. The only guarantee given by `seq` is that the both `a` and `b` will be evaluated before `seq` returns a value. In particular, this means that `b` may be evaluated before `a`. If you need to guarantee a specific order of evaluation, you must use the function `pseq` from the "parallel" package.

error :: HasCallStack => [Char] -> a #

`error` stops execution and displays an error message.

undefined :: HasCallStack => a #

A special case of `error`. It is expected that compilers will recognize this and insert error messages which are more appropriate to the context in which `undefined` appears.

asTypeOf :: a -> a -> a #

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

asIO :: IO a -> IO a #

Helper function to force an action to run in `IO`. Especially useful for overly general contexts, like hspec tests.

Since: 0.1.3.0

# List

Re-exported from Data.List:

(++) :: [a] -> [a] -> [a] infixr 5 #

`(++)` 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

Expand

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 `concat` `=` `foldr` `(++)` `[]` has linear performance, while `foldl` `(++)` `[]` is prone to quadratic slowdown

#### Examples

Expand

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

    >>> [] ++ [1, 2, 3]
    [1,2,3]

    >>> [3, 2, 1] ++ []
    [3,2,1]

break :: (a -> Bool) -> [a] -> ([a], [a]) #

`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

Expand

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

Expand

    >>> 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 :: Int -> [a] -> [a] #

`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

Expand

    >>> 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 :: (a -> Bool) -> [a] -> [a] #

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

#### Examples

Expand

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

filter :: (a -> Bool) -> [a] -> [a] #

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

Expand

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

lookup :: Eq a => a -> [(a, b)] -> Maybe b #

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

#### Examples

Expand

    >>> lookup 2 []
    Nothing

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

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

map :: (a -> b) -> [a] -> [b] #

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

Expand

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

replicate :: Int -> a -> [a] #

`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

Expand

    >>> replicate 0 True
    []

    >>> replicate (-1) True
    []

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

reverse :: [a] -> [a] #

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

#### Laziness

Expand

`reverse` is lazy in its elements.

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

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

#### Examples

Expand

    >>> reverse []
    []

    >>> reverse [42]
    [42]

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

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

span :: (a -> Bool) -> [a] -> ([a], [a]) #

`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

Expand

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

Expand

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

take :: Int -> [a] -> [a] #

`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

Expand

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

#### Examples

Expand

    >>> 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 :: (a -> Bool) -> [a] -> [a] #

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

#### Laziness

Expand

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

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

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

#### Examples

Expand

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

zip :: [a] -> [b] -> [(a, b)] #

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

Expand

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

zipWith :: (a -> b -> c) -> [a] -> [b] -> [c] #

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

Expand

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

nubOrd :: Ord a => [a] -> [a] #

Strip out duplicates

# `String`

Re-exported from Data.String:

fromString :: IsString a => String -> a #

lines :: String -> [String] #

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

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

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

#### Examples

Expand

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

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

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

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

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

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

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

unlines :: [String] -> String #

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

#### Examples

Expand

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

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

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

unwords :: [String] -> String #

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

`unwords` is neither left nor right inverse of `words`:

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

#### Examples

Expand

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

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

words :: String -> [String] #

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

#### Examples

Expand

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

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

## `Show`

Re-exported from Text.Show:

show :: Show a => a -> String #

A specialised variant of `showsPrec`, using precedence context zero, and returning an ordinary `String`.

## `Read`

Re-exported from Text.Read:

readMaybe :: Read a => String -> Maybe a #

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

    >>> readMaybe "123" :: Maybe Int
    Just 123

    >>> readMaybe "hello" :: Maybe Int
    Nothing

Since: base-4.6.0.0

# `NFData`

Re-exported from Control.DeepSeq:

($!!) :: NFData a => (a -> b) -> a -> b infixr 0 #

the deep analogue of `$!`. In the expression `f $!! x`, `x` is fully evaluated before the function `f` is applied to it.

Since: deepseq-1.2.0.0

rnf :: NFData a => a -> () #

`rnf` should reduce its argument to normal form (that is, fully evaluate all sub-components), and then return `()`.

### `Generic` `NFData` deriving

Starting with GHC 7.2, you can automatically derive instances for types possessing a `Generic` instance.

Note: `Generic1` can be auto-derived starting with GHC 7.4

    {-# LANGUAGE DeriveGeneric #-}

    import GHC.Generics (Generic, Generic1)
    import Control.DeepSeq

    data Foo a = Foo a String
                 deriving (Eq, Generic, Generic1)

    instance NFData a => NFData (Foo a)
    instance NFData1 Foo

    data Colour = Red | Green | Blue
                  deriving Generic

    instance NFData Colour

Starting with GHC 7.10, the example above can be written more concisely by enabling the new `DeriveAnyClass` extension:

    {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}

    import GHC.Generics (Generic)
    import Control.DeepSeq

    data Foo a = Foo a String
                 deriving (Eq, Generic, Generic1, NFData, NFData1)

    data Colour = Red | Green | Blue
                  deriving (Generic, NFData)

### Compatibility with previous `deepseq` versions

Prior to version 1.4.0.0, the default implementation of the `rnf` method was defined as

    rnf a = seq a ()

However, starting with `deepseq-1.4.0.0`, the default implementation is based on `DefaultSignatures` allowing for more accurate auto-derived `NFData` instances. If you need the previously used exact default `rnf` method implementation semantics, use

    instance NFData Colour where rnf x = seq x ()

or alternatively

    instance NFData Colour where rnf = rwhnf

or

    {-# LANGUAGE BangPatterns #-}
    instance NFData Colour where rnf !_ = ()

deepseq :: NFData a => a -> b -> b infixr 0 #

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

Since: deepseq-1.1.0.0

force :: NFData a => a -> a #

a variant of `deepseq` that is useful in some circumstances:

    force x = x `deepseq` x

`force x` fully evaluates `x`, and then returns it. Note that `force x` only performs evaluation when the value of `force x` itself is demanded, so essentially it turns shallow evaluation into deep evaluation.

`force` can be conveniently used in combination with `ViewPatterns`:

    {-# LANGUAGE BangPatterns, ViewPatterns #-}
    import Control.DeepSeq

    someFun :: ComplexData -> SomeResult
    someFun (force -> !arg) = {- 'arg' will be fully evaluated -}

Another useful application is to combine `force` with `evaluate` in order to force deep evaluation relative to other `IO` operations:

    import Control.Exception (evaluate)
    import Control.DeepSeq

    main = do
      result <- evaluate $ force $ pureComputation
      {- 'result' will be fully evaluated at this point -}
      return ()

Finally, here's an exception safe variant of the `readFile'` example:

    readFile' :: FilePath -> IO String
    readFile' fn = bracket (openFile fn ReadMode) hClose $ \h ->
                           evaluate . force =<< hGetContents h

Since: deepseq-1.2.0.0

# `Void`

Re-exported from Data.Void:

absurd :: Void -> a #

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

Since: base-4.8.0.0

# `Reader`

Re-exported from Control.Monad.Reader:

lift :: (MonadTrans t, Monad m) => m a -> t m a #

Lift a computation from the argument monad to the constructed monad.

ask :: MonadReader r m => m r #

Retrieves the monad environment.

asks #

Arguments

:: MonadReader r m |
=> (r -> a) | The selector function to apply to the environment.
-> m a |

Retrieves a function of the current environment.

local #

Arguments

:: MonadReader r m |
=> (r -> r) | The function to modify the environment.
-> m a | `Reader` to run in the modified environment.
-> m a |

Executes a computation in a modified environment.

runReader #

Arguments

:: Reader r a | A `Reader` to run.
-> r | An initial environment.
-> a |

Runs a `Reader` and extracts the final value from it. (The inverse of `reader`.)

runReaderT :: ReaderT r m a -> r -> m a #

# `ByteString`

Helper synonyms for converting bewteen lazy and strict `ByteString`s

toStrictBytes :: LByteString -> ByteString #

fromStrictBytes :: ByteString -> LByteString #

# `ShortByteString`

Re-exported from Data.ByteString.Short:

toShort :: ByteString -> ShortByteString #

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

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

fromShort :: ShortByteString -> ByteString #

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

# `Text`

tshow :: Show a => a -> Text #

decodeUtf8Lenient :: ByteString -> Text #

Re-exported from Data.Text.Encoding:

decodeUtf8' :: ByteString -> Either UnicodeException Text #

Decode a `ByteString` containing UTF-8 encoded text.

If the input contains any invalid UTF-8 data, the relevant exception will be returned, otherwise the decoded text.

decodeUtf8With :: OnDecodeError -> ByteString -> Text #

Decode a `ByteString` containing UTF-8 encoded text.

Surrogate code points in replacement character returned by `OnDecodeError` will be automatically remapped to the replacement char `U+FFFD`.

encodeUtf8 :: Text -> ByteString #

Encode text using UTF-8 encoding.

encodeUtf8Builder :: Text -> Builder #

Encode text to a ByteString `Builder` using UTF-8 encoding.

Since: text-1.1.0.0

lenientDecode :: OnDecodeError #

Replace an invalid input byte with the Unicode replacement character U+FFFD.

# `PrimMonad`

Re-exported from Control.Monad.Primitive:

primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a #

Execute a primitive operation.

Re-exported from Control.Monad.ST:

runST :: (forall s. ST s a) -> a #

Return the value computed by a state thread. The `forall` ensures that the internal state used by the `ST` computation is inaccessible to the rest of the program.