-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library of safe (exception free) functions
--   
--   A library wrapping <tt>Prelude</tt>/<tt>Data.List</tt> functions that
--   can throw exceptions, such as <tt>head</tt> and <tt>!!</tt>. Each
--   unsafe function has up to four variants, e.g. with <tt>tail</tt>:
--   
--   <ul>
--   <li><tt>tail :: [a] -&gt; [a]</tt>, raises an error on <tt>tail
--   []</tt>.</li>
--   <li><tt>tailMay :: [a] -&gt; <i>Maybe</i> [a]</tt>, turns errors into
--   <tt>Nothing</tt>.</li>
--   <li><tt>tailDef :: <i>[a]</i> -&gt; [a] -&gt; [a]</tt>, takes a
--   default to return on errors.</li>
--   <li><tt>tailNote :: <i>String</i> -&gt; [a] -&gt; [a]</tt>, takes an
--   extra argument which supplements the error message.</li>
--   <li><tt>tailSafe :: [a] -&gt; [a]</tt>, returns some sensible default
--   if possible, <tt>[]</tt> in the case of <tt>tail</tt>.</li>
--   </ul>
--   
--   This package is divided into three modules:
--   
--   <ul>
--   <li><a>Safe</a> contains safe variants of <tt>Prelude</tt> and
--   <tt>Data.List</tt> functions.</li>
--   <li><a>Safe.Foldable</a> contains safe variants of <tt>Foldable</tt>
--   functions.</li>
--   <li><a>Safe.Exact</a> creates crashing versions of functions like
--   <tt>zip</tt> (errors if the lists are not equal) and <tt>take</tt>
--   (errors if there are not enough elements), then wraps them to provide
--   safe variants.</li>
--   </ul>
@package safe
@version 0.3.15


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


-- | <a>Foldable</a> functions, with wrappers like the <a>Safe</a> module.
module Safe.Foldable

-- | <pre>
--   findJust op = fromJust . find op
--   </pre>
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

-- | <i>Deprecated: Use <tt>foldl f mempty</tt> instead.</i>
foldl1Safe :: (Monoid m, Foldable t) => (m -> m -> m) -> t m -> m

-- | <i>Deprecated: Use <tt>foldr f mempty</tt> instead.</i>
foldr1Safe :: (Monoid m, Foldable t) => (m -> m -> m) -> t m -> m

-- | <i>Deprecated: Use <tt>findJustDef mempty</tt> instead.</i>
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
--   <a>Safe</a> module. For example:
--   
--   <ul>
--   <li><tt><a>takeExact</a> 3 [1,2]</tt> raises an error, in contrast to
--   <a>take</a> which would return just two elements.</li>
--   <li><tt><a>takeExact</a> (-1) [1,2]</tt> raises an error, in contrast
--   to <a>take</a> which would return no elements.</li>
--   <li><tt><a>zip</a> [1,2] [1]</tt> raises an error, in contrast to
--   <a>zip</a> which would only pair up the first element.</li>
--   </ul>
--   
--   Note that the <tt>May</tt> variants of these functions are
--   <i>strict</i> in at least the bit of the prefix of the list required
--   to spot errors. The standard and <tt>Note</tt> versions are lazy, but
--   throw errors later in the process - they do not check upfront.
module Safe.Exact

-- | <pre>
--   takeExact n xs =
--     | n &gt;= 0 &amp;&amp; n &lt;= length xs = take n xs
--     | otherwise                = error "some message"
--   </pre>
takeExact :: Partial => Int -> [a] -> [a]

-- | <pre>
--   dropExact n xs =
--     | n &gt;= 0 &amp;&amp; n &lt;= length xs = drop n xs
--     | otherwise                = error "some message"
--   </pre>
dropExact :: Partial => Int -> [a] -> [a]

-- | <pre>
--   splitAtExact n xs =
--     | n &gt;= 0 &amp;&amp; n &lt;= length xs = splitAt n xs
--     | otherwise                = error "some message"
--   </pre>
splitAtExact :: Partial => Int -> [a] -> ([a], [a])

-- | <pre>
--   zipExact xs ys =
--     | length xs == length ys = zip xs ys
--     | otherwise              = error "some message"
--   </pre>
zipExact :: Partial => [a] -> [b] -> [(a, b)]

-- | <pre>
--   zipWithExact f xs ys =
--     | length xs == length ys = zipWith f xs ys
--     | otherwise              = error "some message"
--   </pre>
zipWithExact :: Partial => (a -> b -> c) -> [a] -> [b] -> [c]

-- | <pre>
--   zip3Exact xs ys zs =
--     | length xs == length ys &amp;&amp; length xs == length zs = zip3 xs ys zs
--     | otherwise                                        = error "some message"
--   </pre>
zip3Exact :: Partial => [a] -> [b] -> [c] -> [(a, b, c)]

-- | <pre>
--   zipWith3Exact f xs ys zs =
--     | length xs == length ys &amp;&amp; length xs == length zs = zipWith3 f xs ys zs
--     | otherwise                                        = error "some message"
--   </pre>
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 <tt>Prelude</tt>/<tt>Data.List</tt> functions that
--   can throw exceptions, such as <tt>head</tt> and <tt>!!</tt>. Each
--   unsafe function has up to four variants, e.g. with <tt>tail</tt>:
--   
--   <ul>
--   <li><tt><a>tail</a> :: [a] -&gt; [a]</tt>, raises an error on <tt>tail
--   []</tt>.</li>
--   <li><tt><a>tailMay</a> :: [a] -&gt; <i>Maybe</i> [a]</tt>, turns
--   errors into <tt>Nothing</tt>.</li>
--   <li><tt><a>tailDef</a> :: <i>[a]</i> -&gt; [a] -&gt; [a]</tt>, takes a
--   default to return on errors.</li>
--   <li><tt><a>tailNote</a> :: <a>Partial</a> =&gt; <i>String</i> -&gt;
--   [a] -&gt; [a]</tt>, takes an extra argument which supplements the
--   error message.</li>
--   <li><tt><a>tailSafe</a> :: [a] -&gt; [a]</tt>, returns some sensible
--   default if possible, <tt>[]</tt> in the case of <tt>tail</tt>.</li>
--   </ul>
--   
--   All functions marked with the <tt><a>Partial</a></tt> constraint are
--   not total, and will produce stack traces on error, on GHC versions
--   which support them (see <a>GHC.Stack</a>).
--   
--   This module also introduces some new functions, documented at the top
--   of the module.
module Safe

-- | Synonym for <a>error</a>. Used for instances where the program has
--   decided to exit because of invalid user input, or the user pressed
--   quit etc. This function allows <a>error</a> to be reserved for
--   programmer errors.
abort :: Partial => String -> a

-- | Synonym for <a>!!</a>, but includes more information in the error
--   message.
at :: Partial => [a] -> Int -> a

-- | <pre>
--   lookupJust key = fromJust . lookup key
--   </pre>
lookupJust :: Eq a => a -> [(a, b)] -> b

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

-- | <pre>
--   elemIndexJust op = fromJust . elemIndex op
--   </pre>
elemIndexJust :: Eq a => a -> [a] -> Int

-- | <pre>
--   findIndexJust op = fromJust . findIndex op
--   </pre>
findIndexJust :: (a -> Bool) -> [a] -> Int

-- | <pre>
--   tailMay [] = Nothing
--   tailMay [1,3,4] = Just [3,4]
--   </pre>
tailMay :: [a] -> Maybe [a]

-- | <pre>
--   tailDef [12] [] = [12]
--   tailDef [12] [1,3,4] = [3,4]
--   </pre>
tailDef :: [a] -> [a] -> [a]

-- | <pre>
--   tailNote "help me" [] = error "Safe.tailNote [], help me"
--   tailNote "help me" [1,3,4] = [3,4]
--   </pre>
tailNote :: Partial => String -> [a] -> [a]

-- | <pre>
--   tailSafe [] = []
--   tailSafe [1,3,4] = [3,4]
--   </pre>
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 <a>fromMaybe</a>, to fit the naming scheme of
--   this package. Generally using <a>fromMaybe</a> 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

-- | <a>readNote</a> uses <a>readEitherSafe</a> for the error message.
readNote :: (Partial, Read a) => String -> String -> a

-- | This function provides a more precise error message than
--   <tt>readEither</tt> from <tt>base</tt>.
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
