-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Library of safe (exception free) functions
--
-- A library wrapping Prelude/Data.List functions that
-- can throw exceptions, such as head and !!. Each
-- unsafe function has up to four variants, e.g. with tail:
--
--
-- - tail :: [a] -> [a], raises an error on tail
-- [].
-- - tailMay :: [a] -> Maybe [a], turns errors into
-- Nothing.
-- - tailDef :: [a] -> [a] -> [a], takes a
-- default to return on errors.
-- - tailNote :: 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.
--
--
-- This package is divided into three modules:
--
--
-- - Safe contains safe variants of Prelude and
-- Data.List functions.
-- - Safe.Foldable contains safe variants of Foldable
-- functions.
-- - Safe.Exact creates crashing versions of functions like
-- zip (errors if the lists are not equal) and take
-- (errors if there are not enough elements), then wraps them to provide
-- safe variants.
--
@package safe
@version 0.3.13
-- | ConstraintKind synonym for marking partial functions
module Safe.Partial
-- | A constraint synonym which denotes that the function is partial, and
-- will (on GHC 8.* and up) produce a stack trace on failure. You may
-- mark your own non-total functions as Partial, if necessary, and this
-- will ensure that they produce useful stack traces.
type Partial = ?loc :: CallStack
-- | Provides functions that raise errors in corner cases instead of
-- returning "best effort" results, then provides wrappers like the
-- Safe module. For example:
--
--
-- - takeExact 3 [1,2] raises an error, in contrast to
-- take which would return just two elements.
-- - takeExact (-1) [1,2] raises an error, in contrast
-- to take which would return no elements.
-- - zip [1,2] [1] raises an error, in contrast to
-- zip which would only pair up the first element.
--
--
-- Note that the May variants of these functions are
-- strict in at least the bit of the prefix of the list required
-- to spot errors. The standard and Note versions are lazy, but
-- throw errors later in the process - they do not check upfront.
module Safe.Exact
-- |
-- takeExact n xs =
-- | n >= 0 && n <= length xs = take n xs
-- | otherwise = error "some message"
--
takeExact :: Partial => Int -> [a] -> [a]
-- |
-- dropExact n xs =
-- | n >= 0 && n <= length xs = drop n xs
-- | otherwise = error "some message"
--
dropExact :: Partial => Int -> [a] -> [a]
-- |
-- splitAtExact n xs =
-- | n >= 0 && n <= length xs = splitAt n xs
-- | otherwise = error "some message"
--
splitAtExact :: Partial => Int -> [a] -> ([a], [a])
-- |
-- zipExact xs ys =
-- | length xs == length ys = zip xs ys
-- | otherwise = error "some message"
--
zipExact :: Partial => [a] -> [b] -> [(a, b)]
-- |
-- zipWithExact f xs ys =
-- | length xs == length ys = zipWith f xs ys
-- | otherwise = error "some message"
--
zipWithExact :: Partial => (a -> b -> c) -> [a] -> [b] -> [c]
-- |
-- zip3Exact xs ys zs =
-- | length xs == length ys && length xs == length zs = zip3 xs ys zs
-- | otherwise = error "some message"
--
zip3Exact :: Partial => [a] -> [b] -> [c] -> [(a, b, c)]
-- |
-- zipWith3Exact f xs ys zs =
-- | length xs == length ys && length xs == length zs = zipWith3 f xs ys zs
-- | otherwise = error "some message"
--
zipWith3Exact :: Partial => (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]
takeExactMay :: Int -> [a] -> Maybe [a]
takeExactNote :: Partial => String -> Int -> [a] -> [a]
takeExactDef :: [a] -> Int -> [a] -> [a]
dropExactMay :: Int -> [a] -> Maybe [a]
dropExactNote :: Partial => String -> Int -> [a] -> [a]
dropExactDef :: [a] -> Int -> [a] -> [a]
splitAtExactMay :: Int -> [a] -> Maybe ([a], [a])
splitAtExactNote :: Partial => String -> Int -> [a] -> ([a], [a])
splitAtExactDef :: ([a], [a]) -> Int -> [a] -> ([a], [a])
zipExactMay :: [a] -> [b] -> Maybe [(a, b)]
zipExactNote :: Partial => String -> [a] -> [b] -> [(a, b)]
zipExactDef :: [(a, b)] -> [a] -> [b] -> [(a, b)]
zipWithExactMay :: (a -> b -> c) -> [a] -> [b] -> Maybe [c]
zipWithExactNote :: Partial => String -> (a -> b -> c) -> [a] -> [b] -> [c]
zipWithExactDef :: [c] -> (a -> b -> c) -> [a] -> [b] -> [c]
zip3ExactMay :: [a] -> [b] -> [c] -> Maybe [(a, b, c)]
zip3ExactNote :: Partial => String -> [a] -> [b] -> [c] -> [(a, b, c)]
zip3ExactDef :: [(a, b, c)] -> [a] -> [b] -> [c] -> [(a, b, c)]
zipWith3ExactMay :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> Maybe [d]
zipWith3ExactNote :: Partial => String -> (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]
zipWith3ExactDef :: [d] -> (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]
-- | Foldable functions, with wrappers like the Safe module.
module Safe.Foldable
-- |
-- findJust op = fromJust . find op
--
findJust :: (Partial, Foldable t) => (a -> Bool) -> t a -> a
foldl1May :: Foldable t => (a -> a -> a) -> t a -> Maybe a
foldl1Def :: Foldable t => a -> (a -> a -> a) -> t a -> a
foldl1Note :: (Partial, Foldable t) => String -> (a -> a -> a) -> t a -> a
foldr1May :: Foldable t => (a -> a -> a) -> t a -> Maybe a
foldr1Def :: Foldable t => a -> (a -> a -> a) -> t a -> a
foldr1Note :: (Partial, Foldable t) => String -> (a -> a -> a) -> t a -> a
findJustDef :: Foldable t => a -> (a -> Bool) -> t a -> a
findJustNote :: (Partial, Foldable t) => String -> (a -> Bool) -> t a -> a
minimumMay :: (Foldable t, Ord a) => t a -> Maybe a
minimumDef :: (Foldable t, Ord a) => a -> t a -> a
minimumNote :: (Partial, Foldable t, Ord a) => String -> t a -> a
maximumMay :: (Foldable t, Ord a) => t a -> Maybe a
maximumDef :: (Foldable t, Ord a) => a -> t a -> a
maximumNote :: (Partial, Foldable t, Ord a) => String -> t a -> a
minimumByMay :: Foldable t => (a -> a -> Ordering) -> t a -> Maybe a
minimumByDef :: Foldable t => a -> (a -> a -> Ordering) -> t a -> a
minimumByNote :: (Partial, Foldable t) => String -> (a -> a -> Ordering) -> t a -> a
maximumByMay :: Foldable t => (a -> a -> Ordering) -> t a -> Maybe a
maximumByDef :: Foldable t => a -> (a -> a -> Ordering) -> t a -> a
maximumByNote :: (Partial, Foldable t) => String -> (a -> a -> Ordering) -> t a -> a
-- | Deprecated: Use foldl f mempty instead.
foldl1Safe :: (Monoid m, Foldable t) => (m -> m -> m) -> t m -> m
-- | Deprecated: Use foldr f mempty instead.
foldr1Safe :: (Monoid m, Foldable t) => (m -> m -> m) -> t m -> m
-- | Deprecated: Use findJustDef mempty instead.
findJustSafe :: (Monoid m, Foldable t) => (m -> Bool) -> t m -> m
-- | A module wrapping Prelude/Data.List functions that
-- can throw exceptions, such as head and !!. Each
-- unsafe function has up to four variants, e.g. with tail:
--
--
-- - tail :: [a] -> [a], raises an error on tail
-- [].
-- - 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.
module Safe
-- | 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.
abort :: Partial => String -> a
-- | Synonym for !!, but includes more information in the error
-- message.
at :: Partial => [a] -> Int -> a
-- |
-- lookupJust key = fromJust . lookup key
--
lookupJust :: Eq a => a -> [(a, b)] -> b
-- |
-- findJust op = fromJust . find op
--
findJust :: (a -> Bool) -> [a] -> a
-- |
-- elemIndexJust op = fromJust . elemIndex op
--
elemIndexJust :: Eq a => a -> [a] -> Int
-- |
-- findIndexJust op = fromJust . findIndex op
--
findIndexJust :: (a -> Bool) -> [a] -> Int
-- |
-- tailMay [] = Nothing
-- tailMay [1,3,4] = Just [3,4]
--
tailMay :: [a] -> Maybe [a]
-- |
-- tailDef [12] [] = [12]
-- tailDef [12] [1,3,4] = [3,4]
--
tailDef :: [a] -> [a] -> [a]
-- |
-- tailNote "help me" [] = error "Safe.tailNote [], help me"
-- tailNote "help me" [1,3,4] = [3,4]
--
tailNote :: Partial => String -> [a] -> [a]
-- |
-- tailSafe [] = []
-- tailSafe [1,3,4] = [3,4]
--
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 :: String -> [a] -> a
lastMay :: [a] -> Maybe a
lastDef :: a -> [a] -> a
lastNote :: String -> [a] -> a
minimumMay :: Ord a => [a] -> Maybe a
minimumDef :: Ord a => a -> [a] -> a
minimumNote :: (Partial, Ord a) => String -> [a] -> a
maximumMay :: Ord a => [a] -> Maybe a
maximumDef :: Ord a => a -> [a] -> a
maximumNote :: (Partial, Ord a) => String -> [a] -> a
minimumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
minimumByDef :: a -> (a -> a -> Ordering) -> [a] -> a
minimumByNote :: Partial => String -> (a -> a -> Ordering) -> [a] -> a
maximumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
maximumByDef :: a -> (a -> a -> Ordering) -> [a] -> a
maximumByNote :: Partial => String -> (a -> a -> Ordering) -> [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]
-- | An alternative name for fromMaybe, to fit the naming scheme of
-- this package. Generally using fromMaybe directly would be
-- considered better style.
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 uses readEitherSafe for the error message.
readNote :: (Partial, Read a) => String -> String -> a
-- | This function provides a more precise error message than
-- readEither from base.
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