base-4.13.0.0: Basic libraries

GHC.List

Description

The List data type and its operations

Synopsis

# Documentation

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

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, ...]
>>> map (+1) [1, 2, 3]


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

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]
>>> filter odd [1, 2, 3]
[1,3]


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

Concatenate a list of lists.

head :: [a] -> a #

O(1). Extract the first element of a list, which must be non-empty.

last :: [a] -> a #

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

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

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

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

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

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

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

Since: base-4.8.0.0

null :: [a] -> Bool #

O(1). 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] #

O(n). scanl is similar to foldl, but returns a list of successive reduced values from the left:

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

Note that

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

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

O(n). 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] #

O(n). 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] #

O(n). 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] #

O(n). 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 #

O(n). lookup key assocs looks up a key in an association list.

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


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

Map a function over a list and concatenate the results.

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

O(min(m,n)). 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 _|_ [] = _|_

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

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

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

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

O(min(m,n)). 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 (+) [1, 2, 3] [4, 5, 6]
[5,7,9]


zipWith is right-lazy:

zipWith f [] _|_ = []

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

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. It is capable of list fusion, but it is restricted to its first list argument and its resulting list.

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.