Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
RIO.List.Partial
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
>>>
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
>>>
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
>>>
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
>>>
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
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
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
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
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
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
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
>>>
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
>>>
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
>>>
['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