numericpeano 0.1.0.0 → 0.2.0.0

raw patch · 2 files changed

+36/−31 lines, 2 filesdep ~basePVP ok

version bump matches the API change (PVP)

Dependency ranges changed: base

API changes (from Hackage documentation)

Files

• Numeric/Peano.hs +33/−28
• numericpeano.cabal +3/−3

@@ -1,27 +1,33 @@--- Value-level Peano arithmetic.
+-- |Value-level Peano arithmetic.
 module Numeric.Peano where
 
+import Prelude hiding (foldr)
+import Data.Foldable (Foldable(foldr))
 import Data.Ratio ((%))
 
 -- |Lazy Peano numbers. Allow calculation with infinite values.
-data Nat = Z | S Nat deriving (Show)
+data Nat = Z -- ^Zero
+           | S Nat -- ^Successor
+   deriving (Show)
 
 -- |Sign for whole numbers.
 data Sign = Pos | Neg deriving (Show, Eq, Ord, Enum, Read, Bounded)
 
 -- |Whole numbers (Z).
-data Whole = Whole Nat Sign
+data Whole = Whole Nat Sign -- ^Construct a whole number out of a magnitue and a sign.
 
 -- |The class of Peano-like constructions (i.e. Nat and Whole).
 class Enum a => Peano a where
    -- |Test for zero.
    isZero :: a -> Bool
-   -- |An unobservable infinity.
+   -- |An unobservable infinity. For all finite numbers @n@, @n < infinity@ must
+   --  hold, but there need not be a total function that tests whether a number
+   --  is infinite.
    infinity :: a
    -- |Converts the number to an Integer.
    fromPeano :: a -> Integer
    -- |Reduces the absolute value of the number by 1. If @isZero n@, then
-   --  @decr n = n@.
+   --  @decr n = n@ and vice versa.
    decr :: a -> a
 
 -- |Negation of 'isZero'.
@@ -53,18 +59,17 @@                      | otherwise = takeNat' (succ c) (pred i) (decr n)
 
 
--- |Bounded-instance for 'Nat'. The lower bound is zero, the upper bound
---  is infinity.
+-- |The lower bound is zero, the upper bound is infinity.
 instance Bounded Nat where
    minBound = Z
    maxBound = infinity
 
--- |Bounded-instance for 'Nat'. The bounds are negative and positive infinity.
+-- |The bounds are negative and positive infinity.
 instance Bounded Whole where
    minBound = Whole infinity Neg
    maxBound = infinity
 
--- |Enum-instance for 'Nat'. The 'pred' function is bounded at Zero.
+-- |The 'pred' function is bounded at Zero.
 instance Enum Nat where
    toEnum = fromInteger . fromIntegral
    fromEnum = fromInteger . fromPeano
@@ -72,7 +77,7 @@    pred Z = Z
    pred (S n) = n
 
--- |Enum-instance for 'Whole'. 'succ' and 'pred' work according to the total
+-- |'succ' and 'pred' work according to the total
 --  order on the whole numbers, i.e. @succ n = n+1@ and @pred n = n-1@.
 instance Enum Whole where
    toEnum i | i < 0     = Whole (toEnum i) Neg
@@ -85,14 +90,14 @@    pred (Whole n Neg) = Whole (S n) Neg
    pred (Whole Z _) = Whole (S Z) Neg
 
--- |Num-instance for 'Nat'. Addition, multiplication, and subtraction are
+-- |Addition, multiplication, and subtraction are
 --  lazy in both arguments, meaning that, in the case of infinite values,
 --  they can produce an infinite stream of S-constructors. As long as
 --  the callers of these functions only consume a finite amount of these,
 --  the program will not hang.
 --
 --  @fromInteger@ is not injective in case of 'Nat', since negative integers
---  are all converted to Z.
+--  are all converted to zero ('Z').
 instance Num Nat where
    (+) Z n = n
    (+) n Z = n
@@ -136,27 +141,27 @@                  | otherwise = Whole (fromInteger i) Pos
 
 
--- |Eq-instance for 'Nat'. '==' and '/=' work as long as at least one operand
---  is finite.
+-- |'==' and '/=' work as long as at least one operand is finite.
 instance Eq Nat where
    (==) Z Z = True
    (==) Z (S _) = False
    (==) (S _) Z = False
    (==) (S n) (S m) = n == m
 
--- |Eq-instance for 'Whole'. Positive and negative zero are considered equal.
+-- |Positive and negative zero are considered equal.
 instance Eq Whole where
    (==) (Whole Z _) (Whole Z _) = True
    (==) (Whole n s) (Whole m t) = s == t && n == m
 
--- |Ord-instance for 'Nat'. All methods work as long as at least one operand
---  is finite.
+-- |All methods work as long as at least one operand is finite.
 instance Ord Nat where
    compare Z Z = EQ
    compare Z (S _) = LT
    compare (S _) Z = GT
    compare (S n) (S m) = compare n m
 
+-- |The ordering is the standard total order on Z. Positive and negative zero
+--  are equal.
 instance Ord Whole where
    compare (Whole Z _) (Whole Z _) = EQ
    compare (Whole _ Neg) (Whole _ Pos) = LT
@@ -164,21 +169,21 @@    compare (Whole n Pos) (Whole m Pos) = compare n m
    compare (Whole n Neg) (Whole m Neg) = compare m n
 
--- |Returns the length of a list as Nat. Can handle infinite lists, provided
---  that a finite lower bound is checked.
-natLength :: [a] -> Nat
-natLength [] = Z
-natLength (_:xs) = S $ natLength xs
+-- |Returns the length of a foldable container as 'Nat'. The number is generated
+--  lazily and thus, infinitely large containers are supported.
+natLength :: Foldable f => f a -> Nat
+natLength = foldr (const S) Z
 
--- |Real-instance for 'Nat'. Since 'toRational' returns a @Ratio Integer@,
---  it WILL NOT terminate on infinities.
+-- |Since 'toRational' returns a @Ratio Integer@, it WILL NOT terminate on infinities.
 instance Real Nat where
    toRational = flip (%) 1 . fromPeano
 
--- |Integral-instance for 'Nat'. Since negative numbers are not allowed,
---  @quot = div@ and @rem = mod@. The methods @quot@, @rem@, @div@, @mod@,
---  @quotRem@ and @divMod@ will return as long as their first argument is
---  finite. Infinities are handled as follows:
+-- |Since negative numbers are not allowed,
+--  @'quot' = 'div'@ and @'rem' = 'mod'@. The methods 'quot', 'rem', 'div', 'mod',
+--  'quotRem' and 'divMod' will terminate as long as their first argument is
+--  finite. Infinities in their second arguments are permitted and are handled
+--  as follows:
+--
 --  @
 --  n `quot` infinity   =   n `div` infinity   =   0
 --  n `rem`  infinity   =   n `mod` infinity   =   n@

@@ -2,7 +2,7 @@ -- documentation, see http://haskell.org/cabal/users-guide/
 
 name:                numericpeano
-version:             0.1.0.0
+version:             0.2.0.0
 synopsis:            Peano numbers with attendant bells and whistles.
 description:         Value-level lazy Peano numbers for all your proof-theoretic
                      and infinity-related needs. The features are:
@@ -13,7 +13,7 @@                        Peano arithmetic can be used in generic functions without
                        extra hassle.
 
-                     The implementation is naive, meaning that a number of
+                     The implementation is naive: a number of
                      magnitude n may consume O(n) bytes of memory.
 homepage:            https://github.com/ombocomp/numericpeano/
 license:             Apache-2.0
@@ -30,6 +30,6 @@   exposed-modules:     Numeric.Peano
   -- other-modules:
   -- other-extensions:
-  build-depends:       base >=4.7 && <4.8
+  build-depends:       base >=4.7 && <=5.0
   -- hs-source-dirs:
   default-language:    Haskell2010