rio-0.1.22.0: A standard library for Haskell

Safe Haskell | Safe-Inferred
Language | Haskell2010

RIO.List.Partial

Contents

- Basic functions
- Reducing lists (folds)
  - Special folds
- Building lists
  - Scans
- Indexing lists

Description

`List` partial functions. Import as:

    import qualified RIO.List.Partial as L'

Synopsis

- head :: HasCallStack => [a] -> a
- last :: HasCallStack => [a] -> a
- tail :: HasCallStack => [a] -> [a]
- init :: HasCallStack => [a] -> [a]
- foldl1 :: Foldable t => (a -> a -> a) -> t a -> a
- foldl1' :: HasCallStack => (a -> a -> a) -> [a] -> a
- foldr1 :: Foldable t => (a -> a -> a) -> t a -> a
- maximum :: (Foldable t, Ord a) => t a -> a
- minimum :: (Foldable t, Ord a) => t a -> a
- maximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a
- minimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a
- scanl1 :: (a -> a -> a) -> [a] -> [a]
- scanr1 :: (a -> a -> a) -> [a] -> [a]
- (!!) :: HasCallStack => [a] -> Int -> a

# Basic functions

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

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

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

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

# Reducing lists (folds)

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 *

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

A strict version of `foldl1`.

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 *

## Special folds

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

maximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a #

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

#### Examples

Expand

Basic usage:

    >>> maximumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]
    "Longest"

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

minimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a #

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

#### Examples

Expand

Basic usage:

    >>> minimumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]
    "!"

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

# Building lists

## Scans

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

\(\mathcal{O}(n)\). `scanl1` is a variant of `scanl` that has no starting value argument:

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

#### Examples

Expand

    >>> scanl1 (+) [1..4]
    [1,3,6,10]

    >>> scanl1 (+) []
    []

    >>> scanl1 (-) [1..4]
    [1,-1,-4,-8]

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

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

    >>> take 10 (scanl1 (+) [1..])
    [1,3,6,10,15,21,28,36,45,55]

    >>> take 1 (scanl1 undefined ('a' : undefined))
    "a"

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

\(\mathcal{O}(n)\). `scanr1` is a variant of `scanr` that has no starting value argument.

#### Examples

Expand

    >>> scanr1 (+) [1..4]
    [10,9,7,4]

    >>> scanr1 (+) []
    []

    >>> scanr1 (-) [1..4]
    [-2,3,-1,4]

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

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

    >>> force $ scanr1 (+) [1..]
    *** Exception: stack overflow

# Indexing lists

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