Next Previous Table of Contents

# The LMath Class

    #include <linteger/lmath.hxx>

## Overview

This LMath class provides methods to perform basic number theoretical algorithms on `LInteger`s. Probabilistic compositeness testing is also included here, along with probable prime number generation.

## Public Methods

### LongDivide

    static void LMath::LongDivide(const LInteger& dividend,
                                  const LInteger& divisor,
                                  LInteger& quotient,
                                  LInteger& remainder);

This method makes quotient and remainder represent integers such that dividend=quotient*divisor+remainder, with 0<=remainder<|divisor|.

### Sqrt

    static LInteger LMath::Sqrt(const LInteger& n);

This method returns an `LInteger` representing the integer which is equal to the floor of the square root of the integer that n represents.

n must represent a positive integer for this method to work.

### ModExp

    static LInteger LMath::ModExp(const LInteger& g, const LInteger& x,
                                  const LInteger& n);

This method returns an `LInteger` representing the integer between 0 and n-1 which is congruent, mod n, to g raised to the the xth power.

n must represent an integer greater than 1 for this method to work.

### CRTModExp

    static LInteger LMath::CRTModExp(const LInteger& g, const LInteger& x,
                                     const LInteger& p, const LInteger& q);

This method returns an `LInteger` representing the integer between 0 and p*q-1 which is congruent, mod pq, to g raised to the the xth power.

p and q must represent distinct, positive, odd, relatively prime integers for this method to work. (In the interest of speed, however, the library does not check these requirements.)

### GCD

    static LInteger LMath::GCD(const LInteger& x, const LInteger& y);

This method returns an `LInteger` representing the greatest common divisor of the integers represented by x and y.

x and y must both represent non-negative integers for this method to work.

### ExtendedEuclid

    static LInteger LMath::ExtendedEuclid(const LInteger& x, const LInteger& y,
                                          LInteger& u, LInteger& v);

This methods makes u and v represent integers such that x*u+y*v is equal to the greatest common divisor of the integers represented by x and y. An `LInteger` representing this greatest common divisor is returned.

x and y must both represent non-negative integers for this method to work.

### InvertUnit

    static LInteger LMath::InvertUnit(const LInteger& x, const LInteger& n);

This method returns an `LInteger` representing the integer between 0 and n-1 which, when multiplied mod n by the integer that x represents, is equal to 1.

n must be positive for this method to work.

Warning: Be sure that x does, indeed, represent a member of an invertable residue class before this method is called or the program will terminate on an assertion!

### ChineseRemainderTheorem

    static LInteger LMath::ChineseRemainderTheorem(const LInteger& x_p,
                                                   const LInteger& p,
                                                   const LInteger& x_q,
                                                   const LInteger& q);

This method returns an `LInteger` representing an integer, between 0 and p*q-1, which is congurent, mod p, to x_p, and congurent, mod q, to x_q.

p and q and must represent relatively prime, positive integers for this method to work.

### Composite

    static int LMath::Composite(const LInteger& x, PRNG& prng);

This method applies a probablistic primality test, using prng to generate random bits, to determine whether or not x is composite. If this method returns 1, then x definitely represents a composite integer. Otherwise, 0 is returned meaning that x has passed one round of the Rabin-Miller compositeness test, and thus, probably represents a prime number. Schneier (11.5) contains a list of references to research on the probability that a composite number will pass one round of the Rabin-Miller compositeness test.

x must be positive for this method to work.

### RandomProbablePrime

    LInteger LMath::RandomProbablePrime(const int numBits, PRNG& prng,
                                        int (*PreProcess)(LInteger&)=NULL,
                                        const int fewerBits=0,
                                        const int RabinMillerIterations=20);

This method generates a pseudo-random `LInteger` representing an integer which is probably prime, using prng as a pseudo-random bit source. fewerBits specifies what range this probable prime is to lie in: If fewerBits is 1 the integer will lie in the interval [0,2**maxBits-1], while if fewBits is 0, the integer will lie in the interval [2**(maxBits-1),2**(maxBits)-1]. RabinMillerIteration specifies the number of times a randomly generated integer must fail the Rabin-Miller compositeness test before it is considered to be "probably prime". Assuming that the pseudo-random number generator is unbiased, and a reasonable number of Rabin-Miller iterations are performed, each prime in the given interval should be as likely to be returned as any other, and the probability of returning a composite number should be very small. (See Schneier (11.5) for advice and references to research on what value to set RabinMillerIterations to for a given level of confidence that the return value here will represent a prime number.)

PreProcess allows the optional specification of a function to be to applied to each randomly generated `LInteger` before it is passed on to compositeness testing. This function may modify or test the `LInteger` in any way, but must leave it positive. If there is a PreProcess function and its return value is 0 a new random `LInteger` will be generated and old one discarded. If, on the other hand, there is a PreProcess function, and its return value is non-zero, the, possibly modifed, `LInteger` will be passed on for compositeness testing.

Next Previous Table of Contents