GHC.List

base-4.12.0.0: Basic libraries

Copyright | (c) The University of Glasgow 1994-2002
License | see libraries/base/LICENSE
Maintainer | cvs-ghc@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.List

Description

The List data type and its operations

Synopsis

- map :: (a -> b) -> [a] -> [b]
- (++) :: [a] -> [a] -> [a]
- filter :: (a -> Bool) -> [a] -> [a]
- concat :: [[a]] -> [a]
- head :: [a] -> a
- last :: [a] -> a
- tail :: [a] -> [a]
- init :: [a] -> [a]
- uncons :: [a] -> Maybe (a, [a])
- null :: [a] -> Bool
- length :: [a] -> Int
- (!!) :: [a] -> Int -> a
- foldl :: forall a b. (b -> a -> b) -> b -> [a] -> b
- foldl' :: forall a b. (b -> a -> b) -> b -> [a] -> b
- foldl1 :: (a -> a -> a) -> [a] -> a
- foldl1' :: (a -> a -> a) -> [a] -> a
- scanl :: (b -> a -> b) -> b -> [a] -> [b]
- scanl1 :: (a -> a -> a) -> [a] -> [a]
- scanl' :: (b -> a -> b) -> b -> [a] -> [b]
- foldr :: (a -> b -> b) -> b -> [a] -> b
- foldr1 :: (a -> a -> a) -> [a] -> a
- scanr :: (a -> b -> b) -> b -> [a] -> [b]
- scanr1 :: (a -> a -> a) -> [a] -> [a]
- iterate :: (a -> a) -> a -> [a]
- iterate' :: (a -> a) -> a -> [a]
- repeat :: a -> [a]
- replicate :: Int -> a -> [a]
- cycle :: [a] -> [a]
- take :: Int -> [a] -> [a]
- drop :: Int -> [a] -> [a]
- sum :: Num a => [a] -> a
- product :: Num a => [a] -> a
- maximum :: Ord a => [a] -> a
- minimum :: Ord a => [a] -> a
- splitAt :: Int -> [a] -> ([a], [a])
- takeWhile :: (a -> Bool) -> [a] -> [a]
- dropWhile :: (a -> Bool) -> [a] -> [a]
- span :: (a -> Bool) -> [a] -> ([a], [a])
- break :: (a -> Bool) -> [a] -> ([a], [a])
- reverse :: [a] -> [a]
- and :: [Bool] -> Bool
- or :: [Bool] -> Bool
- any :: (a -> Bool) -> [a] -> Bool
- all :: (a -> Bool) -> [a] -> Bool
- elem :: Eq a => a -> [a] -> Bool
- notElem :: Eq a => a -> [a] -> Bool
- lookup :: Eq a => a -> [(a, b)] -> Maybe b
- concatMap :: (a -> [b]) -> [a] -> [b]
- zip :: [a] -> [b] -> [(a, b)]
- zip3 :: [a] -> [b] -> [c] -> [(a, b, c)]
- zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]
- zipWith3 :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]
- unzip :: [(a, b)] -> ([a], [b])
- unzip3 :: [(a, b, c)] -> ([a], [b], [c])
- errorEmptyList :: String -> a

# Documentation

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

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

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

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

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

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

concat :: [[a]] -> [a] #

Concatenate a list of lists.

head :: [a] -> a #

Extract the first element of a list, which must be non-empty.

last :: [a] -> a #

Extract the last element of a list, which must be finite and non-empty.

tail :: [a] -> [a] #

Extract the elements after the head of a list, which must be non-empty.

init :: [a] -> [a] #

Return all the elements of a list except the last one. The list must be non-empty.

uncons :: [a] -> Maybe (a, [a]) #

Decompose a list into its head and tail. If the list is empty, returns `Nothing`. If the list is non-empty, returns ``Just` (x, xs)`, where `x` is the head of the list and `xs` its tail.

Since: base-4.8.0.0

null :: [a] -> Bool #

Test whether a list is empty.

length :: [a] -> Int #

O(n). `length` returns the length of a finite list as an `Int`. It is an instance of the more general `genericLength`, the result type of which may be any kind of number.

(!!) :: [a] -> Int -> a infixl 9 #

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

foldl :: forall a b. (b -> a -> b) -> b -> [a] -> b #

`foldl`, applied to a binary operator, a starting value (typically the left-identity of the operator), and a list, reduces the list using the binary operator, from left to right:

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

The list must be finite.

foldl' :: forall a b. (b -> a -> b) -> b -> [a] -> b #

A strict version of `foldl`.

foldl1 :: (a -> a -> a) -> [a] -> a #

`foldl1` is a variant of `foldl` that has no starting value argument, and thus must be applied to non-empty lists.

foldl1' :: (a -> a -> a) -> [a] -> a #

A strict version of `foldl1`

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

`scanl` is similar to `foldl`, but returns a list of successive reduced values from the left:

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

Note that

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

scanl1 :: (a -> a -> a) -> [a] -> [a] #

`scanl1` is a variant of `scanl` that has no starting value argument:

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

scanl' :: (b -> a -> b) -> b -> [a] -> [b] #

A strictly accumulating version of `scanl`

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

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

foldr1 :: (a -> a -> a) -> [a] -> a #

`foldr1` is a variant of `foldr` that has no starting value argument, and thus must be applied to non-empty lists.

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

`scanr` is the right-to-left dual of `scanl`. Note that

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

scanr1 :: (a -> a -> a) -> [a] -> [a] #

`scanr1` is a variant of `scanr` that has no starting value argument.

iterate :: (a -> a) -> a -> [a] #

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

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

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

iterate' :: (a -> a) -> a -> [a] #

'iterate\'' is the strict version of `iterate`.

It ensures that the result of each application of force to weak head normal form before proceeding.

repeat :: a -> [a] #

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

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.

cycle :: [a] -> [a] #

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

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

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

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

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

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

    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]

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

sum :: Num a => [a] -> a #

The `sum` function computes the sum of a finite list of numbers.

product :: Num a => [a] -> a #

The `product` function computes the product of a finite list of numbers.

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

`maximum` returns the maximum value from a list, which must be non-empty, finite, and of an ordered type. It is a special case of `maximumBy`, which allows the programmer to supply their own comparison function.

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

`minimum` returns the minimum value from a list, which must be non-empty, finite, and of an ordered type. It is a special case of `minimumBy`, which allows the programmer to supply their own comparison function.

splitAt :: Int -> [a] -> ([a], [a]) #

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

    splitAt 6 "Hello World!" == ("Hello ","World!")
    splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
    splitAt 1 [1,2,3] == ([1],[2,3])
    splitAt 3 [1,2,3] == ([1,2,3],[])
    splitAt 4 [1,2,3] == ([1,2,3],[])
    splitAt 0 [1,2,3] == ([],[1,2,3])
    splitAt (-1) [1,2,3] == ([],[1,2,3])

It is equivalent to `(`take` n xs, `drop` n xs)` when `n` is not `_|_` (`splitAt _|_ xs = _|_`). `splitAt` is an instance of the more general `genericSplitAt`, in which `n` may be of any integral type.

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

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

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

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

    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]

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

`span`, 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 satisfy `p` and second element is the remainder of the list:

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

`span` `p xs` is equivalent to `(`takeWhile` p xs, `dropWhile` p xs)`

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

`break` `p` is equivalent to ``span` (`not` . p)`.

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

`reverse` `xs` returns the elements of `xs` in reverse order. `xs` must be finite.

and :: [Bool] -> Bool #

`and` returns the conjunction of a Boolean list. For the result to be `True`, the list must be finite; `False`, however, results from a `False` value at a finite index of a finite or infinite list.

or :: [Bool] -> Bool #

`or` returns the disjunction of a Boolean list. For the result to be `False`, the list must be finite; `True`, however, results from a `True` value at a finite index of a finite or infinite list.

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

Applied to a predicate and a list, `any` determines if any element of the list satisfies the predicate. For the result to be `False`, the list must be finite; `True`, however, results from a `True` value for the predicate applied to an element at a finite index of a finite or infinite list.

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

Applied to a predicate and a list, `all` determines if all elements of the list satisfy the predicate. For the result to be `True`, the list must be finite; `False`, however, results from a `False` value for the predicate applied to an element at a finite index of a finite or infinite list.

elem :: Eq a => a -> [a] -> Bool infix 4 #

`elem` is the list membership predicate, usually written in infix form, e.g., `x `elem` xs`. For the result to be `False`, the list must be finite; `True`, however, results from an element equal to `x` found at a finite index of a finite or infinite list.

notElem :: Eq a => a -> [a] -> Bool infix 4 #

`notElem` is the negation of `elem`.

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

`lookup` `key assocs` looks up a key in an association list.

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

Map a function over a list and concatenate the results.

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

`zip` takes two lists and returns a list of corresponding pairs.

    zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]

If one input list is short, excess elements of the longer list are discarded:

    zip [1] ['a', 'b'] = [(1, 'a')]
    zip [1, 2] ['a'] = [(1, 'a')]

`zip` is right-lazy:

    zip [] _|_ = []
    zip _|_ [] = _|_

zip3 :: [a] -> [b] -> [c] -> [(a, b, c)] #

`zip3` takes three lists and returns a list of triples, analogous to `zip`.

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

`zipWith` generalises `zip` by zipping with the function given as the first argument, instead of a tupling function. For example, ``zipWith` (+)` is applied to two lists to produce the list of corresponding sums.

`zipWith` is right-lazy:

    zipWith f [] _|_ = []

zipWith3 :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d] #

The `zipWith3` function takes a function which combines three elements, as well as three lists and returns a list of their point-wise combination, analogous to `zipWith`.

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

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

unzip3 :: [(a, b, c)] -> ([a], [b], [c]) #

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

errorEmptyList :: String -> a #