packages feed

positive-integer-0.1.0.0: lib/Numeric/PositiveInteger.hs

{-# LANGUAGE CPP #-}

-- | This module provides a type for the positive integers, together
--   with conversion functions and other operations.
--
--   When an operation is partial (for example, subtraction), the result
--   has a 'Maybe' type, letting the user handle such case, without the
--   need for handling exceptions during evaluation.
--   As a result, 'PositiveInteger' is not an instance of the 'Num' class
--   or any of its subclasses. Functions are provided that offer similar
--   functionality.
--
--   It is recommended that you import this module qualified, as some of
--   the function names clash with those from the Prelude.
module Numeric.PositiveInteger
  ( PositiveInteger
  , one
    -- * Conversions
  , fromNatural
  , fromIntegral
  , toNatural
  , toNum
    -- * Operations
  , next
  , add
  , sub
  , mul
  , div
    -- * Positive lengths
  , length
    -- * Non-empty lists
  , take
  , replicate
  , replicateM
    ) where

import Prelude hiding (fromIntegral, div, length, take, replicate)
import Prelude qualified
import Numeric.Natural (Natural)
import Text.Read (readPrec)
import Control.Monad qualified as Monad

#if MIN_VERSION_base(4,18,0)
import Data.Foldable1 (Foldable1)
#else
import Control.Applicative (liftA2)
#endif

import Data.List.NonEmpty (NonEmpty)
import Data.List.NonEmpty qualified as NonEmpty

-- | Unbounded positive integers.
--
--   No 'Num' instance is provided, as no negative integers are available.
newtype PositiveInteger = PositiveInteger Natural deriving (Eq, Ord)

-- | The number 1.
one :: PositiveInteger
{-# INLINE one #-}
one = PositiveInteger 1

instance Show PositiveInteger where
  show (PositiveInteger n) = show n

instance Read PositiveInteger where
  readPrec = do
    n <- readPrec
    Monad.guard (n /= 0)
    pure $ PositiveInteger n

-- | Convert from a 'Natural' number, returning 'Nothing' if the input
--   is 0.
fromNatural :: Natural -> Maybe PositiveInteger
{-# INLINE fromNatural #-}
fromNatural n = if n == 0 then Nothing else Just (PositiveInteger n)

-- | Convert from a type that's instance of 'Integral'.
--   Similar to Prelude's 'Prelude.fromIntegral', but the result is
--   a 'Maybe', since the input might not be positive.
fromIntegral :: Integral a => a -> Maybe PositiveInteger
{-# INLINE fromIntegral #-}
fromIntegral n =
  if n > 0
     then Just (PositiveInteger $ Prelude.fromIntegral n)
     else Nothing

-- | Cast a positive integer to a natural number.
toNatural :: PositiveInteger -> Natural
{-# INLINE toNatural #-}
toNatural (PositiveInteger n) = n

-- | Convert a positive integer to any type instance of 'Num'.
--   This is equivalent to Prelude's 'Prelude.fromIntegral' when the input
--   type is 'PositiveInteger'.
toNum :: Num a => PositiveInteger -> a
{-# INLINE toNum #-}
toNum (PositiveInteger n) = Prelude.fromIntegral n

-- | Return the next positive integer.
next :: PositiveInteger -> PositiveInteger
{-# INLINE next #-}
next (PositiveInteger n) = PositiveInteger (n+1)

-- | Add two positive integers.
add :: PositiveInteger -> PositiveInteger -> PositiveInteger
{-# INLINE add #-}
add (PositiveInteger n) (PositiveInteger m) = PositiveInteger (n+m)

-- | Multiply two positive integers.
mul :: PositiveInteger -> PositiveInteger -> PositiveInteger
{-# INLINE mul #-}
mul (PositiveInteger n) (PositiveInteger m) = PositiveInteger (n*m)

-- | Subtract two positive integers. If the result wouldn't be positive,
--   'Nothing' is returned.
sub :: PositiveInteger -> PositiveInteger -> Maybe PositiveInteger
{-# INLINE sub #-}
sub (PositiveInteger n) (PositiveInteger m) =
  if n > m then Just $ PositiveInteger (n - m) else Nothing

-- | Divide a positive integer by another. If the divisor is larger than
--   the dividend, 'Nothing' is returned.
div :: PositiveInteger -> PositiveInteger -> Maybe PositiveInteger
{-# INLINE div #-}
div (PositiveInteger n) (PositiveInteger m) =
  if m <= n then Just (PositiveInteger (Prelude.div n m)) else Nothing

{-

Starting on base-4.18.0.0, the type class Foldable1 becomes available.
This allows us to generalize the type of length.

-}

#if MIN_VERSION_base(4,18,0)
-- | Length of a non-empty data structure.
length :: Foldable1 t => t a -> PositiveInteger
#else
-- | Lenght of a non-empty list.
length :: NonEmpty a -> PositiveInteger
#endif
{-# INLINE length #-}
length = PositiveInteger . Prelude.fromIntegral . Prelude.length

-- | Take a positive number of elements from a non-empty list.
take :: PositiveInteger -> NonEmpty a -> NonEmpty a
take (PositiveInteger n) (x NonEmpty.:| xs) =
  x NonEmpty.:| Prelude.take (Prelude.fromIntegral $ n - 1) xs

-- | Produce a non-empty list with the same value repeated a given number of
--   times.
replicate :: PositiveInteger -> a -> NonEmpty a
{-# INLINE replicate #-}
replicate (PositiveInteger n) x =
  x NonEmpty.:| Prelude.replicate (Prelude.fromIntegral $ n - 1) x

-- | Repeat an action a given number of times and collect the
--   results in a non-empty list.
replicateM :: Applicative f => PositiveInteger -> f a -> f (NonEmpty a)
{-# INLINE replicateM #-}
replicateM (PositiveInteger n) x =
  liftA2 (NonEmpty.:|) x $ Monad.replicateM (Prelude.fromIntegral $ n - 1) x