-- 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.17

-- | 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 = HasCallStack

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

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

-- | 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, Partial) => a -> [(a, b)] -> b

-- | 
--   findJust op = fromJust . find op
--   
findJust :: (a -> Bool) -> [a] -> a

-- | 
--   elemIndexJust op = fromJust . elemIndex op
--   
elemIndexJust :: (Partial, 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 :: Partial => String -> [a] -> a
lastMay :: [a] -> Maybe a
lastDef :: a -> [a] -> a
lastNote :: Partial => 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
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
