/* -*-c-*-
*
- * $Id: mp.h,v 1.13 2002/10/06 22:52:50 mdw Exp $
+ * $Id$
*
* Simple multiprecision arithmetic
*
* MA 02111-1307, USA.
*/
-/*----- Revision history --------------------------------------------------*
- *
- * $Log: mp.h,v $
- * Revision 1.13 2002/10/06 22:52:50 mdw
- * Pile of changes for supporting two's complement properly.
- *
- * Revision 1.12 2001/06/16 12:57:43 mdw
- * Move the @mpmont_factor@ structure and rename it now that it's used for
- * Barrett simultaneous exponentiation too.
- *
- * Revision 1.11 2001/04/03 19:36:05 mdw
- * Add some simple bitwise operations so that Perl can use them.
- *
- * Revision 1.10 2000/10/08 12:03:16 mdw
- * Provide @mp_eq@ and @MP_EQ@ for rapidly testing equality of two
- * integers.
- *
- * Revision 1.9 2000/07/29 17:03:31 mdw
- * Add support for left-to-right bitscanning, for use in modular
- * exponentiation.
- *
- * Revision 1.8 2000/06/22 19:02:01 mdw
- * Add new functions.
- *
- * Revision 1.7 2000/06/17 11:45:09 mdw
- * Major memory management overhaul. Added arena support. Use the secure
- * arena for secret integers. Replace and improve the MP management macros
- * (e.g., replace MP_MODIFY by MP_DEST).
- *
- * Revision 1.6 1999/12/10 23:19:46 mdw
- * Minor bugfixes. New interface for suggested destinations.
- *
- * Revision 1.5 1999/11/22 20:50:37 mdw
- * Add support for computing Jacobi symbols.
- *
- * Revision 1.4 1999/11/21 22:13:02 mdw
- * Add mp version of MPX_BITS.
- *
- * Revision 1.3 1999/11/19 13:19:14 mdw
- * Fix const annotation.
- *
- * Revision 1.2 1999/11/17 18:02:16 mdw
- * New multiprecision integer arithmetic suite.
- *
- */
-
#ifndef CATACOMB_MP_H
#define CATACOMB_MP_H
#define MP_SHRINK(m) do { \
mp *_mm = (m); \
MPX_SHRINK(_mm->v, _mm->vl); \
- if (!MP_LEN(_mm)) \
+ if (MP_ZEROP(_mm)) \
_mm->f &= ~MP_NEG; \
} while (0)
extern void mp_storeb2c(const mp */*m*/, void */*pv*/, size_t /*sz*/);
-/*----- Simple arithmetic -------------------------------------------------*/
-
-/* --- @mp_lsl@, @mp_lsr@ --- *
- *
- * Arguments: @mp *d@ = destination
- * @mp *a@ = source
- * @size_t n@ = number of bits to move
- *
- * Returns: Result, @a@ shifted left or right by @n@.
- */
-
-extern mp *mp_lsl(mp */*d*/, mp */*a*/, size_t /*n*/);
-extern mp *mp_lsr(mp */*d*/, mp */*a*/, size_t /*n*/);
+/*----- Bit operations ----------------------------------------------------*/
-/* --- @mp_lsl2c@, @mp_lsr2c@ --- *
+/* --- @mp_not@ --- *
*
* Arguments: @mp *d@ = destination
* @mp *a@ = source
- * @size_t n@ = number of bits to move
- *
- * Returns: Result, @a@ shifted left or right by @n@. Handles the
- * pretence of sign-extension for negative numbers.
- */
-
-extern mp *mp_lsl2c(mp */*d*/, mp */*a*/, size_t /*n*/);
-extern mp *mp_lsr2c(mp */*d*/, mp */*a*/, size_t /*n*/);
-
-/* --- @mp_testbit@ --- *
- *
- * Arguments: @mp *x@ = a large integer
- * @size_t n@ = which bit to test
- *
- * Returns: Nonzero if the bit is set, zero if not.
- */
-
-extern int mp_testbit(mp */*x*/, size_t /*n*/);
-
-/* --- @mp_testbit2c@ --- *
*
- * Arguments: @mp *x@ = a large integer
- * @size_t n@ = which bit to test
- *
- * Returns: Nonzero if the bit is set, zero if not. Fakes up two's
- * complement representation.
- */
-
-extern int mp_testbit2c(mp */*x*/, size_t /*n*/);
-
-/* --- @mp_eq@ --- *
- *
- * Arguments: @const mp *a, *b@ = two numbers
- *
- * Returns: Nonzero if the numbers are equal.
- */
-
-extern int mp_eq(const mp */*a*/, const mp */*b*/);
-
-#define MP_EQ(a, b) \
- ((((a)->f ^ (b)->f) & MP_NEG) == 0 && \
- mpx_ueq((a)->v, (a)->vl, (b)->v, (b)->vl))
-
-/* --- @mp_cmp@ --- *
- *
- * Arguments: @const mp *a, *b@ = two numbers
- *
- * Returns: Less than, equal to or greater than zero, according to
- * whether @a@ is less than, equal to or greater than @b@.
- */
-
-extern int mp_cmp(const mp */*a*/, const mp */*b*/);
+ * Returns: The bitwise complement of the source.
+ */
-#define MP_CMP(a, op, b) (mp_cmp((a), (b)) op 0)
+extern mp *mp_not(mp */*d*/, mp */*a*/);
/* --- @mp_bitop@ --- *
*
#define mp_nor mp_bit1000
#define mp_xor mp_bit0110
-/* --- @mp_not@ --- *
+/* --- @mp_testbit@ --- *
+ *
+ * Arguments: @mp *x@ = a large integer
+ * @unsigned long n@ = which bit to test
+ *
+ * Returns: Nonzero if the bit is set, zero if not.
+ */
+
+extern int mp_testbit(mp */*x*/, unsigned long /*n*/);
+
+/* --- @mp_setbit@, @mp_clearbit@ --- *
+ *
+ * Arguments: @mp *d@ = a destination
+ * @mp *x@ = a large integer
+ * @unsigned long n@ = which bit to modify
+ *
+ * Returns: The argument @x@, with the appropriate bit set or cleared.
+ */
+
+extern mp *mp_setbit(mp */*d*/, mp */*x*/, unsigned long /*n*/);
+extern mp *mp_clearbit(mp */*d*/, mp */*x*/, unsigned long /*n*/);
+
+/* --- @mp_lsl@, @mp_lslc@, @mp_lsr@ --- *
*
* Arguments: @mp *d@ = destination
* @mp *a@ = source
+ * @size_t n@ = number of bits to move
*
- * Returns: The bitwise complement of the source.
- */
+ * Returns: Result, @a@ shifted left or right by @n@.
+ *
+ * Use: Bitwise shift operators. @mp_lslc@ fills the bits introduced
+ * on the right with ones instead of zeroes: it's used
+ * internally by @mp_lsl2c@, though it may be useful on its
+ * own.
+ */
-extern mp *mp_not(mp */*d*/, mp */*a*/);
+extern mp *mp_lsl(mp */*d*/, mp */*a*/, size_t /*n*/);
+extern mp *mp_lslc(mp */*d*/, mp */*a*/, size_t /*n*/);
+extern mp *mp_lsr(mp */*d*/, mp */*a*/, size_t /*n*/);
+
+/* --- @mp_not2c@ --- *
+ *
+ * Arguments: @mp *d@ = destination
+ * @mp *a@ = source
+ *
+ * Returns: The sign-extended complement of the argument.
+ */
+
+extern mp *mp_not2c(mp */*d*/, mp */*a*/);
/* --- @mp_bitop2c@ --- *
*
#define mp_nor2c mp_bit10002c
#define mp_xor2c mp_bit01102c
-/* --- @mp_not2c@ --- *
+/* --- @mp_lsl2c@, @mp_lsr2c@ --- *
*
* Arguments: @mp *d@ = destination
* @mp *a@ = source
+ * @size_t n@ = number of bits to move
*
- * Returns: The sign-extended complement of the argument.
+ * Returns: Result, @a@ shifted left or right by @n@. Handles the
+ * pretence of sign-extension for negative numbers.
*/
-extern mp *mp_not2c(mp */*d*/, mp */*a*/);
+extern mp *mp_lsl2c(mp */*d*/, mp */*a*/, size_t /*n*/);
+extern mp *mp_lsr2c(mp */*d*/, mp */*a*/, size_t /*n*/);
+
+/* --- @mp_testbit2c@ --- *
+ *
+ * Arguments: @mp *x@ = a large integer
+ * @unsigned long n@ = which bit to test
+ *
+ * Returns: Nonzero if the bit is set, zero if not. Fakes up two's
+ * complement representation.
+ */
+
+extern int mp_testbit2c(mp */*x*/, unsigned long /*n*/);
+
+/* --- @mp_setbit2c@, @mp_clearbit2c@ --- *
+ *
+ * Arguments: @mp *d@ = a destination
+ * @mp *x@ = a large integer
+ * @unsigned long n@ = which bit to modify
+ *
+ * Returns: The argument @x@, with the appropriate bit set or cleared.
+ * Fakes up two's complement representation.
+ */
+
+extern mp *mp_setbit2c(mp */*d*/, mp */*x*/, unsigned long /*n*/);
+extern mp *mp_clearbit2c(mp */*d*/, mp */*x*/, unsigned long /*n*/);
+
+/*----- Comparisons -------------------------------------------------------*/
+
+/* --- @mp_eq@ --- *
+ *
+ * Arguments: @const mp *a, *b@ = two numbers
+ *
+ * Returns: Nonzero if the numbers are equal.
+ */
+
+extern int mp_eq(const mp */*a*/, const mp */*b*/);
+
+#define MP_EQ(a, b) \
+ ((((a)->f ^ (b)->f) & MP_NEG) == 0 && \
+ mpx_ueq((a)->v, (a)->vl, (b)->v, (b)->vl))
+
+/* --- @mp_cmp@ --- *
+ *
+ * Arguments: @const mp *a, *b@ = two numbers
+ *
+ * Returns: Less than, equal to or greater than zero, according to
+ * whether @a@ is less than, equal to or greater than @b@.
+ */
+
+extern int mp_cmp(const mp */*a*/, const mp */*b*/);
+
+#define MP_CMP(a, op, b) (mp_cmp((a), (b)) op 0)
+
+/* --- Other handy macros --- */
+
+#define MP_NEGP(x) ((x)->f & MP_NEG)
+#define MP_ZEROP(x) (!MP_LEN(x))
+#define MP_POSP(x) (!MP_NEGP(x) && !MP_ZEROP(x))
+#define MP_ODDP(x) (!MP_ZEROP(x) && ((x)->v[0] & 1u))
+#define MP_EVENP(x) (!MP_ODDP(x))
+
+/*----- Arithmetic operations ---------------------------------------------*/
+
+/* --- @mp_neg@ --- *
+ *
+ * Arguments: @mp *d@ = destination
+ * @mp *a@ = argument
+ *
+ * Returns: The negation of the argument.
+ *
+ * Use: Negates its argument.
+ */
+
+extern mp *mp_neg(mp */*d*/, mp */*a*/);
/* --- @mp_add@ --- *
*
extern void mp_div(mp **/*qq*/, mp **/*rr*/, mp */*a*/, mp */*b*/);
+/* --- @mp_exp@ --- *
+ *
+ * Arguments: @mp *d@ = fake destination
+ * @mp *a@ = base
+ * @mp *e@ = exponent
+ *
+ * Returns: Result, %$a^e$%.
+ */
+
+extern mp *mp_exp(mp */*d*/, mp */*a*/, mp */*e*/);
+
/* --- @mp_odd@ --- *
*
* Arguments: @mp *d@ = pointer to destination integer
extern void mp_gcd(mp **/*gcd*/, mp **/*xx*/, mp **/*yy*/,
mp */*a*/, mp */*b*/);
+/* -- @mp_modinv@ --- *
+ *
+ * Arguments: @mp *d@ = destination
+ * @mp *x@ = argument
+ * @mp *p@ = modulus
+ *
+ * Returns: The inverse %$x^{-1} \bmod p$%.
+ *
+ * Use: Computes a modular inverse. An assertion fails if %$p$%
+ * has no inverse.
+ */
+
+extern mp *mp_modinv(mp */*d*/, mp */*x*/, mp */*p*/);
+
/* --- @mp_jacobi@ --- *
*
* Arguments: @mp *a@ = an integer less than @n@
* work if %$p$% is composite: you must factor the modulus, take
* a square root mod each factor, and recombine the results
* using the Chinese Remainder Theorem.
+ *
+ * We guarantee that the square root returned is the smallest
+ * one (i.e., the `positive' square root).
*/
extern mp *mp_modsqrt(mp */*d*/, mp */*a*/, mp */*p*/);
projects / u / mdw / catacomb / blobdiff