com.Ostermiller.util Java Utilities


com.Ostermiller.util
Class SignificantFigures

java.lang.Object
  extended by java.lang.Number
      extended by com.Ostermiller.util.SignificantFigures
All Implemented Interfaces:
Serializable

public class SignificantFigures
extends 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:

When rounding a number the following rules are used:

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
Author:
Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
See Also:
Serialized Form

Constructor Summary
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(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(String number)
          Create a SignificantFigures object from a String representation of a number.
 
Method Summary
 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 String format(byte number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(double number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(float number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(int number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(long number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(Number number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(short number, int significantFigures)
          Convenience method to display a number with the correct significant digits.
static String format(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.
 String toScientificNotation()
          Formats this number in scientific notation.
 String toString()
          Formats this number.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SignificantFigures

public SignificantFigures(String number)
                   throws NumberFormatException
Create a SignificantFigures object from a String representation of a number.

Parameters:
number - String representation of the number.
Throws:
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(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 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 Object
Returns:
representation of this number.
Since:
ostermillerutils 1.00.00

toScientificNotation

public 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 NumberFormatException
Returns the value of this number as a byte.

Overrides:
byteValue in class Number
Returns:
the numeric value represented by this object after conversion to type byte.
Throws:
NumberFormatException - if this number cannot be converted to a byte.
Since:
ostermillerutils 1.00.00

doubleValue

public double doubleValue()
                   throws NumberFormatException
Returns the value of this number as a double.

Specified by:
doubleValue in class Number
Returns:
the numeric value represented by this object after conversion to type double.
Throws:
NumberFormatException - if this number cannot be converted to a double.
Since:
ostermillerutils 1.00.00

floatValue

public float floatValue()
                 throws NumberFormatException
Returns the value of this number as a float.

Specified by:
floatValue in class Number
Returns:
the numeric value represented by this object after conversion to type float.
Throws:
NumberFormatException - if this number cannot be converted to a float.
Since:
ostermillerutils 1.00.00

intValue

public int intValue()
             throws NumberFormatException
Returns the value of this number as a int.

Specified by:
intValue in class Number
Returns:
the numeric value represented by this object after conversion to type int.
Throws:
NumberFormatException - if this number cannot be converted to a int.
Since:
ostermillerutils 1.00.00

longValue

public long longValue()
               throws NumberFormatException
Returns the value of this number as a long.

Specified by:
longValue in class Number
Returns:
the numeric value represented by this object after conversion to type long.
Throws:
NumberFormatException - if this number cannot be converted to a long.
Since:
ostermillerutils 1.00.00

shortValue

public short shortValue()
                 throws NumberFormatException
Returns the value of this number as a short.

Overrides:
shortValue in class Number
Returns:
the numeric value represented by this object after conversion to type short.
Throws:
NumberFormatException - if this number cannot be converted to a short.
Since:
ostermillerutils 1.00.00

format

public static 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 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 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 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 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 String format(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 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 String format(String number,
                            int significantFigures)
                     throws 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:
NumberFormatException - if the String is not a valid number.
Since:
ostermillerutils 1.02.07

com.Ostermiller.util Java Utilities


Copyright © 2001-2012 by Stephen Ostermiller