cz.auderis.tools.math

Class Round

java.lang.Object

cz.auderis.tools.math.Round

public final class Round
extends Object

Collection of methods for rounding real numbers. The functions are provided in two variants:

• rounding to an integral multiple of a given base value, which must be positive non-zero value, but does not have to be an integer
• rounding to an integer (i.e. the base value is 1.0)

Version:

1.0

Author:

Boleslav Bobcik

Method Summary

Modifier and Type	Method and Description
static BigDecimal	ceiling(BigDecimal x)
static BigDecimal	ceiling(BigDecimal x, BigDecimal baseStep)
static double	ceiling(double x) Rounds the number to the least integer n, such that x ≤ n.
static double	ceiling(double x, double baseStep) Rounds the number to the least integral multiple of the base step value, which is greater than or equal to the input value.
static BigDecimal	floor(BigDecimal x)
static BigDecimal	floor(BigDecimal x, BigDecimal baseStep)
static double	floor(double x) Rounds the number to the greatest integer n, such that n ≤ x.
static double	floor(double x, double baseStep) Rounds the number to the greatest integral multiple of the base step value, which is less than or equal to the input value.
static BigDecimal	halfDown(BigDecimal x)
static BigDecimal	halfDown(BigDecimal x, BigDecimal baseStep)
static double	halfDown(double x) Rounds the number to a nearest integer.
static double	halfDown(double x, double baseStep) Rounds the number to a nearest integral multiple of the base step value.
static BigDecimal	halfFromZero(BigDecimal x)
static BigDecimal	halfFromZero(BigDecimal x, BigDecimal baseStep)
static double	halfFromZero(double x) Rounds the number to a nearest integer.
static double	halfFromZero(double x, double baseStep) Rounds the number to a nearest integral multiple of the base step value.
static double	halfFromZeroToEven(double x)
static BigDecimal	halfTowardsZero(BigDecimal x)
static BigDecimal	halfTowardsZero(BigDecimal x, BigDecimal baseStep)
static double	halfTowardsZero(double x) Rounds the number to a nearest integer.
static double	halfTowardsZero(double x, double baseStep) Rounds the number to a nearest integral multiple of the base step value.
static BigDecimal	halfUp(BigDecimal x)
static BigDecimal	halfUp(BigDecimal x, BigDecimal baseStep)
static double	halfUp(double x) Rounds the number to a nearest integer.
static double	halfUp(double x, double baseStep) Rounds the number to a nearest integral multiple of the base step value.
static double	partFromMidpoint(double x, double baseStep, double splitFraction, double midpoint) This function provides further generalization of rounding.
static double	partFromZero(double x, double baseStep, double splitFraction) This function generalizes halfFromZero(double, double), where the "decision point" between two base step multiples is not exactly in the middle between them, but is specified as an arbitrary fraction.
static double	partTowardsMidpoint(double x, double baseStep, double splitFraction, double midpoint)
static double	partTowardsZero(double x, double baseStep, double splitFraction) This function generalizes halfTowardsZero(double, double), where the "decision point" between two base step multiples is not exactly in the middle between them, but is specified as an arbitrary fraction.
static BigDecimal	truncFromZero(BigDecimal x)
static BigDecimal	truncFromZero(BigDecimal x, BigDecimal baseStep)
static double	truncFromZero(double x) Rounds the number to the nearest integer, absolute value of which is greater than or equal to absolute value of the source number.
static double	truncFromZero(double x, double baseStep) Rounds the number to the nearest integral multiple of the base step value, which is not closer to zero than the source value.
static BigDecimal	truncTowardsZero(BigDecimal x)
static BigDecimal	truncTowardsZero(BigDecimal x, BigDecimal baseStep)
static double	truncTowardsZero(double x) Rounds the number to the nearest integer, absolute value of which is less than or equal to absolute value of the source number.
static double	truncTowardsZero(double x, double baseStep) Rounds the number to the nearest integral multiple of the base step value, which is not further to zero than the source value.

Methods inherited from class java.lang.Object

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

Method Detail

floor

public static double floor(double x)

Rounds the number to the greatest integer n, such that n ≤ x. Special cases are:

• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

Parameters:

x - a number

Returns:

the greatest integer less than or equal to x

See Also:

Math.floor(double)

floor

public static BigDecimal floor(BigDecimal x)

floor

public static double floor(double x,
                           double baseStep)

Rounds the number to the greatest integral multiple of the base step value, which is less than or equal to the input value. For example, calling floor(27.5, 10.0) will return value 20.0. Special cases:

• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

The base step value must be positive (greater than 0) and finite.

Formal mathematical description is floor(x, b) = N*b, where N is an integer and N*b ≤ x < (N+1)*b.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the greatest integral multiple of baseStep less than or equal to x

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

floor

public static BigDecimal floor(BigDecimal x,
                               BigDecimal baseStep)

ceiling

public static double ceiling(double x)

Rounds the number to the least integer n, such that x ≤ n. Special cases are:

• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

Parameters:

x - a number

Returns:

the least integer greater than or equal to x

See Also:

Math.ceil(double)

ceiling

public static BigDecimal ceiling(BigDecimal x)

ceiling

public static double ceiling(double x,
                             double baseStep)

Rounds the number to the least integral multiple of the base step value, which is greater than or equal to the input value. For example, calling ceiling(27.5, 10.0) will return value 30.0. Special cases:

• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

The base step value must be positive (greater than 0) and finite.

Formal mathematical description is ceiling(x, b) = N*b, where N is an integer and (N-1)*b < x ≤ (N)*b.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the least integral multiple of baseStep greater than or equal to x

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

ceiling

public static BigDecimal ceiling(BigDecimal x,
                                 BigDecimal baseStep)

truncFromZero

public static double truncFromZero(double x)

Rounds the number to the nearest integer, absolute value of which is greater than or equal to absolute value of the source number. Formally, for non-zero x, truncFromZero(x) = n such that abs(n)-1 < abs(x) ≤ abs(n) and sgn(n) = sgn(x).

Special cases are:

• x is zero (positive or negative): the result is unchanged
• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

Parameters:

x - a number

Returns:

the nearest integer, which is either equal to x or further from 0.0 than the value x

truncFromZero

public static BigDecimal truncFromZero(BigDecimal x)

truncFromZero

public static double truncFromZero(double x,
                                   double baseStep)

Rounds the number to the nearest integral multiple of the base step value, which is not closer to zero than the source value. Formally, for non-zero x, truncFromZero(x, b) = N*b such that sgn(x) = sgn(N) and (abs(N)-1)*b < abs(x) ≤ abs(N)*b.

Special cases:

• x is zero (positive or negative): the result is unchanged
• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

The base step value must be positive (greater than 0) and finite.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the integral multiple of the base step value, which is not closer to zero than the source value itself.

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

truncFromZero

public static BigDecimal truncFromZero(BigDecimal x,
                                       BigDecimal baseStep)

truncTowardsZero

public static double truncTowardsZero(double x)

Rounds the number to the nearest integer, absolute value of which is less than or equal to absolute value of the source number. Formally, for x (where abs(x) ≥ 1), truncTowardsZero(x) = n such that abs(n) ≤ abs(x) ≤ abs(n)+1 and sgn(n) = sgn(x).

Special cases are:

• x is zero (positive or negative): the result is unchanged
• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

Parameters:

x - a number

Returns:

the nearest integer, which is either equal to x or closer to 0.0 than the value x

truncTowardsZero

public static BigDecimal truncTowardsZero(BigDecimal x)

truncTowardsZero

public static double truncTowardsZero(double x,
                                      double baseStep)

Rounds the number to the nearest integral multiple of the base step value, which is not further to zero than the source value. Formally, for non-zero x such that abs(x) ≥ 1, truncTowardsZero(x, b) = N*b, where sgn(x) = sgn(N) and abs(N)*b ≤ abs(x) < (abs(N)+1)*b.

Special cases:

• for 0 < x < base step: the result is zero (+0)
• for -base step < x < 0: the result is negative zero (-0)
• x is zero (positive or negative): the result is unchanged
• x = NaN: the result is NaN
• x is positive or negative infinity: the result is unchanged

The base step value must be positive (greater than 0) and finite.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the integral multiple of the base step value, which is not further from zero than the source value itself.

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

truncTowardsZero

public static BigDecimal truncTowardsZero(BigDecimal x,
                                          BigDecimal baseStep)

halfFromZero

public static double halfFromZero(double x)

Rounds the number to a nearest integer. If the distance to surrounding integers is equal, the result is the integer with greater absolute value.

Examples:

• halfFromZero(3.3) = 3.0
• halfFromZero(3.81) = 4.0
• halfFromZero(-5.2) = -5.0
• halfFromZero(-5.64) = -6.0
• halfFromZero(1.5) = 2.0
• halfFromZero(-1.5) = -2.0

Parameters:

x - a number

Returns:

the nearest integer or, if two integers have equal distance to x, the integer with greater absolute value is returned

halfFromZero

public static BigDecimal halfFromZero(BigDecimal x)

halfFromZero

public static double halfFromZero(double x,
                                  double baseStep)

Rounds the number to a nearest integral multiple of the base step value. If two base step multiples have equal distance to the number x, the multiple with greater absolute value is returned.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the nearest integral multiple of baseStep; if two multiples have identical distance to x the result is the multiple with greater absolute value

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

halfFromZero

public static BigDecimal halfFromZero(BigDecimal x,
                                      BigDecimal baseStep)

halfTowardsZero

public static double halfTowardsZero(double x)

Rounds the number to a nearest integer. If the distance to surrounding integers is equal, the result is the integer with smaller absolute value.

Examples:

• halfTowardsZero(3.3) = 3.0
• halfTowardsZero(3.81) = 4.0
• halfTowardsZero(-5.2) = -5.0
• halfTowardsZero(-5.64) = -6.0
• halfTowardsZero(1.5) = 1.0
• halfTowardsZero(-1.5) = -1.0

Parameters:

x - a number

Returns:

the nearest integer or, if two integers have equal distance to x, the integer with smaller absolute value is returned

halfTowardsZero

public static BigDecimal halfTowardsZero(BigDecimal x)

halfTowardsZero

public static double halfTowardsZero(double x,
                                     double baseStep)

Rounds the number to a nearest integral multiple of the base step value. If two base step multiples have equal distance to the number x, the multiple with smaller absolute value is returned.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the nearest integral multiple of baseStep; if two multiples have identical distance to x the result is the multiple with smaller absolute value

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

halfTowardsZero

public static BigDecimal halfTowardsZero(BigDecimal x,
                                         BigDecimal baseStep)

halfUp

public static double halfUp(double x)

Rounds the number to a nearest integer. If the distance to surrounding integers is equal, the result is the greater integer (i.e. the number closer to positive infinity).

Examples:

• halfUp(3.3) = 3.0
• halfUp(3.81) = 4.0
• halfUp(-5.2) = -5.0
• halfUp(-5.64) = -6.0
• halfUp(1.5) = 2.0
• halfUp(-1.5) = -1.0

Parameters:

x - a number

Returns:

the nearest integer or, if two integers have equal distance to x, the greater integer is returned

halfUp

public static BigDecimal halfUp(BigDecimal x)

halfUp

public static double halfUp(double x,
                            double baseStep)

Rounds the number to a nearest integral multiple of the base step value. If two base step multiples have equal distance to the number x, the greater multiple of the two candidates is returned.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the nearest integral multiple of baseStep; if two multiples have identical distance to x the result is the greater multiple

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

halfUp

public static BigDecimal halfUp(BigDecimal x,
                                BigDecimal baseStep)

halfDown

public static double halfDown(double x)

Rounds the number to a nearest integer. If the distance to surrounding integers is equal, the result is the smaller integer (i.e. the number closer to negative infinity).

Examples:

• halfDown(3.3) = 3.0
• halfDown(3.81) = 4.0
• halfDown(-5.2) = -5.0
• halfDown(-5.64) = -6.0
• halfDown(1.5) = 1.0
• halfDown(-1.5) = -2.0

Parameters:

x - a number

Returns:

the nearest integer or, if two integers have equal distance to x, the smaller integer is returned

halfDown

public static BigDecimal halfDown(BigDecimal x)

halfDown

public static double halfDown(double x,
                              double baseStep)

Rounds the number to a nearest integral multiple of the base step value. If two base step multiples have equal distance to the number x, the smaller multiple of the two candidates is returned.

Parameters:

x - a number

baseStep - the "precision" of rounding

Returns:

the nearest integral multiple of baseStep; if two multiples have identical distance to x the result is the smaller multiple

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite

halfDown

public static BigDecimal halfDown(BigDecimal x,
                                  BigDecimal baseStep)

partFromZero

public static double partFromZero(double x,
                                  double baseStep,
                                  double splitFraction)

This function generalizes halfFromZero(double, double), where the "decision point" between two base step multiples is not exactly in the middle between them, but is specified as an arbitrary fraction.

Examples:

• partFromZero(14.1, 2.2, 0.3) = 15.4, because the surrounding multiples of 14.1 are 13.2 (2.2*6) and 15.4 (2.2*7), and the "0.3 decision point" between these multiples is 13.86
• partFromZero(-8.3, 0.75, 0.05) = -9 , because the surrounding multiples of -8.3 are -8.25 (-11*0.75) and -9 (-12*0.75), and the "0.05 decision point" between these multiples is -8.2875.

The following relation is valid: partFromZero(x, base, 0.5) = halfFromZero(x, base).

Parameters:

x - a number

baseStep - the "precision" of rounding

splitFraction - the relative position of "decision point" between the two consecutive integral multiples of baseStep

Returns:

the nearest integral multiple of baseStep. If the value x lies directly on the "decision point", the multiple with greater absolute value is returned

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite; or when the splitFraction is not within interval (0, 1).

partTowardsZero

public static double partTowardsZero(double x,
                                     double baseStep,
                                     double splitFraction)

This function generalizes halfTowardsZero(double, double), where the "decision point" between two base step multiples is not exactly in the middle between them, but is specified as an arbitrary fraction.

For detailed explanation, see partFromZero(double, double, double).

Parameters:

x - a number

baseStep - the "precision" of rounding

splitFraction - the relative position of "decision point" between the two consecutive integral multiples of baseStep

Returns:

the nearest integral multiple of baseStep. If the value x lies directly on the "decision point", the multiple with smaller absolute value is returned

Throws:

IllegalArgumentException - when the baseStep is negative, zero or infinite; or when the splitFraction is not within interval (0, 1).

partFromMidpoint

public static double partFromMidpoint(double x,
                                      double baseStep,
                                      double splitFraction,
                                      double midpoint)

This function provides further generalization of rounding.

Parameters:

x -

baseStep -

splitFraction -

midpoint -

Returns:

partTowardsMidpoint

public static double partTowardsMidpoint(double x,
                                         double baseStep,
                                         double splitFraction,
                                         double midpoint)

Parameters:

x -

baseStep -

splitFraction -

midpoint -

Returns:

halfFromZeroToEven

public static double halfFromZeroToEven(double x)

Parameters:

x -

Returns: