X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ffec48800022b6872951eca188d2ceedef8dd5c8..6ec3a4cf4aaa7cd375e1aa18f85861986259b8e5:/mp.h

diff --git a/mp.h b/mp.h
index 7f96746..13f97d1 100644
--- a/mp.h
+++ b/mp.h
@@ -7,7 +7,7 @@
  * (c) 1999 Straylight/Edgeware
  */
 
-/*----- Licensing notice --------------------------------------------------* 
+/*----- Licensing notice --------------------------------------------------*
  *
  * This file is part of Catacomb.
  *
@@ -15,12 +15,12 @@
  * it under the terms of the GNU Library General Public License as
  * published by the Free Software Foundation; either version 2 of the
  * License, or (at your option) any later version.
- * 
+ *
  * Catacomb is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Library General Public License for more details.
- * 
+ *
  * You should have received a copy of the GNU Library General Public
  * License along with Catacomb; if not, write to the Free
  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
@@ -90,14 +90,14 @@ typedef struct mp_expfactor {
 extern mp mp_const[];
 
 #define MP_ZERO	 (&mp_const[0])
-#define MP_ONE   (&mp_const[1])
-#define MP_TWO   (&mp_const[2])
+#define MP_ONE	 (&mp_const[1])
+#define MP_TWO	 (&mp_const[2])
 #define MP_THREE (&mp_const[3])
-#define MP_FOUR  (&mp_const[4])
-#define MP_FIVE  (&mp_const[5])
-#define MP_TEN   (&mp_const[6])
+#define MP_FOUR	 (&mp_const[4])
+#define MP_FIVE	 (&mp_const[5])
+#define MP_TEN	 (&mp_const[6])
 #define MP_256	 (&mp_const[7])
-#define MP_MONE  (&mp_const[8])
+#define MP_MONE	 (&mp_const[8])
 
 #define MP_NEW ((mp *)0)
 #define MP_NEWSEC (&mp_const[9])
@@ -218,7 +218,7 @@ extern void mp_drop(mp */*m*/);
   if (_mm->ref == 0 && !(_mm->f & MP_CONST))				\
     mp_destroy(_mm);							\
 } while (0)
-		   
+
 /* --- @mp_split@ --- *
  *
  * Arguments:	@mp *m@ = pointer to a multiprecision integer
@@ -615,7 +615,7 @@ extern void mp_storeb2c(const mp */*m*/, void */*pv*/, size_t /*sz*/);
  *		@mp *a@ = source
  *
  * Returns:	The bitwise complement of the source.
- */ 
+ */
 
 extern mp *mp_not(mp */*d*/, mp */*a*/);
 
@@ -643,11 +643,11 @@ MPX_DOBIN(MP_BITDECL)
  * Synonyms for the commonly-used functions.
  */
 
-#define mp_and  mp_bit0001
-#define mp_or   mp_bit0111
+#define mp_and	mp_bit0001
+#define mp_or	mp_bit0111
 #define mp_nand mp_bit1110
-#define mp_nor  mp_bit1000
-#define mp_xor  mp_bit0110
+#define mp_nor	mp_bit1000
+#define mp_xor	mp_bit0110
 
 /* --- @mp_testbit@ --- *
  *
@@ -724,7 +724,7 @@ MPX_DOBIN(MP_BIT2CDECL)
  */
 
 #define mp_and2c  mp_bit00012c
-#define mp_or2c   mp_bit01112c
+#define mp_or2c	  mp_bit01112c
 #define mp_nand2c mp_bit11102c
 #define mp_nor2c  mp_bit10002c
 #define mp_xor2c  mp_bit01102c
@@ -941,15 +941,35 @@ extern mp *mp_modinv(mp */*d*/, mp */*x*/, mp */*p*/);
 
 /* --- @mp_jacobi@ --- *
  *
- * Arguments:	@mp *a@ = an integer less than @n@
- *		@mp *n@ = an odd integer
+ * Arguments:	@mp *a@ = an integer
+ *		@mp *n@ = another integer
  *
  * Returns:	@-1@, @0@ or @1@ -- the Jacobi symbol %$J(a, n)$%.
  *
- * Use:		Computes the Jacobi symbol.  If @n@ is prime, this is the
- *		Legendre symbol and is equal to 1 if and only if @a@ is a
- *		quadratic residue mod @n@.  The result is zero if and only if
- *		@a@ and @n@ have a common factor greater than one.
+ * Use:		Computes the Kronecker symbol %$\jacobi{a}{n}$%.  If @n@ is
+ *		prime, this is the Legendre symbol and is equal to 1 if and
+ *		only if @a@ is a quadratic residue mod @n@.  The result is
+ *		zero if and only if @a@ and @n@ have a common factor greater
+ *		than one.
+ *
+ *		If @n@ is composite, then this computes the Kronecker symbol
+ *
+ *		  %$\jacobi{a}{n}=\jacobi{a}{u}\prod_i\jacobi{a}{p_i}^{e_i}$%
+ *
+ *		where %$n = u p_0^{e_0} \ldots p_{n-1}^{e_{n-1}}$% is the
+ *		prime factorization of %$n$%.  The missing bits are:
+ *
+ *		  * %$\jacobi{a}{1} = 1$%;
+ *		  * %$\jacobi{a}{-1} = 1$% if @a@ is negative, or 1 if
+ *		    positive;
+ *		  * %$\jacobi{a}{0} = 0$%;
+ *	          * %$\jacobi{a}{2}$ is 0 if @a@ is even, 1 if @a@ is
+ *		    congruent to 1 or 7 (mod 8), or %$-1$% otherwise.
+ *
+ *		If %$n$% is positive and odd, then this is the Jacobi
+ *		symbol.  (The Kronecker symbol is a consistant domain
+ *		extension; the Jacobi symbol was implemented first, and the
+ *		name stuck.)
  */
 
 extern int mp_jacobi(mp */*a*/, mp */*n*/);