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


-- | Safe wrappers for partial list functions, supporting MonadThrow.
--   
--   Data.List includes a handful of partial functions that throw
--   uncatchable exceptions when given empty lists. This package provides
--   safe alternatives for such functions based on MonadThrow which can
--   provide a variety of failure cases: Nothing, IOException, Left, etc.
@package listsafe
@version 0.1.0.0


-- | Operations on lists. This module re-exports all safe functions of
--   <a>List</a>, but wraps all partial functions which may fail. As such,
--   this module can be imported instead of <a>Data.List</a>.
--   
--   Partial functions are wrapped into the <a>MonadThrow</a>-monad from
--   <a>Control.Monad.Catch</a> and as such, have appropriate failure cases
--   for all instances. E.g.:
--   
--   <ul>
--   <li><a>Nothing</a> for <a>Maybe</a>,</li>
--   <li>the empty list for '[a]',</li>
--   <li><tt>IOException</tt> for <a>IO</a>,</li>
--   <li>lifted exceptions for monad transformers.</li>
--   </ul>
module Data.List.Safe

-- | Extract the first element of a list. Empty lists throw an
--   <a>EmptyListException</a>.
head :: MonadThrow m => [a] -> m a

-- | Extract the last element of a list. Empty lists throw an
--   <a>EmptyListException</a>.
last :: MonadThrow m => [a] -> m a

-- | Extract the elements after the head of a list. Empty lists throw an
--   <a>EmptyListException</a>.
tail :: MonadThrow m => [a] -> m [a]

-- | Return all the elements of a list except the last one. Empty lists
--   throw an <a>EmptyListException</a>.
init :: MonadThrow m => [a] -> m [a]

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value,
--   and thus must be applied to non-empty lists. Empty lists throw an
--   <a>EmptyListException</a>.
foldl1 :: MonadThrow m => (a -> a -> a) -> [a] -> m a

-- | A strict version of <a>foldl1</a>.
foldl1' :: MonadThrow m => (a -> a -> a) -> [a] -> m a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value,
--   and thus must be applied to non-empty lists. Empty lists throw an
--   <a>EmptyListException</a>.
foldr1 :: MonadThrow m => (a -> a -> a) -> [a] -> m a

-- | <a>maximum</a> returns the maximum value from a list, which must be
--   non-empty, finite, and of an ordered type. It is a special case of
--   <a>maximumBy</a>, which allows the programmer to supply their own
--   comparison function. Empty lists throw an <a>EmptyListException</a>.
maximum :: (MonadThrow m, Ord a) => [a] -> m a

-- | <a>minimum</a> returns the maximum value from a list, which must be
--   non-empty, finite, and of an ordered type. It is a special case of
--   <a>minimumBy</a>, which allows the programmer to supply their own
--   comparison function. Empty lists throw an <a>EmptyListException</a>.
minimum :: (MonadThrow m, Ord a) => [a] -> m a

-- | The <a>maximumBy</a> function takes a comparison function and a list
--   and returns the greatest element of the list by the comparison
--   function. The list must be finite and non-empty. Empty lists throw an
--   <a>EmptyListException</a>.
maximumBy :: MonadThrow m => (a -> a -> Ordering) -> [a] -> m a

-- | The <a>minimumBy</a> function takes a comparison function and a list
--   and returns the least element of the list by the comparison function.
--   The list must be finite and non-empty. Empty lists throw an
--   <a>EmptyListException</a>.
minimumBy :: MonadThrow m => (a -> a -> Ordering) -> [a] -> m a

-- | List index (subscript) operator, starting from 0. Indices larger than
--   <tt>length xs - 1</tt> throw an <a>EmptyListException</a>, negative
--   indices throw an <a>NegativeIndexException</a>.
(!!) :: (MonadThrow m, Integral n, Num n) => [a] -> n -> m a

-- | Takes a function that requires a non-empty list and wraps it in an
--   instance of <a>MonadThrow</a>. For empty lists, an
--   <a>EmptyListException</a> is thrown.
wrap :: MonadThrow m => ([a] -> b) -> [a] -> m b

-- | Signals that the list was empty or contained too few elements (in the
--   case or access by index).
data EmptyListException
EmptyListException :: EmptyListException

-- | Singals that an element with a negative index was accessed.
data NegativeIndexException
NegativeIndexException :: NegativeIndexException
instance Typeable EmptyListException
instance Typeable NegativeIndexException
instance Show EmptyListException
instance Read EmptyListException
instance Eq EmptyListException
instance Ord EmptyListException
instance Show NegativeIndexException
instance Read NegativeIndexException
instance Eq NegativeIndexException
instance Ord NegativeIndexException
instance Exception NegativeIndexException
instance Exception EmptyListException