RIO.List.Partial · rio-0.1.25.0

Basic functions

4 declarations

valuehead :: HasCallStack => [a] -> a

This is a partial function, it throws an error on empty lists. Use pattern matching, Data.List.uncons or listToMaybe instead. Consider refactoring to use Data.List.NonEmpty.

\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

Example1 expression

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

Example1 expression

>>> head [1..]1

Example1 expression

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

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

valuetail :: HasCallStack => [a] -> [a]

#

This is a partial function, it throws an error on empty lists. Replace it with drop 1, or use pattern matching or uncons instead. Consider refactoring to use Data.List.NonEmpty.

\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

Example1 expression

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

Example1 expression

>>> tail [1][]

Example1 expression

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

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

Example1 expression

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

Example1 expression

>>> init [1][]

Example1 expression

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

Reducing lists (folds)

3 declarations

methodfoldl1 :: (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:

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

valuefoldl1' :: HasCallStack => (a -> a -> a) -> [a] -> a

#

A strict version of foldl1.

methodfoldr1 :: (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:

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Special folds

methodmaximum :: Ord a => t a -> a

#

The largest element of a non-empty structure. This function is equivalent to foldr1 max, and its behavior on structures with multiple largest elements depends on the relevant implementation of max. For the default implementation of max (max x y = if x <= y then y else x), structure order is used as a tie-breaker: if there are multiple largest elements, the rightmost of them is chosen (this is equivalent to maximumBy compare).

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:

Example1 expression

>>> maximum [1..10]10

Example1 expression

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

Example1 expression

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

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

methodminimum :: Ord a => t a -> a

#

The least element of a non-empty structure. This function is equivalent to foldr1 min, and its behavior on structures with multiple largest elements depends on the relevant implementation of min. For the default implementation of min (min x y = if x <= y then x else y), structure order is used as a tie-breaker: if there are multiple least elements, the leftmost of them is chosen (this is equivalent to minimumBy compare).

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:

Example1 expression

>>> minimum [1..10]1

Example1 expression

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

Example1 expression

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

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

valuemaximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a

#

The largest element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple largest elements, the rightmost of them is chosen.

Examples

Basic usage:

Example1 expression

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

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

valueminimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a

#

The least element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple least elements, the leftmost of them is chosen.

Examples

Basic usage:

Example1 expression

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

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

Building lists

0 declarations

Scans

valuescanl1 :: (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

Example1 expression

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

Example1 expression

>>> scanl1 (+) [][]

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

valuescanr1 :: (a -> a -> a) -> [a] -> [a]

#

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

Examples

Example1 expression

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

Example1 expression

>>> scanr1 (+) [][]

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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

Indexing lists

1 declaration

value(!!) :: HasCallStack => [a] -> Int -> a

#

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 Data.List.!?.

WARNING: This function takes linear time in the index.

Examples

Example1 expression

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

Example1 expression

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

Example1 expression

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

Example1 expression

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