Safe Haskell	Safe-Inferred
Language	Haskell2010

Safe

Contents

New functions
Partial functions
Safe wrappers
Discouraged

Description

A module wrapping Prelude/Data.List functions that can throw exceptions, such as head and !!. Each unsafe function has up to five variants, e.g. with tail:

tail :: [a] -> [a], raises an error on tail [], as provided by Prelude.
tailErr :: [a] -> [a], alias for tail that doesn't trigger an x-partial warning and does raise errors.
tailMay :: [a] -> Maybe [a], turns errors into Nothing.
tailDef :: [a] -> [a] -> [a], takes a default to return on errors.
tailNote :: Partial => String -> [a] -> [a], takes an extra argument which supplements the error message.
tailSafe :: [a] -> [a], returns some sensible default if possible, [] in the case of tail.

All functions marked with the Partial constraint are not total, and will produce stack traces on error, on GHC versions which support them (see GHC.Stack).

This module also introduces some new functions, documented at the top of the module.

Synopsis

abort :: Partial => String -> a
at :: Partial => [a] -> Int -> a
lookupJust :: (Eq a, Partial) => a -> [(a, b)] -> b
findJust :: (a -> Bool) -> [a] -> a
elemIndexJust :: (Partial, Eq a) => a -> [a] -> Int
findIndexJust :: (a -> Bool) -> [a] -> Int
tailErr :: Partial => [a] -> [a]
headErr :: Partial => [a] -> a
tailMay :: [a] -> Maybe [a]
tailDef :: [a] -> [a] -> [a]
tailNote :: Partial => String -> [a] -> [a]
tailSafe :: [a] -> [a]
initMay :: [a] -> Maybe [a]
initDef :: [a] -> [a] -> [a]
initNote :: Partial => String -> [a] -> [a]
initSafe :: [a] -> [a]
headMay :: [a] -> Maybe a
headDef :: a -> [a] -> a
headNote :: Partial => String -> [a] -> a
lastMay :: [a] -> Maybe a
lastDef :: a -> [a] -> a
lastNote :: Partial => String -> [a] -> a
minimumMay :: Ord a => [a] -> Maybe a
minimumNote :: (Partial, Ord a) => String -> [a] -> a
maximumMay :: Ord a => [a] -> Maybe a
maximumNote :: (Partial, Ord a) => String -> [a] -> a
minimumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
minimumByNote :: Partial => String -> (a -> a -> Ordering) -> [a] -> a
maximumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
maximumByNote :: Partial => String -> (a -> a -> Ordering) -> [a] -> a
minimumBoundBy :: a -> (a -> a -> Ordering) -> [a] -> a
maximumBoundBy :: a -> (a -> a -> Ordering) -> [a] -> a
maximumBounded :: (Ord a, Bounded a) => [a] -> a
maximumBound :: Ord a => a -> [a] -> a
minimumBounded :: (Ord a, Bounded a) => [a] -> a
minimumBound :: Ord a => a -> [a] -> a
foldr1May :: (a -> a -> a) -> [a] -> Maybe a
foldr1Def :: a -> (a -> a -> a) -> [a] -> a
foldr1Note :: Partial => String -> (a -> a -> a) -> [a] -> a
foldl1May :: (a -> a -> a) -> [a] -> Maybe a
foldl1Def :: a -> (a -> a -> a) -> [a] -> a
foldl1Note :: Partial => String -> (a -> a -> a) -> [a] -> a
foldl1May' :: (a -> a -> a) -> [a] -> Maybe a
foldl1Def' :: a -> (a -> a -> a) -> [a] -> a
foldl1Note' :: Partial => String -> (a -> a -> a) -> [a] -> a
scanl1May :: (a -> a -> a) -> [a] -> Maybe [a]
scanl1Def :: [a] -> (a -> a -> a) -> [a] -> [a]
scanl1Note :: Partial => String -> (a -> a -> a) -> [a] -> [a]
scanr1May :: (a -> a -> a) -> [a] -> Maybe [a]
scanr1Def :: [a] -> (a -> a -> a) -> [a] -> [a]
scanr1Note :: Partial => String -> (a -> a -> a) -> [a] -> [a]
cycleMay :: [a] -> Maybe [a]
cycleDef :: [a] -> [a] -> [a]
cycleNote :: Partial => String -> [a] -> [a]
fromJustDef :: a -> Maybe a -> a
fromJustNote :: Partial => String -> Maybe a -> a
assertNote :: Partial => String -> Bool -> a -> a
atMay :: [a] -> Int -> Maybe a
atDef :: a -> [a] -> Int -> a
atNote :: Partial => String -> [a] -> Int -> a
readMay :: Read a => String -> Maybe a
readDef :: Read a => a -> String -> a
readNote :: (Partial, Read a) => String -> String -> a
readEitherSafe :: Read a => String -> Either String a
lookupJustDef :: Eq a => b -> a -> [(a, b)] -> b
lookupJustNote :: (Partial, Eq a) => String -> a -> [(a, b)] -> b
findJustDef :: a -> (a -> Bool) -> [a] -> a
findJustNote :: Partial => String -> (a -> Bool) -> [a] -> a
elemIndexJustDef :: Eq a => Int -> a -> [a] -> Int
elemIndexJustNote :: (Partial, Eq a) => String -> a -> [a] -> Int
findIndexJustDef :: Int -> (a -> Bool) -> [a] -> Int
findIndexJustNote :: Partial => String -> (a -> Bool) -> [a] -> Int
toEnumMay :: (Enum a, Bounded a) => Int -> Maybe a
toEnumDef :: (Enum a, Bounded a) => a -> Int -> a
toEnumNote :: (Partial, Enum a, Bounded a) => String -> Int -> a
toEnumSafe :: (Enum a, Bounded a) => Int -> a
succMay :: (Enum a, Eq a, Bounded a) => a -> Maybe a
succDef :: (Enum a, Eq a, Bounded a) => a -> a -> a
succNote :: (Partial, Enum a, Eq a, Bounded a) => String -> a -> a
succSafe :: (Enum a, Eq a, Bounded a) => a -> a
predMay :: (Enum a, Eq a, Bounded a) => a -> Maybe a
predDef :: (Enum a, Eq a, Bounded a) => a -> a -> a
predNote :: (Partial, Enum a, Eq a, Bounded a) => String -> a -> a
predSafe :: (Enum a, Eq a, Bounded a) => a -> a
indexMay :: Ix a => (a, a) -> a -> Maybe Int
indexDef :: Ix a => Int -> (a, a) -> a -> Int
indexNote :: (Partial, Ix a) => String -> (a, a) -> a -> Int
minimumDef :: Ord a => a -> [a] -> a
maximumDef :: Ord a => a -> [a] -> a
minimumByDef :: a -> (a -> a -> Ordering) -> [a] -> a
maximumByDef :: a -> (a -> a -> Ordering) -> [a] -> a

New functions

abort :: Partial => String -> a Source #

Synonym for error. Used for instances where the program has decided to exit because of invalid user input, or the user pressed quit etc. This function allows error to be reserved for programmer errors.

at :: Partial => [a] -> Int -> a Source #

Synonym for !!, but includes more information in the error message.

lookupJust :: (Eq a, Partial) => a -> [(a, b)] -> b Source #

lookupJust key = fromJust . lookup key

findJust :: (a -> Bool) -> [a] -> a Source #

findJust op = fromJust . find op

elemIndexJust :: (Partial, Eq a) => a -> [a] -> Int Source #

elemIndexJust op = fromJust . elemIndex op

findIndexJust :: (a -> Bool) -> [a] -> Int Source #

findIndexJust op = fromJust . findIndex op

Partial functions

tailErr :: Partial => [a] -> [a] Source #

Identical to tail, namely that fails on an empty list. Useful to avoid the x-partial warning introduced in GHC 9.8.

tailErr [] = error "Prelude.tail: empty list"
tailErr [1,2,3] = [2,3]

headErr :: Partial => [a] -> a Source #

Identical to head, namely that fails on an empty list. Useful to avoid the x-partial warning introduced in GHC 9.8.

headErr [] = error "Prelude.head: empty list"
headErr [1,2,3] = 1

Safe wrappers

tailMay :: [a] -> Maybe [a] Source #

tailMay [] = Nothing
tailMay [1,3,4] = Just [3,4]

tailDef :: [a] -> [a] -> [a] Source #

tailDef [12] [] = [12]
tailDef [12] [1,3,4] = [3,4]

tailNote :: Partial => String -> [a] -> [a] Source #

tailNote "help me" [] = error "Safe.tailNote [], help me"
tailNote "help me" [1,3,4] = [3,4]

tailSafe :: [a] -> [a] Source #

tailSafe [] = []
tailSafe [1,3,4] = [3,4]

initMay :: [a] -> Maybe [a] Source #

initDef :: [a] -> [a] -> [a] Source #

initNote :: Partial => String -> [a] -> [a] Source #

initSafe :: [a] -> [a] Source #

headMay :: [a] -> Maybe a Source #

headDef :: a -> [a] -> a Source #

headNote :: Partial => String -> [a] -> a Source #

lastMay :: [a] -> Maybe a Source #

lastDef :: a -> [a] -> a Source #

lastNote :: Partial => String -> [a] -> a Source #

minimumMay :: Ord a => [a] -> Maybe a Source #

minimumNote :: (Partial, Ord a) => String -> [a] -> a Source #

maximumMay :: Ord a => [a] -> Maybe a Source #

maximumNote :: (Partial, Ord a) => String -> [a] -> a Source #

minimumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a Source #

minimumByNote :: Partial => String -> (a -> a -> Ordering) -> [a] -> a Source #

maximumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a Source #

maximumByNote :: Partial => String -> (a -> a -> Ordering) -> [a] -> a Source #

minimumBoundBy :: a -> (a -> a -> Ordering) -> [a] -> a Source #

The smallest element of a list with respect to the given comparison function. The result is bounded by the value given as the first argument.

maximumBoundBy :: a -> (a -> a -> Ordering) -> [a] -> a Source #

The largest element of a list with respect to the given comparison function. The result is bounded by the value given as the first argument.

maximumBounded :: (Ord a, Bounded a) => [a] -> a Source #

The largest element of a list. The result is bounded by minBound.

maximumBound :: Ord a => a -> [a] -> a Source #

The largest element of a list. The result is bounded by the value given as the first argument.

minimumBounded :: (Ord a, Bounded a) => [a] -> a Source #

The largest element of a list. The result is bounded by maxBound.

minimumBound :: Ord a => a -> [a] -> a Source #

The smallest element of a list. The result is bounded by the value given as the first argument.

foldr1May :: (a -> a -> a) -> [a] -> Maybe a Source #

foldr1Def :: a -> (a -> a -> a) -> [a] -> a Source #

Deprecated: Use foldr1May instead.

foldr1Note :: Partial => String -> (a -> a -> a) -> [a] -> a Source #

foldl1May :: (a -> a -> a) -> [a] -> Maybe a Source #

foldl1Def :: a -> (a -> a -> a) -> [a] -> a Source #

Deprecated: Use foldl1May instead.

foldl1Note :: Partial => String -> (a -> a -> a) -> [a] -> a Source #

foldl1May' :: (a -> a -> a) -> [a] -> Maybe a Source #

foldl1Def' :: a -> (a -> a -> a) -> [a] -> a Source #

Deprecated: Use foldl1May' instead.

foldl1Note' :: Partial => String -> (a -> a -> a) -> [a] -> a Source #

scanl1May :: (a -> a -> a) -> [a] -> Maybe [a] Source #

scanl1Def :: [a] -> (a -> a -> a) -> [a] -> [a] Source #

scanl1Note :: Partial => String -> (a -> a -> a) -> [a] -> [a] Source #

scanr1May :: (a -> a -> a) -> [a] -> Maybe [a] Source #

scanr1Def :: [a] -> (a -> a -> a) -> [a] -> [a] Source #

scanr1Note :: Partial => String -> (a -> a -> a) -> [a] -> [a] Source #

cycleMay :: [a] -> Maybe [a] Source #

cycleDef :: [a] -> [a] -> [a] Source #

cycleNote :: Partial => String -> [a] -> [a] Source #

fromJustDef :: a -> Maybe a -> a Source #

An alternative name for fromMaybe, to fit the naming scheme of this package. Generally using fromMaybe directly would be considered better style.

fromJustNote :: Partial => String -> Maybe a -> a Source #

assertNote :: Partial => String -> Bool -> a -> a Source #

atMay :: [a] -> Int -> Maybe a Source #

atDef :: a -> [a] -> Int -> a Source #

atNote :: Partial => String -> [a] -> Int -> a Source #

readMay :: Read a => String -> Maybe a Source #

readDef :: Read a => a -> String -> a Source #

readNote :: (Partial, Read a) => String -> String -> a Source #

readNote uses readEitherSafe for the error message.

readEitherSafe :: Read a => String -> Either String a Source #

This function provides a more precise error message than readEither from base.

lookupJustDef :: Eq a => b -> a -> [(a, b)] -> b Source #

lookupJustNote :: (Partial, Eq a) => String -> a -> [(a, b)] -> b Source #

findJustDef :: a -> (a -> Bool) -> [a] -> a Source #

findJustNote :: Partial => String -> (a -> Bool) -> [a] -> a Source #

elemIndexJustDef :: Eq a => Int -> a -> [a] -> Int Source #

elemIndexJustNote :: (Partial, Eq a) => String -> a -> [a] -> Int Source #

findIndexJustDef :: Int -> (a -> Bool) -> [a] -> Int Source #

findIndexJustNote :: Partial => String -> (a -> Bool) -> [a] -> Int Source #

toEnumMay :: (Enum a, Bounded a) => Int -> Maybe a Source #

toEnumDef :: (Enum a, Bounded a) => a -> Int -> a Source #

toEnumNote :: (Partial, Enum a, Bounded a) => String -> Int -> a Source #

toEnumSafe :: (Enum a, Bounded a) => Int -> a Source #

succMay :: (Enum a, Eq a, Bounded a) => a -> Maybe a Source #

succDef :: (Enum a, Eq a, Bounded a) => a -> a -> a Source #

succNote :: (Partial, Enum a, Eq a, Bounded a) => String -> a -> a Source #

succSafe :: (Enum a, Eq a, Bounded a) => a -> a Source #

predMay :: (Enum a, Eq a, Bounded a) => a -> Maybe a Source #

predDef :: (Enum a, Eq a, Bounded a) => a -> a -> a Source #

predNote :: (Partial, Enum a, Eq a, Bounded a) => String -> a -> a Source #

predSafe :: (Enum a, Eq a, Bounded a) => a -> a Source #

indexMay :: Ix a => (a, a) -> a -> Maybe Int Source #

indexDef :: Ix a => Int -> (a, a) -> a -> Int Source #

indexNote :: (Partial, Ix a) => String -> (a, a) -> a -> Int Source #

Discouraged

minimumDef :: Ord a => a -> [a] -> a Source #

New users are recommended to use minimumBound or maximumBound instead.

maximumDef :: Ord a => a -> [a] -> a Source #

New users are recommended to use minimumBound or maximumBound instead.

minimumByDef :: a -> (a -> a -> Ordering) -> [a] -> a Source #

New users are recommended to use minimumBoundBy or maximumBoundBy instead.

maximumByDef :: a -> (a -> a -> Ordering) -> [a] -> a Source #

New users are recommended to use minimumBoundBy or maximumBoundBy instead.