Safe

safe-0.3.21: Library of safe (exception free) functions

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 #

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 #

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

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

    lookupJust key = fromJust . lookup key

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

    findJust op = fromJust . find op

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

    elemIndexJust op = fromJust . elemIndex op

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

    findIndexJust op = fromJust . findIndex op

# Partial functions

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

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 #

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

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

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

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

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

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

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

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

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 #

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 #

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 #

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

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

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 #

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

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

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 #

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

Deprecated: Use `foldr1May` instead.

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

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

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

Deprecated: Use `foldl1May` instead.

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

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

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

Deprecated: Use `foldl1May'` instead.

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 #

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 #

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 #

`readNote` uses `readEitherSafe` for the error message.

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

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

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 #

# Discouraged

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

New users are recommended to use `minimumBound` or `maximumBound` instead.

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

New users are recommended to use `minimumBound` or `maximumBound` instead.

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

New users are recommended to use `minimumBoundBy` or `maximumBoundBy` instead.

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

New users are recommended to use `minimumBoundBy` or `maximumBoundBy` instead.