Safe Haskell | Safe-Inferred |
---|---|

Language | Haskell2010 |

## Synopsis

- head :: [a] -> a
- init :: [a] -> [a]
- tail :: [a] -> [a]
- last :: [a] -> a
- foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b
- foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
- foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b
- foldr' :: Foldable t => (a -> b -> b) -> b -> t a -> b
- foldr1 :: Foldable t => (a -> a -> a) -> t a -> a
- foldl1 :: Foldable t => (a -> a -> a) -> t a -> a
- cycle :: [a] -> [a]
- maximum :: (Foldable t, Ord a) => t a -> a
- minimum :: (Foldable t, Ord a) => t a -> a
- (!!) :: [a] -> Int -> a
- sum :: (Foldable t, Num a) => t a -> a
- product :: (Foldable t, Num a) => t a -> a
- fromJust :: HasCallStack => Maybe a -> a
- read :: Read a => String -> a

# Documentation

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

`>>>`

1`head [1, 2, 3]`

`>>>`

1`head [1..]`

`>>>`

*** Exception: Prelude.head: empty list`head []`

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

`>>>`

[1,2]`init [1, 2, 3]`

`>>>`

[]`init [1]`

`>>>`

*** Exception: Prelude.init: empty list`init []`

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

`>>>`

[2,3]`tail [1, 2, 3]`

`>>>`

[]`tail [1]`

`>>>`

*** Exception: Prelude.tail: empty list`tail []`

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

`>>>`

3`last [1, 2, 3]`

`>>>`

* Hangs forever *`last [1..]`

`>>>`

*** Exception: Prelude.last: empty list`last []`

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

Left-associative fold of a structure, lazy in the accumulator. This is rarely what you want, but can work well for structures with efficient right-to-left sequencing and an operator that is lazy in its left argument.

In the case of lists, `foldl`

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

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

Note that to produce the outermost application of the operator the
entire input list must be traversed. Like all left-associative folds,
`foldl`

will diverge if given an infinite list.

If you want an efficient strict left-fold, you probably want to use
`foldl'`

instead of `foldl`

. The reason for this is that the latter
does not force the *inner* results (e.g. `z `f` x1`

in the above
example) before applying them to the operator (e.g. to `(`f` x2)`

).
This results in a thunk chain \(\mathcal{O}(n)\) elements long, which
then must be evaluated from the outside-in.

For a general `Foldable`

structure this should be semantically identical
to:

foldl f z =`foldl`

f z .`toList`

#### Examples

The first example is a strict fold, which in practice is best performed
with `foldl'`

.

`>>>`

52`foldl (+) 42 [1,2,3,4]`

Though the result below is lazy, the input is reversed before prepending it to the initial accumulator, so corecursion begins only after traversing the entire input string.

`>>>`

"hgfeabcd"`foldl (\acc c -> c : acc) "abcd" "efgh"`

A left fold of a structure that is infinite on the right cannot terminate, even when for any finite input the fold just returns the initial accumulator:

`>>>`

* Hangs forever *`foldl (\a _ -> a) 0 $ repeat 1`

WARNING: When it comes to lists, you always want to use either `foldl'`

or `foldr`

instead.

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

Basic usage:

`>>>`

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

`>>>`

False`foldr (||) False []`

`>>>`

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

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

`>>>`

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

But the following doesn't terminate:

`>>>`

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

###### 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):

`>>>`

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

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*

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

Right-associative fold of a structure, strict in the accumulator. This is rarely what you want.

*Since: base-4.6.0.0*

foldr1 :: Foldable t => (a -> a -> a) -> t a -> a #

A variant of `foldr`

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

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

#### Examples

Basic usage:

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

foldl1 :: Foldable t => (a -> a -> a) -> t a -> a #

A variant of `foldl`

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

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

`foldl1`

f =`foldl1`

f .`toList`

#### Examples

Basic usage:

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

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

`>>>`

*** Exception: Prelude.cycle: empty list`cycle []`

`>>>`

[42,42,42,42,42,42,42,42,42,42...`take 20 $ cycle [42]`

`>>>`

[2,5,7,2,5,7,2,5,7,2,5,7...`take 20 $ cycle [2, 5, 7]`

maximum :: (Foldable t, Ord a) => t a -> a #

The largest element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the maximum in faster than linear time.

#### Examples

Basic usage:

`>>>`

10`maximum [1..10]`

`>>>`

*** Exception: Prelude.maximum: empty list`maximum []`

`>>>`

*** Exception: maximum: empty structure`maximum Nothing`

WARNING: This function is partial for possibly-empty structures like lists.

*Since: base-4.8.0.0*

minimum :: (Foldable t, Ord a) => t a -> a #

The least element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the minimum in faster than linear time.

#### Examples

Basic usage:

`>>>`

1`minimum [1..10]`

`>>>`

*** Exception: Prelude.minimum: empty list`minimum []`

`>>>`

*** Exception: minimum: empty structure`minimum Nothing`

WARNING: This function is partial for possibly-empty structures like lists.

*Since: base-4.8.0.0*

(!!) :: [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.

`>>>`

'a'`['a', 'b', 'c'] !! 0`

`>>>`

'c'`['a', 'b', 'c'] !! 2`

`>>>`

*** Exception: Prelude.!!: index too large`['a', 'b', 'c'] !! 3`

`>>>`

*** Exception: Prelude.!!: negative index`['a', 'b', 'c'] !! (-1)`

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

The `sum`

function computes the sum of the numbers of a structure.

#### Examples

Basic usage:

`>>>`

0`sum []`

`>>>`

42`sum [42]`

`>>>`

55`sum [1..10]`

`>>>`

7.8`sum [4.1, 2.0, 1.7]`

`>>>`

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

*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

Basic usage:

`>>>`

1`product []`

`>>>`

42`product [42]`

`>>>`

3628800`product [1..10]`

`>>>`

13.939999999999998`product [4.1, 2.0, 1.7]`

`>>>`

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

*Since: base-4.8.0.0*

fromJust :: HasCallStack => Maybe a -> a #

read :: Read a => String -> a #

The `read`

function reads input from a string, which must be
completely consumed by the input process. `read`

fails with an `error`

if the
parse is unsuccessful, and it is therefore discouraged from being used in
real applications. Use `readMaybe`

or `readEither`

for safe alternatives.

`>>>`

123`read "123" :: Int`

`>>>`

*** Exception: Prelude.read: no parse`read "hello" :: Int`