Instantly share code, notes, and snippets.

# tbuktu/BigInteger.java.phase3 Created Jan 7, 2012

Patched BigInteger using efficient algorithms for multiplication and division

Semantics of arithmetic operations exactly mimic those of Java's integer * arithmetic operators, as defined in The Java Language Specification. * For example, division by zero throws an {@code ArithmeticException}, and * division of a negative by a positive yields a negative (or zero) remainder. * All of the details in the Spec concerning overflow are ignored, as * BigIntegers are made as large as necessary to accommodate the results of an * operation. * *

Semantics of shift operations extend those of Java's shift operators * to allow for negative shift distances. A right-shift with a negative * shift distance results in a left shift, and vice-versa. The unsigned * right shift operator ({@code >>>}) is omitted, as this operation makes * little sense in combination with the "infinite word size" abstraction * provided by this class. * *

Semantics of bitwise logical operations exactly mimic those of Java's * bitwise integer operators. The binary operators ({@code and}, * {@code or}, {@code xor}) implicitly perform sign extension on the shorter * of the two operands prior to performing the operation. * *

Comparison operations perform signed integer comparisons, analogous to * those performed by Java's relational and equality operators. * *

Modular arithmetic operations are provided to compute residues, perform * exponentiation, and compute multiplicative inverses. These methods always * return a non-negative result, between {@code 0} and {@code (modulus - 1)}, * inclusive. * *

Bit operations operate on a single bit of the two's-complement * representation of their operand. If necessary, the operand is sign- * extended so that it contains the designated bit. None of the single-bit * operations can produce a BigInteger with a different sign from the * BigInteger being operated on, as they affect only a single bit, and the * "infinite word size" abstraction provided by this class ensures that there * are infinitely many "virtual sign bits" preceding each BigInteger. * *

For the sake of brevity and clarity, pseudo-code is used throughout the * descriptions of BigInteger methods. The pseudo-code expression * {@code (i + j)} is shorthand for "a BigInteger whose value is * that of the BigInteger {@code i} plus that of the BigInteger {@code j}." * The pseudo-code expression {@code (i == j)} is shorthand for * "{@code true} if and only if the BigInteger {@code i} represents the same * value as the BigInteger {@code j}." Other pseudo-code expressions are * interpreted similarly. * *