-- 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.7
-- | 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 :: Int -> [a] -> [a]
-- |
-- dropExact n xs =
-- | n >= 0 && n <= length xs = drop n xs
-- | otherwise = error "some message"
--
dropExact :: Int -> [a] -> [a]
-- |
-- splitAtExact n xs =
-- | n >= 0 && n <= length xs = splitAt n xs
-- | otherwise = error "some message"
--
splitAtExact :: Int -> [a] -> ([a], [a])
-- |
-- zipExact xs ys =
-- | length xs == length ys = zip xs ys
-- | otherwise = error "some message"
--
zipExact :: [a] -> [b] -> [(a, b)]
-- |
-- zipWithExact f xs ys =
-- | length xs == length ys = zipWith f xs ys
-- | otherwise = error "some message"
--
zipWithExact :: (a -> b -> c) -> [a] -> [b] -> [c]
takeExactMay :: Int -> [a] -> Maybe [a]
takeExactNote :: String -> Int -> [a] -> [a]
takeExactDef :: [a] -> Int -> [a] -> [a]
dropExactMay :: Int -> [a] -> Maybe [a]
dropExactNote :: String -> Int -> [a] -> [a]
dropExactDef :: [a] -> Int -> [a] -> [a]
splitAtExactMay :: Int -> [a] -> Maybe ([a], [a])
splitAtExactNote :: String -> Int -> [a] -> ([a], [a])
splitAtExactDef :: ([a], [a]) -> Int -> [a] -> ([a], [a])
zipExactMay :: [a] -> [b] -> Maybe [(a, b)]
zipExactNote :: String -> [a] -> [b] -> [(a, b)]
zipExactDef :: [(a, b)] -> [a] -> [b] -> [(a, b)]
zipWithExactMay :: (a -> b -> c) -> [a] -> [b] -> Maybe [c]
zipWithExactNote :: String -> (a -> b -> c) -> [a] -> [b] -> [c]
zipWithExactDef :: [c] -> (a -> b -> c) -> [a] -> [b] -> [c]
-- | Foldable functions, with wrappers like the Safe module.
module Safe.Foldable
-- |
-- findJust op = fromJust . find op
--
findJust :: 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 :: 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 :: Foldable t => String -> (a -> a -> a) -> t a -> a
findJustDef :: Foldable t => a -> (a -> Bool) -> t a -> a
findJustNote :: 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 :: (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 :: (Foldable t, Ord a) => String -> t a -> a
minimumByMay :: (Foldable t, Ord a) => (a -> a -> Ordering) -> t a -> Maybe a
minimumByDef :: (Foldable t, Ord a) => a -> (a -> a -> Ordering) -> t a -> a
minimumByNote :: (Foldable t, Ord a) => String -> (a -> a -> Ordering) -> t a -> a
maximumByMay :: (Foldable t, Ord a) => (a -> a -> Ordering) -> t a -> Maybe a
maximumByDef :: (Foldable t, Ord a) => a -> (a -> a -> Ordering) -> t a -> a
maximumByNote :: (Foldable t, Ord a) => 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 :: 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 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 :: String -> a
-- | Synonym for !!, but includes more information in the error
-- message.
at :: [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 :: String -> [a] -> [a]
-- |
-- tailSafe [] = []
-- tailSafe [1,3,4] = [3,4]
--
tailSafe :: [a] -> [a]
initMay :: [a] -> Maybe [a]
initDef :: [a] -> [a] -> [a]
initNote :: 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 :: Ord a => String -> [a] -> a
maximumMay :: Ord a => [a] -> Maybe a
maximumDef :: Ord a => a -> [a] -> a
maximumNote :: Ord a => String -> [a] -> a
minimumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
minimumByDef :: a -> (a -> a -> Ordering) -> [a] -> a
minimumByNote :: String -> (a -> a -> Ordering) -> [a] -> a
maximumByMay :: (a -> a -> Ordering) -> [a] -> Maybe a
maximumByDef :: a -> (a -> a -> Ordering) -> [a] -> a
maximumByNote :: String -> (a -> a -> Ordering) -> [a] -> a
foldr1May :: (a -> a -> a) -> [a] -> Maybe a
foldr1Def :: a -> (a -> a -> a) -> [a] -> a
foldr1Note :: String -> (a -> a -> a) -> [a] -> a
foldl1May :: (a -> a -> a) -> [a] -> Maybe a
foldl1Def :: a -> (a -> a -> a) -> [a] -> a
foldl1Note :: String -> (a -> a -> a) -> [a] -> a
foldl1May' :: (a -> a -> a) -> [a] -> Maybe a
foldl1Def' :: a -> (a -> a -> a) -> [a] -> a
foldl1Note' :: String -> (a -> a -> a) -> [a] -> a
scanl1May :: (a -> a -> a) -> [a] -> Maybe [a]
scanl1Def :: [a] -> (a -> a -> a) -> [a] -> [a]
scanl1Note :: String -> (a -> a -> a) -> [a] -> [a]
scanr1May :: (a -> a -> a) -> [a] -> Maybe [a]
scanr1Def :: [a] -> (a -> a -> a) -> [a] -> [a]
scanr1Note :: String -> (a -> a -> a) -> [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 :: String -> Maybe a -> a
assertNote :: String -> Bool -> a -> a
atMay :: [a] -> Int -> Maybe a
atDef :: a -> [a] -> Int -> a
atNote :: String -> [a] -> Int -> a
readMay :: Read a => String -> Maybe a
readDef :: Read a => a -> String -> a
readNote :: Read a => String -> String -> a
lookupJustDef :: Eq a => b -> a -> [(a, b)] -> b
lookupJustNote :: Eq a => String -> a -> [(a, b)] -> b
findJustDef :: a -> (a -> Bool) -> [a] -> a
findJustNote :: String -> (a -> Bool) -> [a] -> a
elemIndexJustDef :: Eq a => Int -> a -> [a] -> Int
elemIndexJustNote :: Eq a => String -> a -> [a] -> Int
findIndexJustDef :: Int -> (a -> Bool) -> [a] -> Int
findIndexJustNote :: String -> (a -> Bool) -> [a] -> Int