lava.math
Class MathToolbox

java.lang.Object
  |
  +--lava.math.MathToolbox

public class MathToolbox

extends java.lang.Object

Miscellaneous mathematical operations.

Details: MathToolbox is a collection of static methods for performing mathematical operations.

Since:

1998

Version:

1998.10.26

Field Summary

static double

TWO_PI Two times pi.

Method Summary

static int	compare(int i, int j) Compares two ints.
static int	compareUnsigned(int i, int j) Compares two ints as if they were 32-bit unsigned values.
static java.math.BigInteger	flipSignBits(java.math.BigInteger bi) Flips the sign bits in a BigInteger.
static int	log2Ceiling(int n) Computes the base-2 log ceiling of n.
static double	magnitude(double x, double y) Computes the magnitude of a 2D coordinate.
static java.math.BigDecimal	minimizeScale(java.math.BigDecimal bd) Minimizes the scale of a BigDecimal to the greatest extent possible without rounding.
static int	mod(int value, int lowerbound, int upperbound) Arbitrary modulus operation.
static long	overlap(long n0, long l0, long n1, long l1) Determines the number of overlapping integers in two ranges of integers.
static java.math.BigDecimal	setPrecision(java.math.BigDecimal bd, int n) Adjusts the fractional precision of a BigDecimal.
static java.math.BigDecimal	setSignificantDigits(java.math.BigDecimal bd, int n) Adjusts the number of significant digits in a BigDecimal.
static int	signum(int n) Returns the sign of n.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TWO_PI

public static final double TWO_PI

Two times pi.

Details: TWO_PI is the value obtained when Math.PI is multiplied by 2. It is stored here for convenience.

Since:

1998.11.12

Method Detail

overlap

public static final long overlap(long n0,
                                 long l0,
                                 long n1,
                                 long l1)

Determines the number of overlapping integers in two ranges of integers. Ranges are specified by naming the starting integer and extent (i.e., number of integers in the range).

Parameters:

n0 - the first integer in the first range

l0 - the extent (length) of the first range

n1 - the second integer in the second range

l1 - the extent (length) of the second range

Returns:

the number of integers held in common to both ranges

setSignificantDigits

public static final java.math.BigDecimal setSignificantDigits(java.math.BigDecimal bd,
                                                              int n)

Adjusts the number of significant digits in a BigDecimal.

Parameters:

bd - the value to adjust

n - the number of significant digits

Returns:

a BigDecimal with the specified number of significant digits

setPrecision

public static final java.math.BigDecimal setPrecision(java.math.BigDecimal bd,
                                                      int n)

Adjusts the fractional precision of a BigDecimal.

Parameters:

bd - the value to adjust

n - the number of digits after the decimal point

Returns:

a BigDecimal with the specified fractional precision

minimizeScale

public static final java.math.BigDecimal minimizeScale(java.math.BigDecimal bd)

Minimizes the scale of a BigDecimal to the greatest extent possible without rounding.

Parameters:

bd - the BigDecimal

Returns:

a scale-minimized BigDecimal with the same value

compare

public static final int compare(int i,
                                int j)

Compares two ints. Returns -1 if i < j, 0 if i = j, or +1 if i > j.

Parameters:

i - the "left" value in the comparison

j - the "right" value in the comparison

Returns:

the result of the comparison

compareUnsigned

public static final int compareUnsigned(int i,
                                        int j)

Compares two ints as if they were 32-bit unsigned values. Returns -1 if i < j, 0 if i = j, or +1 if i > j.

Parameters:

i - the "left" value in the comparison

j - the "right" value in the comparison

Returns:

the result of the comparison

flipSignBits

public static final java.math.BigInteger flipSignBits(java.math.BigInteger bi)

Flips the sign bits in a BigInteger. The value returned is the BigInteger with all of the sign bits flipped. (Recall that BigIntegers have infinite bit-width.)

Example: The bit representation of 3 is

000...00011.

This method will change the value to

111...11111,

or -1. (Elipses ("...") represent infinite repetition.)

The bit representation of -72 is

111...1110111000.

This method will change the value to

000...0000111000,

or 56.

Parameters:

bi - the BigInteger

Returns:

the BigInteger with negative sign bits removed

magnitude

public static final double magnitude(double x,
                                     double y)

Computes the magnitude of a 2D coordinate.

Details: magnitude computes the magnitude of a 2D coordinate, i.e., the distance from the origin.

To determine the phase of the coordinate, use java.lang.Math.atan2.

Parameters:

x - x coordinate

y - y coordinate

Returns:

the magnitude

Since:

1988.10.26

mod

public static final int mod(int value,
                            int lowerbound,
                            int upperbound)

Arbitrary modulus operation.

Details: The remainder operator % is useful for performing modulus operations, but only if the range begins at 0 and the domain is non-negative. This method provides a more generic modulus operation because it allows negative domains and arbitrarily positioned ranges.

lowerbound is the beginning of the range, and upperbound is one more than the last value allowed in the range. (Obviously, upperbound - lowerbound is the period of modulation.) value is the value to modulate.

The returned value, retval, is such that:

• lowerbound <= retval
• retval < upperbound
• (value - retval) is a multiple of (upperbound - lowerbound)

The % operator has these properties, too, but only for lowerbound == 0 and value >= 0.

Parameters:

value - value to modulate

lowerbound - bottom of range

upperbound - top of range

Returns:

modulated value within [lowerbound..upperbound)

Since:

1988.10.31

log2Ceiling

public static final int log2Ceiling(int n)

Computes the base-2 log ceiling of n.

Details: log2Ceiling returns the base-2 log of n, rounded up to the nearest whole integer. n is treated as a an unsigned int. If n==0, -1 is returned.

Parameters:

n - n

Returns:

the base-2 log ceiling of n

Since:

1998.12.12

signum

public static final int signum(int n)

Returns the sign of n.

Details: signum returns -1 if n<0, 0 if n==0, or +1 if n>0.

Parameters:

n - n

Returns:

the sign of n

Since:

1998.11.12