com.devexperts.util

Class MathUtil

java.lang.Object

com.devexperts.util.MathUtil

public class MathUtil
extends Object

A collection of non-trivial mathematical utility methods.

Method Summary

Modifier and Type	Method and Description
static int	div(int a, int b) Returns quotient according to number theory - i.e.
static long	div(long a, long b) Returns quotient according to number theory - i.e.
static String	formatDouble(double value, int scale) Returns a string representation of the double argument whose scale is the specified value.
static void	formatDouble(StringBuilder sb, double value, int scale) Returns a string representation of the double argument whose scale is the specified value.
static String	formatDoublePrecision(double value, int precision) Returns a string representation of the double argument with specified precision.
static void	formatDoublePrecision(StringBuilder sb, double value, int precision) Returns a string representation of the double argument with specified precision.
static double	parseDouble(CharSequence text) Fast implementation of double parser.
static double	parseDouble(CharSequence text, int start, int end) Fast implementation of double parser.
static int	rem(int a, int b) Returns remainder according to number theory - i.e.
static long	rem(long a, long b) Returns remainder according to number theory - i.e.
static double	roundDecimal(double x) Rounds a specified double number to a decimal number with at most 14 significant digits and at most 14 digits after decimal point.
static double	roundDecimal(double value, int scale, RoundingMode mode) Returns a double value scaled according to the RoundingMode and scale value.
static double	roundPrecision(double value, int precision, RoundingMode mode) Returns a double value rounded according to the RoundingMode and round precision.

Methods inherited from class java.lang.Object

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

Method Detail

roundDecimal

public static double roundDecimal(double x)

Rounds a specified double number to a decimal number with at most 14 significant digits and at most 14 digits after decimal point. When x is integer, NaN or infinity, then x is returned (this method does not round big integers to powers of 10).

For example, suppose you have 1 dollar and 10 cents and you pay 20 cent. You should keep 90 cents. However, the following expression is false in Java:

1.1 - 0.2 == 0.9

because both 1.1 and 0.2 do not have precise representations in double. To make this comparison work, you have to use roundDecimal method:

roundDecimal(1.1 - 0.2) == 0.9

As a general rule, you should use roundDecimal after any operation (addition, subtraction, multiplication, division) on two decimal numbers if you know that the result is a decimal with at most 14 significant digits and at most 14 digits after decimal point.

roundDecimal

public static double roundDecimal(double value,
                                  int scale,
                                  RoundingMode mode)

Returns a double value scaled according to the RoundingMode and scale value. This is a fast implementation compared to BigDecimal.setScale(int, java.math.RoundingMode). Returns similar result as BigDecimal setScale for RoundingMode (HALF_UP, HALF_DOWN, HALF_EVEN)

For Rounding Mode (UP, DOWN, CEILING, FLOOR) and values larger than 1E16 by absolute value it is possible to have different result than BigDecimal in very rare case. The positive scale parameter defines a number of fraction digits in the double value. The negative scale parameter defines a number of integer digits that will be assigned to 0.

Parameters:

value - double for round

scale - the number of fractional digits for the positive scale and the number of integer digits to be assigned the value 0 for negative scale

mode - RoundingMode

Returns:

scaled double value

Throws:

ArithmeticException - if the rounding mode is UNNECESSARY and the operation would require rounding.

parseDouble

public static double parseDouble(CharSequence text)
                          throws NumberFormatException

Fast implementation of double parser. This method works only with decimal representation of double values and is intolerant to leading or trailing spaces in CharSequence.

Parameters:

text - with double value

Returns:

double presentation

Throws:

NullPointerException - if the text is null

NumberFormatException - if the text does not contain valid double value

parseDouble

public static double parseDouble(CharSequence text,
                                 int start,
                                 int end)
                          throws NumberFormatException

Fast implementation of double parser. This method works only with decimal representation of double values and is intolerant to leading or trailing spaces in CharSequence range from start to end positions.

Parameters:

text - with double value

start - start position of value

end - end position of value, exclusive

Returns:

double presentation

Throws:

NullPointerException - if the text is null

NumberFormatException - if the text does not contain valid double value

formatDoublePrecision

public static String formatDoublePrecision(double value,
                                           int precision)

Returns a string representation of the double argument with specified precision. Produced string representation matches the syntax of Double.toString(double) but conforms to the following rules:

• A wider range is used for engineering format: Engineering notation is used for numbers in range from 0.000 000 001 to 1 000 000 000, otherwise scientific notation is used.
• In the scientific notation additional '.0' is omitted (Example: '1E10' instead of '1.0E10' for Double.toString(double))
• The precision parameter defines a number of significant digits in the result string. If precision is zero the formatting is performed without rounding like Double.toString(double)

  For a number with absolute value greater than 1E16, in very rare cases it's possible to have rounding not exactly the same as BigDecimal.valueOf(value).round(new MathContext(precision, RoundingMode.HALF_UP)), but anyway the value will match the result with RoundingMode.UP or RoundingMode.DOWN

Parameters:

value - double

precision - number of significant digits, effective rounding for [1,16]

Returns:

a string representation of the double argument with specified precision

Throws:

IllegalArgumentException - if precision less than 0

formatDoublePrecision

public static void formatDoublePrecision(StringBuilder sb,
                                         double value,
                                         int precision)

Returns a string representation of the double argument with specified precision. Produced string representation matches the syntax of Double.toString(double) but conforms to the following rules:

• A wider range is used for engineering format: Engineering notation is used for numbers in range from 0.000 000 001 to 1 000 000 000, otherwise scientific notation is used.
• In the scientific notation additional '.0' is omitted (Example: '1E10' instead of '1.0E10' for Double.toString(double))
• The precision parameter defines a number of significant digits in the result string. If precision is zero the formatting is performed without rounding like Double.toString(double)

  For a number with absolute value greater than 1E16, in very rare cases it's possible to have rounding not exactly the same as BigDecimal.valueOf(value).round(new MathContext(precision, RoundingMode.HALF_UP)), but anyway the value will match the result with RoundingMode.UP or RoundingMode.DOWN

Parameters:

sb - StringBuilder with formatted result

value - double

precision - number of significant digits, effective rounding for [1,16]

Throws:

NullPointerException - if the sb is null

IllegalArgumentException - for precision less than 0

formatDouble

public static String formatDouble(double value,
                                  int scale)

Returns a string representation of the double argument whose scale is the specified value. Produced string representation matches the syntax of Double.toString(double) but conforms to the following rules:

• A wider range is used for engineering format: Engineering notation is used for numbers in range from 0.000 000 001 to 1 000 000 000, otherwise scientific notation is used.
• In the scientific notation additional '.0' is omitted (Example: '1E10' instead of '1.0E10' for Double.toString(double))
• The positive scale parameter defines a number of fraction digits in the result string. The negative scale parameter defines a number of integer digits that will be assigned to 0 with defined round mode. This approach similar as in BigDecimal.setScale(int, java.math.RoundingMode). For a number with absolute value greater than 1E16, in very rare cases it's possible to have rounding not exactly the same as BigDecimal.valueOf(value).setScale(scale, RoundingMode.HALF_UP)), but anyway the value will match the result with RoundingMode.UP or RoundingMode.DOWN

Parameters:

value - double

scale - the number of fractional digits for the positive scale and the number of integer digits to be assigned the value 0 for negative scale

Returns:

a string representation of the double argument with specified scale

formatDouble

public static void formatDouble(StringBuilder sb,
                                double value,
                                int scale)

Returns a string representation of the double argument whose scale is the specified value. Produced string representation matches the syntax of Double.toString(double) but conforms to the following rules:

• A wider range is used for engineering format: Engineering notation is used for numbers in range from 0.000 000 001 to 1 000 000 000, otherwise scientific notation is used.
• In the scientific notation additional '.0' is omitted (Example: '1E10' instead of '1.0E10' for Double.toString(double))
• The positive scale parameter defines a number of fraction digits in the result string. The negative scale parameter defines a number of integer digits that will be assigned to 0 with defined round mode. This approach similar as in BigDecimal.setScale(int, java.math.RoundingMode). For a number with absolute value greater than 1E16, in very rare cases it's possible to have rounding not exactly the same as BigDecimal.valueOf(value).setScale(scale, RoundingMode.HALF_UP)), but anyway the value will match the result with RoundingMode.UP or RoundingMode.DOWN

Parameters:

sb - StringBuilder with formatted result with specified scale

value - double

scale - the number of fractional digits for the positive scale and the number of integer digits to be assigned the value 0 for negative scale

roundPrecision

public static double roundPrecision(double value,
                                    int precision,
                                    RoundingMode mode)

Returns a double value rounded according to the RoundingMode and round precision. If the round is 0 or more than 16 then no rounding takes place. This is a fast implementation compared to BigDecimal round. Returns similar result as BigDecimal round for RoundingMode (HALF_UP, HALF_DOWN, HALF_EVEN)

For Rounding Mode (UP, DOWN, CEILING, FLOOR) and values larger than 1E16 by absolute value it is possible to have different result than BigDecimal in very rare case.

Parameters:

value - double for round

precision - number of significant digits, effective rounding for [1,16]

mode - RoundingMode

Returns:

rounded double value

Throws:

ArithmeticException - if the rounding mode is UNNECESSARY and the operation would require rounding.

div

public static int div(int a,
                      int b)

Returns quotient according to number theory - i.e. when remainder is zero or positive.

Parameters:

a - dividend

b - divisor

Returns:

quotient according to number theory

div

public static long div(long a,
                       long b)

Returns quotient according to number theory - i.e. when remainder is zero or positive.

Parameters:

a - dividend

b - divisor

Returns:

quotient according to number theory

rem

public static int rem(int a,
                      int b)

Returns remainder according to number theory - i.e. when remainder is zero or positive.

Parameters:

a - dividend

b - divisor

Returns:

remainder according to number theory

rem

public static long rem(long a,
                       long b)

Returns remainder according to number theory - i.e. when remainder is zero or positive.

Parameters:

a - dividend

b - divisor

Returns:

remainder according to number theory