com.Ostermiller.util

Class SignificantFigures

java.lang.Object

java.lang.Number

com.Ostermiller.util.SignificantFigures

All Implemented Interfaces:

java.io.Serializable

public class SignificantFigures
extends java.lang.Number

A number with an associated number of significant figures. This class handles parsing numbers, determining the number of significant figures, adjusting the number of significant figures (including scientific rounding), and displaying the number. More information about this class is available from ostermiller.org.

When parsing a number to determine the number of significant figures, these rules are used:

• Non-zero digits are always significant.
• All zeros between other significant digits are significant.
• All zeros left of the decimal point between a significant digit and the decimal point are significant.
• All trailing zeros to the right of the decimal point are significant.
• If the number is contains no digits other than zero, every zero is significant.

When rounding a number the following rules are used:

• If the greatest insignificant digit is less than five, round down.
• If the greatest insignificant digit is greater than five, round up.
• If the greatest insignificant digit is five and followed by some non-zero digit, round up.
• If the greatest insignificant digit is five and followed only by zeros, and the least significant digit is odd, round up.
• If the greatest insignificant digit is five and followed only by zeros, and the least significant digit is even, round down.

Example of using this class to multiply numbers and display the result with the proper number of significant figures:

 String[] arguments = {"1.0", "2.0", ...}
 SignificantFigures number;
 int sigFigs = Integer.MAX_VALUE;
 double result = 1D;
 for (int i=0; i<arguments.length; i++){
     number = new SignificantFigures(arguments[i]);
     sigFigs = Math.min(sigFigs, number.getNumberSignificantFigures());
     result *= number.doubleValue();
 }
 number = new SignificantFigures(result);
 number.setNumberSignificantFigures(sigFigs);
 System.out.println(number);

Example of using this class to add numbers and display the result with the proper number of significant figures:

 String[] arguments = {"1.0", "2.0", ...}
 SignificantFigures number;
 int leastSD = Integer.MIN_VALUE;
 int mostSD = Integer.MIN_VALUE;
 double result = 0D;
 for (int i=0; i<arguments.length; i++){
     number = new SignificantFigures(arguments[i]);
     leastSD = Math.max(leastSD, number.getLSD());
     mostSD = Math.max(mostSD, number.getMSD());
     result += number.doubleValue();
 }
 number = new SignificantFigures(result);
 number.setLMSD(leastSD, mostSD);
 System.out.println(number);

Since:

ostermillerutils 1.00.00

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
SignificantFigures(byte number) Create a SignificantFigures object from a byte.
SignificantFigures(double number) Create a SignificantFigures object from a double.
SignificantFigures(float number) Create a SignificantFigures object from a float.
SignificantFigures(int number) Create a SignificantFigures object from an integer.
SignificantFigures(long number) Create a SignificantFigures object from a long.
SignificantFigures(java.lang.Number number) Create a SignificantFigures object from a java number such as a BigDecimal, BigInteger, Byte, Double, Float, Integer, Long, or Short.
SignificantFigures(short number) Create a SignificantFigures object from a short.
SignificantFigures(java.lang.String number) Create a SignificantFigures object from a String representation of a number.

Method Summary

Modifier and Type	Method and Description
byte	byteValue() Returns the value of this number as a byte.
double	doubleValue() Returns the value of this number as a double.
float	floatValue() Returns the value of this number as a float.
static java.lang.String	format(byte number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(double number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(float number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(int number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(long number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(java.lang.Number number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(short number, int significantFigures) Convenience method to display a number with the correct significant digits.
static java.lang.String	format(java.lang.String number, int significantFigures) Convenience method to display a number with the correct significant digits.
int	getLSD() Get the decimal place of the least significant digit.
int	getMSD() Get the decimal place of the most significant digit.
int	getNumberSignificantFigures() Get the number of significant digits.
int	intValue() Returns the value of this number as a int.
long	longValue() Returns the value of this number as a long.
SignificantFigures	setLMSD(int leastPlace, int mostPlace) Adjust the number of significant figures such that the least significant digit is at the given place.
SignificantFigures	setLSD(int place) Adjust the number of significant figures such that the least significant digit is at the given place.
SignificantFigures	setNumberSignificantFigures(int significantFigures) Adjust the number of digits in the number.
short	shortValue() Returns the value of this number as a short.
java.lang.String	toScientificNotation() Formats this number in scientific notation.
java.lang.String	toString() Formats this number.

Methods inherited from class java.lang.Object

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

Constructor Detail

SignificantFigures

public SignificantFigures(java.lang.String number)
                   throws java.lang.NumberFormatException

Create a SignificantFigures object from a String representation of a number.

Parameters:

number - String representation of the number.

Throws:

java.lang.NumberFormatException - if the String is not a valid number.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(byte number)

Create a SignificantFigures object from a byte.

Parameters:

number - an 8 bit integer.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(short number)

Create a SignificantFigures object from a short.

Parameters:

number - a 16 bit integer.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(int number)

Create a SignificantFigures object from an integer.

Parameters:

number - a 32 bit integer.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(long number)

Create a SignificantFigures object from a long.

Parameters:

number - a 64 bit integer.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(float number)

Create a SignificantFigures object from a float.

Parameters:

number - a 32 bit floating point.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(double number)

Create a SignificantFigures object from a double.

Parameters:

number - a 64 bit floating point.

Since:

ostermillerutils 1.00.00

SignificantFigures

public SignificantFigures(java.lang.Number number)

Create a SignificantFigures object from a java number such as a BigDecimal, BigInteger, Byte, Double, Float, Integer, Long, or Short.

Parameters:

number - a number.

Since:

ostermillerutils 1.00.00

Method Detail

getNumberSignificantFigures

public int getNumberSignificantFigures()

Get the number of significant digits.

If this number is not a number or infinity zero will be returned.

Returns:

the number of significant digits in this number.

Since:

ostermillerutils 1.00.00

setLSD

public SignificantFigures setLSD(int place)

Adjust the number of significant figures such that the least significant digit is at the given place. This method may add significant zeros to the end of this number, or remove significant digits from this number.

It is possible to remove all significant digits from this number which will cause the string representation of this number to become "NaN". This could become a problem if you are adding numbers and the result is close to zero. All of the significant digits may get removed, even though the result could be zero with some number of significant digits. Its is safes to use the setLMSD() method which will make a zero with the appropriate number of significant figures in such instances.

This method has no effect if this number is not a number or infinity.

Parameters:

place - the desired place of the least significant digit.

Returns:

this number.

Since:

ostermillerutils 1.00.00

setLMSD

public SignificantFigures setLMSD(int leastPlace,
                                  int mostPlace)

Adjust the number of significant figures such that the least significant digit is at the given place. This method may add significant zeros to the end of this number, or remove significant digits from this number.

If all significant digits are removed from this number by truncating to the least significant place, a zero will be created with significant figures from the least to most significant places.

This method has no effect if this number is not a number or infinity.

Parameters:

leastPlace - the desired place of the least significant digit or Integer.MIN_VALUE to ignore.

mostPlace - the desired place of the most significant digit or Integer.MIN_VALUE to ignore.

Returns:

this number

Since:

ostermillerutils 1.00.00

getLSD

public int getLSD()

Get the decimal place of the least significant digit.

If this number is not a number or infinity Integer.MIN_VALUE will be returned.

Returns:

the decimal place of the least significant digit.

Since:

ostermillerutils 1.00.00

getMSD

public int getMSD()

Get the decimal place of the most significant digit.

If this number is not a number or infinity Integer.MIN_VALUE will be returned.

Returns:

the decimal place of the least significant digit.

Since:

ostermillerutils 1.00.00

toString

public java.lang.String toString()

Formats this number. If the number is less than 10^-3 or greater than or equal to 10^7, or the number might have an ambiguous number of significant figures, scientific notation will be used.

A string such as "NaN" or "Infinity" may be returned by this method.

Overrides:

toString in class java.lang.Object

Returns:

representation of this number.

Since:

ostermillerutils 1.00.00

toScientificNotation

public java.lang.String toScientificNotation()

Formats this number in scientific notation.

A string such as "NaN" or "Infinity" may be returned by this method.

Returns:

representation of this number in scientific notation.

Since:

ostermillerutils 1.00.00

setNumberSignificantFigures

public SignificantFigures setNumberSignificantFigures(int significantFigures)

Adjust the number of digits in the number. Pad the tail with zeros if too short, round the number according to scientific rounding if too long, leave alone if just right.

This method has no effect if this number is not a number or infinity.

Parameters:

significantFigures - desired number of significant figures.

Returns:

This number.

Since:

ostermillerutils 1.00.00

byteValue

public byte byteValue()
               throws java.lang.NumberFormatException

Returns the value of this number as a byte.

Overrides:

byteValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type byte.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a byte.

Since:

ostermillerutils 1.00.00

doubleValue

public double doubleValue()
                   throws java.lang.NumberFormatException

Returns the value of this number as a double.

Specified by:

doubleValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type double.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a double.

Since:

ostermillerutils 1.00.00

floatValue

public float floatValue()
                 throws java.lang.NumberFormatException

Returns the value of this number as a float.

Specified by:

floatValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type float.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a float.

Since:

ostermillerutils 1.00.00

intValue

public int intValue()
             throws java.lang.NumberFormatException

Returns the value of this number as a int.

Specified by:

intValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type int.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a int.

Since:

ostermillerutils 1.00.00

longValue

public long longValue()
               throws java.lang.NumberFormatException

Returns the value of this number as a long.

Specified by:

longValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type long.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a long.

Since:

ostermillerutils 1.00.00

shortValue

public short shortValue()
                 throws java.lang.NumberFormatException

Returns the value of this number as a short.

Overrides:

shortValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type short.

Throws:

java.lang.NumberFormatException - if this number cannot be converted to a short.

Since:

ostermillerutils 1.00.00

format

public static java.lang.String format(byte number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(double number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(float number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(int number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(long number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(java.lang.Number number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(short number,
                                      int significantFigures)

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Since:

ostermillerutils 1.02.07

format

public static java.lang.String format(java.lang.String number,
                                      int significantFigures)
                               throws java.lang.NumberFormatException

Convenience method to display a number with the correct significant digits.

Parameters:

number - the number to display

significantFigures - the number of significant figures to display.

Returns:

the number formatted with the correct significant figures

Throws:

java.lang.NumberFormatException - if the String is not a valid number.

Since:

ostermillerutils 1.02.07