-- | Provides the 'NonNegative' type for enforcing a nonnegative invariant.
--
-- @since 0.1
module Numeric.Data.NonNegative
  ( -- * Type
    NonNegative (MkNonNegative),

    -- * Creation
    mkNonNegativeTH,
    mkNonNegative,
    Internal.unsafeNonNegative,
    (*!),
    reallyUnsafeNonNegative,

    -- * Elimination
    unNonNegative,

    -- * Optics
    -- $optics
    _MkNonNegative,
    rmatching,
  )
where

import GHC.Stack (HasCallStack)
import Language.Haskell.TH (Code, Q)
import Language.Haskell.TH.Syntax (Lift (liftTyped))
import Numeric.Data.Internal.Utils (rmatching)
import Numeric.Data.NonNegative.Internal
  ( NonNegative
      ( MkNonNegative,
        UnsafeNonNegative
      ),
  )
import Numeric.Data.NonNegative.Internal qualified as Internal
import Optics.Core (ReversedPrism', ReversibleOptic (re), prism)

-- $setup
-- >>> :set -XTemplateHaskell
-- >>> :set -XPostfixOperators

-- | Template haskell for creating a 'NonNegative' at compile-time.
--
-- ==== __Examples__
-- >>> $$(mkNonNegativeTH 1)
-- UnsafeNonNegative 1
--
-- @since 0.1
mkNonNegativeTH :: (Integral a, Lift a, Show a) => a -> Code Q (NonNegative a)
mkNonNegativeTH :: forall a.
(Integral a, Lift a, Show a) =>
a -> Code Q (NonNegative a)
mkNonNegativeTH a
x = Code Q (NonNegative a)
-> (NonNegative a -> Code Q (NonNegative a))
-> Maybe (NonNegative a)
-> Code Q (NonNegative a)
forall b a. b -> (a -> b) -> Maybe a -> b
maybe ([Char] -> Code Q (NonNegative a)
forall a. HasCallStack => [Char] -> a
error [Char]
err) NonNegative a -> Code Q (NonNegative a)
forall t (m :: Type -> Type). (Lift t, Quote m) => t -> Code m t
forall (m :: Type -> Type).
Quote m =>
NonNegative a -> Code m (NonNegative a)
liftTyped (Maybe (NonNegative a) -> Code Q (NonNegative a))
-> Maybe (NonNegative a) -> Code Q (NonNegative a)
forall a b. (a -> b) -> a -> b
$ a -> Maybe (NonNegative a)
forall a. (Num a, Ord a) => a -> Maybe (NonNegative a)
mkNonNegative a
x
  where
    err :: [Char]
err = [Char] -> a -> [Char]
forall a. Show a => [Char] -> a -> [Char]
Internal.errMsg [Char]
"mkNonNegativeTH" a
x
{-# INLINEABLE mkNonNegativeTH #-}

-- | Smart constructor for 'NonNegative'. Returns 'Nothing' if the second
-- parameter is @< 0@.
--
-- ==== __Examples__
-- >>> mkNonNegative 0
-- Just (UnsafeNonNegative 0)
--
-- >>> mkNonNegative (-2)
-- Nothing
--
-- @since 0.1
mkNonNegative :: (Num a, Ord a) => a -> Maybe (NonNegative a)
mkNonNegative :: forall a. (Num a, Ord a) => a -> Maybe (NonNegative a)
mkNonNegative a
x
  | a
x a -> a -> Bool
forall a. Ord a => a -> a -> Bool
>= a
0 = NonNegative a -> Maybe (NonNegative a)
forall a. a -> Maybe a
Just (a -> NonNegative a
forall a. a -> NonNegative a
UnsafeNonNegative a
x)
  | Bool
otherwise = Maybe (NonNegative a)
forall a. Maybe a
Nothing
{-# INLINEABLE mkNonNegative #-}

-- | Postfix operator for 'Internal.unsafeNonNegative'.
--
-- __WARNING: Partial__
--
-- ==== __Examples__
--
-- >>> (7 *!)
-- UnsafeNonNegative 7
--
-- @since 0.1
(*!) :: (HasCallStack, Num a, Ord a, Show a) => a -> NonNegative a
*! :: forall a.
(HasCallStack, Num a, Ord a, Show a) =>
a -> NonNegative a
(*!) = a -> NonNegative a
forall a.
(HasCallStack, Num a, Ord a, Show a) =>
a -> NonNegative a
Internal.unsafeNonNegative
{-# INLINE (*!) #-}

infixl 7 *!

-- | This function is an alias for the unchecked constructor @UnsafeNonNegative@
-- i.e. it allows us to construct a 'NonNegative' __without__ checking the
-- invariant. This is intended only for when we absolutely know the invariant
-- holds and a branch (i.e. 'Internal.unsafeNonNegative') is undesirable for
-- performance reasons. Exercise extreme caution.
--
-- @since 0.1
reallyUnsafeNonNegative :: a -> NonNegative a
reallyUnsafeNonNegative :: forall a. a -> NonNegative a
reallyUnsafeNonNegative = a -> NonNegative a
forall a. a -> NonNegative a
UnsafeNonNegative
{-# INLINEABLE reallyUnsafeNonNegative #-}

-- | @since 0.1
unNonNegative :: NonNegative a -> a
unNonNegative :: forall a. NonNegative a -> a
unNonNegative (UnsafeNonNegative a
x) = a
x
{-# INLINE unNonNegative #-}

-- $optics
-- We provide a 'ReversedPrism'' '_MkNonNegative' that allows for total
-- elimination and partial construction, along with a 'Optics.Core.LabelOptic' 'Optics.Core.Getter'
-- for @#unNonNegative@.
--
-- ==== __Examples__
--
-- >>> :set -XOverloadedLabels
-- >>> import Optics.Core (view)
-- >>> let n = $$(mkNonNegativeTH 2)
-- >>> view #unNonNegative n
-- 2

-- | 'ReversedPrism'' that enables total elimination and partial construction.
--
-- ==== __Examples__
-- >>> import Optics.Core (view)
-- >>> nn = $$(mkNonNegativeTH 2)
-- >>> view _MkNonNegative nn
-- 2
--
-- >>> rmatching _MkNonNegative 3
-- Right (UnsafeNonNegative 3)
--
-- >>> rmatching _MkNonNegative (-2)
-- Left (-2)
--
-- @since 0.1
_MkNonNegative :: (Num a, Ord a) => ReversedPrism' (NonNegative a) a
_MkNonNegative :: forall a. (Num a, Ord a) => ReversedPrism' (NonNegative a) a
_MkNonNegative = Optic A_Prism NoIx a a (NonNegative a) (NonNegative a)
-> Optic
     (ReversedOptic A_Prism) NoIx (NonNegative a) (NonNegative a) a a
forall (is :: IxList) s t a b.
AcceptsEmptyIndices "re" is =>
Optic A_Prism is s t a b
-> Optic (ReversedOptic A_Prism) is b a t s
forall k (is :: IxList) s t a b.
(ReversibleOptic k, AcceptsEmptyIndices "re" is) =>
Optic k is s t a b -> Optic (ReversedOptic k) is b a t s
re ((NonNegative a -> a)
-> (a -> Either a (NonNegative a))
-> Optic A_Prism NoIx a a (NonNegative a) (NonNegative a)
forall b t s a. (b -> t) -> (s -> Either t a) -> Prism s t a b
prism NonNegative a -> a
forall a. NonNegative a -> a
unNonNegative a -> Either a (NonNegative a)
forall {a}. (Num a, Ord a) => a -> Either a (NonNegative a)
g)
  where
    g :: a -> Either a (NonNegative a)
g a
x = case a -> Maybe (NonNegative a)
forall a. (Num a, Ord a) => a -> Maybe (NonNegative a)
mkNonNegative a
x of
      Maybe (NonNegative a)
Nothing -> a -> Either a (NonNegative a)
forall a b. a -> Either a b
Left a
x
      Just NonNegative a
x' -> NonNegative a -> Either a (NonNegative a)
forall a b. b -> Either a b
Right NonNegative a
x'
{-# INLINEABLE _MkNonNegative #-}