protolude-0.3.4: A small prelude.

Safe Haskell | Safe-Inferred
Language | Haskell2010

Protolude.Partial

Synopsis

- head :: HasCallStack => [a] -> a
- init :: HasCallStack => [a] -> [a]
- tail :: HasCallStack => [a] -> [a]
- last :: HasCallStack => [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 :: HasCallStack => [a] -> [a]
- maximum :: (Foldable t, Ord a) => t a -> a
- minimum :: (Foldable t, Ord a) => t a -> a
- (!!) :: HasCallStack => [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

head :: HasCallStack => [a] -> a #

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

To disable the warning about partiality put `{-# OPTIONS_GHC -Wno-x-partial -Wno-unrecognised-warning-flags #-}` at the top of the file. To disable it throughout a package put the same options into `ghc-options` section of Cabal file. To disable it in GHCi put `:set -Wno-x-partial -Wno-unrecognised-warning-flags` into `~/.ghci` config file. See also the migration guide.

##### Examples

Expand

    >>> head [1, 2, 3]
    1

    >>> head [1..]
    1

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

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

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

WARNING: This function is partial. Consider using `unsnoc` instead.

#### Examples

Expand

    >>> init [1, 2, 3]
    [1,2]

    >>> init [1]
    []

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

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

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

To disable the warning about partiality put `{-# OPTIONS_GHC -Wno-x-partial -Wno-unrecognised-warning-flags #-}` at the top of the file. To disable it throughout a package put the same options into `ghc-options` section of Cabal file. To disable it in GHCi put `:set -Wno-x-partial -Wno-unrecognised-warning-flags` into `~/.ghci` config file. See also the migration guide.

#### Examples

Expand

    >>> tail [1, 2, 3]
    [2,3]

    >>> tail [1]
    []

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

last :: HasCallStack => [a] -> a #

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

WARNING: This function is partial. Consider using `unsnoc` instead.

#### Examples

Expand

    >>> last [1, 2, 3]
    3

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

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

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

Expand

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

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

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.

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

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:

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

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

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

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

`foldr'` is a variant of `foldr` that performs strict reduction from right to left, i.e. starting with the right-most element. The input structure must be finite, otherwise `foldr'` runs out of space (diverges).

If you want a strict right fold in constant space, you need a structure that supports faster than O(n) access to the right-most element, such as `Seq` from the `containers` package.

This method does not run in constant space for structures such as lists that don't support efficient right-to-left iteration and so require O(n) space to perform right-to-left reduction. Use of this method with such a structure is a hint that the chosen structure may be a poor fit for the task at hand. If the order in which the elements are combined is not important, use `foldl'` instead.

@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

Expand

Basic usage:

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

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

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

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

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

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

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

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

Expand

Basic usage:

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

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

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

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

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

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

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

cycle :: HasCallStack => [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.

#### Examples

Expand

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

    >>> take 10 (cycle [42])
    [42,42,42,42,42,42,42,42,42,42]

    >>> take 10 (cycle [2, 5, 7])
    [2,5,7,2,5,7,2,5,7,2]

    >>> take 1 (cycle (42 : undefined))
    [42]

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

Expand

Basic usage:

    >>> maximum [1..10]
    10

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

    >>> maximum Nothing
    *** Exception: maximum: empty structure

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

Expand

Basic usage:

    >>> minimum [1..10]
    1

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

    >>> minimum Nothing
    *** Exception: minimum: empty structure

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

@since base-4.8.0.0

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

WARNING: This function is partial, and should only be used if you are sure that the indexing will not fail. Otherwise, use `!?`.

WARNING: This function takes linear time in the index.

#### Examples

Expand

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

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

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

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

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

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

The `fromJust` function extracts the element out of a `Just` and throws an error if its argument is `Nothing`.

#### Examples

Expand

Basic usage:

    >>> fromJust (Just 1)
    1

    >>> 2 * (fromJust (Just 10))
    20

    >>> 2 * (fromJust Nothing)
    *** Exception: Maybe.fromJust: Nothing
    ...

WARNING: This function is partial. You can use case-matching instead.

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.

    >>> read "123" :: Int
    123

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