bb.science
Class Prefix

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

public class Prefix
extends Object

This class models the state corresponding to a prefix for a scientific unit of measurement. In particular, it has name, symbol, (power of 10) exponent, and scaleFactor properties.

This class also offers static constants which are Prefix instances that model the standard SI unit prefixes.

This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).

Author:
Brent Boyer
See Also:
SI prefixes, The Prefixes of the SI, Prefixes for Basic Metric Units, Unit

Nested Class Summary
static class Prefix.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
static Prefix atto
          Models the SI prefix for 10-18, the atto.
static Prefix centi
          Models the SI prefix for 10-2, the centi.
static Prefix deci
          Models the SI prefix for 10-1, the deci.
static Prefix deka
          Models the SI prefix for 101, the deka.
static Prefix exa
          Models the SI prefix for 1018, the exa.
private  int exponent
          The exponent for the power of 10 that is associated with this prefix (e.g. -3, 3, 6 etc).
static Prefix femto
          Models the SI prefix for 10-15, the femto.
static Prefix giga
          Models the SI prefix for 109, the giga.
static Prefix hecto
          Models the SI prefix for 102, the hecto.
static Prefix kilo
          Models the SI prefix for 103, the kilo.
static Prefix mega
          Models the SI prefix for 106, the mega.
static Prefix micro
          Models the SI prefix for 10-6, the micro.
static Prefix milli
          Models the SI prefix for 10-3, the milli.
private  String name
          The full name of the prefix (e.g. milli, kilo, mega etc).
static Prefix nano
          Models the SI prefix for 10-9, the nano.
static Prefix nullPrefix
          Models the "null" prefix (i.e. when there is no visible prefix, that is, for 100 = 1).
static Prefix peta
          Models the SI prefix for 1015, the peta.
static Prefix pico
          Models the SI prefix for 10-12, the pico.
private  double scaleFactor
          Convenience field that equals 10exponent.
private  String symbol
          The symbol that identifies this prefix (e.g. m, k, M etc).
static Prefix tera
          Models the SI prefix for 1012, the tera.
static Prefix yocto
          Models the SI prefix for 10-24, the yocto.
static Prefix yotta
          Models the SI prefix for 1024, the yotta.
static Prefix zepto
          Models the SI prefix for 10-21, the zepto.
static Prefix zetta
          Models the SI prefix for 1021, the zetta.
 
Constructor Summary
protected Prefix()
          This special protected constructor is used solely to make a "null" Prefix instance.
  Prefix(String name, String symbol, int exponent)
          Constructs a new Prefix instance for the supplied name, symbol, and exponent.
 
Method Summary
 int getExponent()
          Returns the exponent for the power of 10 that is associated with this prefix (e.g. -3, 3, 6 etc).
 String getName()
          Returns the full name of the prefix (e.g. milli, kilo, mega etc).
 double getScaleFactor()
          Convenience method that returns the value of the scaleFactor field.
static Prefix getScalePrefix(double quantity)
          This method attempts to return a Prefix instance which will "best scale" the supplied quantity.
static Prefix[] getSiPrefixes()
          Returns an array of all the standard SI prefixes in order from yotta down to yocto.
 String getSymbol()
          Returns the symbol that identifies this prefix (e.g. m, k, M etc).
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

yotta

public static final Prefix yotta
Models the SI prefix for 1024, the yotta.


zetta

public static final Prefix zetta
Models the SI prefix for 1021, the zetta.


exa

public static final Prefix exa
Models the SI prefix for 1018, the exa.


peta

public static final Prefix peta
Models the SI prefix for 1015, the peta.


tera

public static final Prefix tera
Models the SI prefix for 1012, the tera.


giga

public static final Prefix giga
Models the SI prefix for 109, the giga.


mega

public static final Prefix mega
Models the SI prefix for 106, the mega.


kilo

public static final Prefix kilo
Models the SI prefix for 103, the kilo.


hecto

public static final Prefix hecto
Models the SI prefix for 102, the hecto.


deka

public static final Prefix deka
Models the SI prefix for 101, the deka.


nullPrefix

public static final Prefix nullPrefix
Models the "null" prefix (i.e. when there is no visible prefix, that is, for 100 = 1).


deci

public static final Prefix deci
Models the SI prefix for 10-1, the deci.


centi

public static final Prefix centi
Models the SI prefix for 10-2, the centi.


milli

public static final Prefix milli
Models the SI prefix for 10-3, the milli.


micro

public static final Prefix micro
Models the SI prefix for 10-6, the micro.


nano

public static final Prefix nano
Models the SI prefix for 10-9, the nano.


pico

public static final Prefix pico
Models the SI prefix for 10-12, the pico.


femto

public static final Prefix femto
Models the SI prefix for 10-15, the femto.


atto

public static final Prefix atto
Models the SI prefix for 10-18, the atto.


zepto

public static final Prefix zepto
Models the SI prefix for 10-21, the zepto.


yocto

public static final Prefix yocto
Models the SI prefix for 10-24, the yocto.


name

private final String name
The full name of the prefix (e.g. milli, kilo, mega etc).


symbol

private final String symbol
The symbol that identifies this prefix (e.g. m, k, M etc).


exponent

private final int exponent
The exponent for the power of 10 that is associated with this prefix (e.g. -3, 3, 6 etc).


scaleFactor

private final double scaleFactor
Convenience field that equals 10exponent.

Warning: this value may have roundoff error, so use at your own discretion. This always occurs whenever exponent is negative (because the base 2 system used by computers can never perfectly represent negative powers of 10). It will also occur if exponent is a sufficiently large positive value (because the limited precision of floating point numbers becomes insufficient to perfectly represent really large integers); with the 64-bit IEEE floating point implementation used by Java's double type, which uses 52 bits in the fractional part (appended after an implicit leading 1); this will happen for integers greater than 2^53 - 1 = 9,007,199,254,740,991 (i.e. powers of 10 greater than 15).

See Also:
The IEEE standard for floating point arithmetic
Constructor Detail

Prefix

protected Prefix()
This special protected constructor is used solely to make a "null" Prefix instance.

See Also:
nullPrefix

Prefix

public Prefix(String name,
              String symbol,
              int exponent)
       throws IllegalArgumentException
Constructs a new Prefix instance for the supplied name, symbol, and exponent.

Throws:
IllegalArgumentException - if name or symbol are either null or all whitespace
Method Detail

getSiPrefixes

public static Prefix[] getSiPrefixes()
Returns an array of all the standard SI prefixes in order from yotta down to yocto.


getScalePrefix

public static Prefix getScalePrefix(double quantity)
This method attempts to return a Prefix instance which will "best scale" the supplied quantity. Such a Prefix has the property that when its scaleFactor divides the quantity arg, it produces a number in the range [1, 1000). For example, the best Prefix for 2,000 would be kilo, and the best Prefix for 0.00001 would be micro.

The Prefixes returned are only the "standard" ones -- that is, those whose exponents are multiples of 3 (e.g. n = 10-6, m = 10-3, k = 103, G = 109, etc). Other prefixes (e.g. c = 10-2) are never returned.

If the quantity arg is either too large or small to be scaled using a standard SI prefix, or has some other problem (e.g. is NaN or infinite), then this method simply returns nullPrefix.

Parameters:
quantity - the number that is to be scaled by a Prefix

getName

public String getName()
Returns the full name of the prefix (e.g. milli, kilo, mega etc).


getSymbol

public String getSymbol()
Returns the symbol that identifies this prefix (e.g. m, k, M etc).


getExponent

public int getExponent()
Returns the exponent for the power of 10 that is associated with this prefix (e.g. -3, 3, 6 etc).


getScaleFactor

public double getScaleFactor()
Convenience method that returns the value of the scaleFactor field.


toString

public String toString()
Overrides:
toString in class Object