Package com.Ostermiller.util

Class SignificantFigures

java.lang.Object
java.lang.Number
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:

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

  • Constructor Summary

    Constructors
    Constructor
    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(short number)
    Create a SignificantFigures object from a short.
    SignificantFigures(Number number)
    Create a SignificantFigures object from a java number such as a BigDecimal, BigInteger, Byte, Double, Float, Integer, Long, or Short.
    SignificantFigures(String number)
    Create a SignificantFigures object from a String representation of a number.

  • Method Summary

    Modifier and Type
    Method
    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 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(short 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(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 Details

    • 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 Details

    • 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