From 5bea21e81ed516440e34e480f2c33ca41aa8c597 Mon Sep 17 00:00:00 2001
From: Bryan Newbold <bnewbold@robocracy.org>
Date: Mon, 20 Feb 2017 00:05:36 -0800
Subject: Import Upstream version 3a4

---
 modular.txi | 56 ++++++++++++++++++++------------------------------------
 1 file changed, 20 insertions(+), 36 deletions(-)

(limited to 'modular.txi')

diff --git a/modular.txi b/modular.txi
index bf2cd52..666f52a 100644
--- a/modular.txi
+++ b/modular.txi
@@ -2,31 +2,6 @@
 @ftindex modular
 
 
-@defun mod x1 x2
-@defunx rem x1 x2
-
-These procedures implement the Common-Lisp functions of the same names.
-The real number @var{x2} must be non-zero.
-@code{mod} returns @code{(- @var{x1} (* @var{x2} (floor (/ @var{x1} @var{x2}))))}.
-@code{rem} returns @code{(- @var{x1} (* @var{x2} (truncate (/ @var{x1} @var{x2}))))}.
-
-If @var{x1} and @var{x2} are integers, then @code{mod} behaves like
-@code{modulo} and @code{rem} behaves like @code{remainder}.
-
-@format
-@t{(mod -90 360)                          @result{} 270
-(rem -90 180)                          @result{} -90
-
-(mod 540 360)                          @result{} 180
-(rem 540 360)                          @result{} 180
-
-(mod (* 5/2 pi) (* 2 pi))              @result{} 1.5707963267948965
-(rem (* -5/2 pi) (* 2 pi))             @result{} -1.5707963267948965
-}
-@end format
-@end defun
-
-
 @defun extended-euclid n1 n2
 
 Returns a list of 3 integers @code{(d x y)} such that d = gcd(@var{n1},
@@ -34,13 +9,18 @@ Returns a list of 3 integers @code{(d x y)} such that d = gcd(@var{n1},
 @end defun
 
 
-@defun symmetric:modulus n
+@defun symmetric:modulus m
 
-Returns @code{(quotient (+ -1 n) -2)} for positive odd integer @var{n}.
+For odd positive integer @var{m}, returns an object suitable for passing
+as the first argument to @code{modular:} procedures, directing them
+to return a symmetric modular number, ie. an @var{n} such that
+@example
+(<= (quotient @var{m} -2) @var{n} (quotient @var{m} 2)
+@end example
 @end defun
 
 
-@defun modulus->integer modulus
+@defun modular:characteristic modulus
 
 Returns the non-negative integer characteristic of the ring formed when
 @var{modulus} is used with @code{modular:} procedures.
@@ -49,7 +29,7 @@ Returns the non-negative integer characteristic of the ring formed when
 
 @defun modular:normalize modulus n
 
-Returns the integer @code{(modulo @var{n} (modulus->integer
+Returns the integer @code{(modulo @var{n} (modular:characteristic
 @var{modulus}))} in the representation specified by @var{modulus}.
 @end defun
 
@@ -61,18 +41,22 @@ arguments are constrained by the following table:
 For all of these functions, if the first argument (@var{modulus}) is:
 @table @code
 @item positive?
-Work as before.  The result is between 0 and @var{modulus}.
+Integers mod @var{modulus}.  The result is between 0 and
+@var{modulus}.
 
 @item zero?
 The arguments are treated as integers.  An integer is returned.
+@end table
 
-@item negative?
-The arguments and result are treated as members of the integers modulo
-@code{(+ 1 (* -2 @var{modulus}))}, but with @dfn{symmetric}
+@noindent
+Otherwise, if @var{modulus} is a value returned by
+@code{(symmetric:modulus @var{radix})}, then the arguments and
+result are treated as members of the integers modulo @var{radix},
+but with @dfn{symmetric} representation; i.e.
 @cindex symmetric
-representation; i.e. @code{(<= (- @var{modulus}) @var{n}
-@var{modulus})}.
-@end table
+@example
+(<= (quotient @var{radix} 2) @var{n} (quotient (- -1 @var{radix}) 2)
+@end example
 
 @noindent
 If all the arguments are fixnums the computation will use only fixnums.
-- 
cgit v1.2.3