bb.science
Class FormatUtil

java.lang.Object
  extended by bb.science.FormatUtil

public final class FormatUtil
extends Object

Provides static utility methods to help in formatting/scaling of quantities.

This class is multithread safe: it is stateless.

Author:
Brent Boyer
See Also:
Prefix

Nested Class Summary
static class FormatUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Constructor Summary
private FormatUtil()
          This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.
 
Method Summary
static String toEngineeringString(BigDecimal quantity, Unit unit)
          Returns toEngineeringString(quantity, unit, -1) (i.e. all digits retained).
static String toEngineeringString(BigDecimal quantity, Unit unit, int numberDigitsFractional)
          Returns quantity expressed in enginnering notation with the exponent accounted for by the appropriate prefix of unit.
static String toEngineeringString(double quantity, Unit unit)
          Returns toEngineeringString(quantity, unit, -1) (i.e. all digits retained).
static String toEngineeringString(double quantity, Unit unit, int numberDigitsFractional)
          If quantity is NaN or infinite, then simply returns quantity + " " + unit.getSymbol().
static String toEngineeringTime(double time)
          Convenience method that simply returns toEngineeringTime(time, -1).
static String toEngineeringTime(double time, int numberDigitsFractional)
          Convenience method that simply returns toEngineeringString(time, Unit.second, numberDigitsFractional).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FormatUtil

private FormatUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.

Method Detail

toEngineeringString

public static String toEngineeringString(double quantity,
                                         Unit unit)
                                  throws IllegalArgumentException
Returns toEngineeringString(quantity, unit, -1) (i.e. all digits retained).

Parameters:
quantity - the number that is to be formatted
unit - the relevant Unit instance
Throws:
IllegalArgumentException - if unit == null

toEngineeringString

public static String toEngineeringString(BigDecimal quantity,
                                         Unit unit)
                                  throws IllegalArgumentException
Returns toEngineeringString(quantity, unit, -1) (i.e. all digits retained).

Parameters:
quantity - the number that is to be formatted
unit - the relevant Unit instance
Throws:
IllegalArgumentException - if unit == null

toEngineeringString

public static String toEngineeringString(double quantity,
                                         Unit unit,
                                         int numberDigitsFractional)
                                  throws IllegalArgumentException
If quantity is NaN or infinite, then simply returns quantity + " " + unit.getSymbol(). Else simply returns toEngineeringString(BigDecimal.valueOf(quantity), unit, numberDigitsFractional).

Parameters:
quantity - the number that is to be formatted
unit - the relevant Unit instance
numberDigitsFractional - is either -1 (meaning retain all digits), or else is some value >= 0 which specifies how many digits after the decimal point are to be retained
Throws:
IllegalArgumentException - if unit == null; numberDigitsFractional < -1

toEngineeringString

public static String toEngineeringString(BigDecimal quantity,
                                         Unit unit,
                                         int numberDigitsFractional)
                                  throws IllegalArgumentException
Returns quantity expressed in enginnering notation with the exponent accounted for by the appropriate prefix of unit. Here is what is returned:
  1. the numerical value of quantity, scaled by that power of 10 which puts it in the range [1, 1000)
  2. a space char
  3. the SI prefix symbol for the scaling factor (e.g. m for milli if the scaling factor was 10^-3)
  4. unit's symbol (e.g. s if unit is Unit.second)
Prefix.getScalePrefix is used to determine the scaling factor.

Parameters:
quantity - the number that is to be formatted
unit - the relevant Unit instance
numberDigitsFractional - is either -1 (meaning retain all digits), or else is some value >= 0 which specifies how many digits after the decimal point are to be retained
Throws:
IllegalArgumentException - if unit == null; numberDigitsFractional < -1

toEngineeringTime

public static String toEngineeringTime(double time)
Convenience method that simply returns toEngineeringTime(time, -1).

Parameters:
time - the time that is to be formatted; the units of this quantity must be in seconds

toEngineeringTime

public static String toEngineeringTime(double time,
                                       int numberDigitsFractional)
                                throws IllegalArgumentException
Convenience method that simply returns toEngineeringString(time, Unit.second, numberDigitsFractional).

Parameters:
time - the time that is to be formatted; the units of this quantity must be in seconds
numberDigitsFractional - is either -1 (meaning retain all digits), or else is some value >= 0 which specifies how many digits after the decimal point are to be retained
Throws:
IllegalArgumentException - if numberDigitsFractional < -1