{-# LANGUAGE Safe #-}

-- | This module contains safe functions to work with list type (mostly with 'NonEmpty').

module Universum.List.Safe
       ( uncons
       , whenNotNull
       , whenNotNullM
       , foldr1
       , foldl1
       , minimum
       , maximum
       , minimumBy
       , maximumBy
       ) where

import qualified Data.Foldable as F
import Data.Ord (Ord, Ordering)

import Universum.Applicative (Applicative, pass)
import Universum.List.Reexport (NonEmpty (..))
import Universum.Monad (Maybe (..), Monad (..))

-- $setup
-- >>> import Universum.Applicative (pure)
-- >>> import Universum.Base ((==), (+), even)
-- >>> import Universum.Bool (Bool (..), not)
-- >>> import Universum.Container (length)
-- >>> import Universum.Function (($))
-- >>> import Universum.Print (print)

-- | Destructuring list into its head and tail if possible. This function is total.
--
-- >>> uncons []
-- Nothing
-- >>> uncons [1..5]
-- Just (1,[2,3,4,5])
-- >>> uncons (5 : [1..5]) >>= \(f, l) -> pure $ f == length l
-- Just True
uncons :: [a] -> Maybe (a, [a])
uncons :: [a] -> Maybe (a, [a])
uncons []     = Maybe (a, [a])
forall a. Maybe a
Nothing
uncons (a
x:[a]
xs) = (a, [a]) -> Maybe (a, [a])
forall a. a -> Maybe a
Just (a
x, [a]
xs)

{- | Performs given action over 'NonEmpty' list if given list is non empty.

>>> whenNotNull [] $ \(b :| _) -> print (not b)
>>> whenNotNull [False,True] $ \(b :| _) -> print (not b)
True

-}
whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
whenNotNull :: [a] -> (NonEmpty a -> f ()) -> f ()
whenNotNull []     NonEmpty a -> f ()
_ = f ()
forall (f :: * -> *). Applicative f => f ()
pass
whenNotNull (a
x:[a]
xs) NonEmpty a -> f ()
f = NonEmpty a -> f ()
f (a
x a -> [a] -> NonEmpty a
forall a. a -> [a] -> NonEmpty a
:| [a]
xs)
{-# INLINE whenNotNull #-}

-- | Monadic version of 'whenNotNull'.
whenNotNullM :: Monad m => m [a] -> (NonEmpty a -> m ()) -> m ()
whenNotNullM :: m [a] -> (NonEmpty a -> m ()) -> m ()
whenNotNullM m [a]
ml NonEmpty a -> m ()
f = m [a]
ml m [a] -> ([a] -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \[a]
l -> [a] -> (NonEmpty a -> m ()) -> m ()
forall (f :: * -> *) a.
Applicative f =>
[a] -> (NonEmpty a -> f ()) -> f ()
whenNotNull [a]
l NonEmpty a -> m ()
f
{-# INLINE whenNotNullM #-}

-- | A variant of 'foldl' that has no base case, and thus may only be
-- applied to 'NonEmpty'.
--
-- >>> foldl1 (+) (1 :| [2,3,4,5])
-- 15
foldl1 :: (a -> a -> a) -> NonEmpty a -> a
foldl1 :: (a -> a -> a) -> NonEmpty a -> a
foldl1 = (a -> a -> a) -> NonEmpty a -> a
forall (t :: * -> *) a. Foldable t => (a -> a -> a) -> t a -> a
F.foldl1
{-# INLINE foldl1 #-}

-- | A variant of 'foldr' that has no base case, and thus may only be
-- applied to 'NonEmpty'.
--
-- >>> foldr1 (+) (1 :| [2,3,4,5])
-- 15
foldr1 :: (a -> a -> a) -> NonEmpty a -> a
foldr1 :: (a -> a -> a) -> NonEmpty a -> a
foldr1 = (a -> a -> a) -> NonEmpty a -> a
forall (t :: * -> *) a. Foldable t => (a -> a -> a) -> t a -> a
F.foldr1
{-# INLINE foldr1 #-}

-- | The least element of a 'NonEmpty' with respect to the given
-- comparison function.
minimumBy :: (a -> a -> Ordering) -> NonEmpty a -> a
minimumBy :: (a -> a -> Ordering) -> NonEmpty a -> a
minimumBy = (a -> a -> Ordering) -> NonEmpty a -> a
forall (t :: * -> *) a.
Foldable t =>
(a -> a -> Ordering) -> t a -> a
F.minimumBy
{-# INLINE minimumBy #-}

-- | The least element of a 'NonEmpty'.
--
-- >>> minimum (1 :| [2,3,4,5])
-- 1
minimum :: Ord a => NonEmpty a -> a
minimum :: NonEmpty a -> a
minimum = NonEmpty a -> a
forall (t :: * -> *) a. (Foldable t, Ord a) => t a -> a
F.minimum
{-# INLINE minimum #-}

-- | The largest element of a 'NonEmpty' with respect to the given
-- comparison function.
maximumBy :: (a -> a -> Ordering) -> NonEmpty a -> a
maximumBy :: (a -> a -> Ordering) -> NonEmpty a -> a
maximumBy = (a -> a -> Ordering) -> NonEmpty a -> a
forall (t :: * -> *) a.
Foldable t =>
(a -> a -> Ordering) -> t a -> a
F.maximumBy
{-# INLINE maximumBy #-}

-- | The largest element of a 'NonEmpty'.
--
-- >>> maximum (1 :| [2,3,4,5])
-- 5
maximum :: Ord a => NonEmpty a -> a
maximum :: NonEmpty a -> a
maximum = NonEmpty a -> a
forall (t :: * -> *) a. (Foldable t, Ord a) => t a -> a
F.maximum
{-# INLINE maximum #-}