net.sf.magnitude.core
Class Magnitude

java.lang.Object
  net.sf.magnitude.core.Magnitude

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable<Magnitude>

public class Magnitude
extends java.lang.Object
implements java.lang.Comparable<Magnitude>, java.lang.Cloneable

A magnitude is a value and its units. Mathematical operations take into account the units.

Translation from the python project magnitude of Juan Reyero

Author:

Philippe Pinard, Marin Lagacé

Constructor Summary

Magnitude(double val)
Creates a new dimension less Magnitude with the specified value.

Magnitude(double val, Magnitude units)
Creates a new Magnitude from the specified value and the units of another Magnitude object.

Magnitude(double val, java.lang.String units)
Creates a new Magnitude from the specified value and units expressed as a string.

Method Summary

Magnitude	add(Magnitude m) Adds two magnitudes together.
static void	addMag(java.lang.String symbol, Magnitude mag) Adds a magnitude to the list of known magnitudes.
boolean	areSameUnits(Magnitude m) Checks if the units of the two Magnitudes are the same.
boolean	areUnits(java.lang.String units) Checks whether this Magnitude can be expressed using the specified units.
void	clearPreferredUnits() Clears the preferred units.
Magnitude	clone() Creates a copy of the Magnitude object.
int	compareTo(Magnitude m) Compares two Magnitudes.
Magnitude	div(double k) Divides this Magnitude by a constant.
Magnitude	div(Magnitude m) Divides two magnitudes.
boolean	equals(Magnitude obj, Magnitude precision) Checks whether two Magnitudes are almost equal.
boolean	equals(java.lang.Object obj) Checks whether two Magnitudes are equal.
protected double[]	getBaseUnitExponents() Returns a base unit exponents for this magnitude.
java.lang.String	getBaseUnitsLabel() Returns a string representation of the units of this Magnitude.
double	getBaseUnitsValue() Returns the value of this Magnitude in the base units.
java.lang.String	getPreferredUnitsLabel() Returns the currently defined preferred units.
double	getPreferredUnitsValue() Returns the value of this Magnitude in the preferred units.
double	getValue(java.lang.String units) Returns the value of this Magnitude in the specified units.
int	hashCode() Returns the hash code of this Magnitude.
boolean	isDimensionless() Returns whether this Magnitude has units.
boolean	isExponent(BaseUnits baseUnit, int value) Checks if the exponent of the specified base unit is as specified.
boolean	isInfinite() Returns true if the value of this Magnitude is infinitely large, false otherwise.
static boolean	isInfinite(Magnitude m) Returns true if the value of the specified Magnitude is infinitely large, false otherwise.
boolean	isNaN() Returns true if the value of this Magnitude is a Not-a-Number (NaN), false otherwise.
static boolean	isNaN(Magnitude m) Returns true if the value of the specified Magnitude is a Not-a-Number (NaN), false otherwise.
boolean	isUnidimensional() Returns whether this Magnitude has only one type of unit.
static boolean	isValidUnits(java.lang.String units) Checks whether the specified units are valid (can be parsed by a Magnitude object).
Magnitude	minus(Magnitude m) Subtracts two magnitudes together.
Magnitude	modulo(Magnitude m) Returns the modulo of two Magnitude's.
Magnitude	multiply(double k) Multiplies this Magnitude by a constant.
Magnitude	multiply(Magnitude m) Multiplies two magnitudes.
Magnitude	power(double exponent) Power of this magnitude.
void	setPreferredUnits(java.lang.String units) Sets the preferred units for the output ( getPreferredUnitsValue()).
java.lang.String	toString() Returns a String representation.
void	validateEqualUnits(Magnitude m) Checks if the units of this Magnitude are equal to the units of another Magnitude.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Magnitude

public Magnitude(double val)

Creates a new dimension less Magnitude with the specified value.

Parameters:

val - value

Magnitude

public Magnitude(double val,
                 Magnitude units)

Creates a new Magnitude from the specified value and the units of another Magnitude object. The preferred units from the specified Magnitude are also transfered to the new Magnitude.

Parameters:

val - value

units - a Magnitude defining the units

Throws:

java.lang.NullPointerException - if the units Magnitude is null

Magnitude

public Magnitude(double val,
                 java.lang.String units)

Creates a new Magnitude from the specified value and units expressed as a string.

The preferred units are automatically set to be the specified units. This preference is lost if a multiplication or a division is performed. For the addition or the subtraction the preferred units of the first Magnitude are kept.

Parameters:

val - value

units - string representation of the units

Throws:

java.lang.NullPointerException - if the units are null

java.lang.IllegalArgumentException - if the string does not represent valid units

Method Detail

addMag

public static void addMag(java.lang.String symbol,
                          Magnitude mag)

Adds a magnitude to the list of known magnitudes.

Parameters:

symbol - string representation of the magnitude

mag - definition of the magnitude

Throws:

java.lang.NullPointerException - if the symbol or the magnitude is null

java.lang.IllegalArgumentException - if the symbol has already been defined to a different magnitude

isInfinite

public static boolean isInfinite(Magnitude m)

Returns true if the value of the specified Magnitude is infinitely large, false otherwise.

Parameters:

m - a magnitude

Returns:

true if the value represented by this object is positive infinity or negative infinity; false otherwise.

isNaN

public static boolean isNaN(Magnitude m)

Returns true if the value of the specified Magnitude is a Not-a-Number (NaN), false otherwise.

Parameters:

m - a magnitude

Returns:

true if the value represented by this object is NaN; false otherwise.

isValidUnits

public static boolean isValidUnits(java.lang.String units)

Checks whether the specified units are valid (can be parsed by a Magnitude object).

Parameters:

units - units

Returns:

true if the units are valid, false otherwise

add

@CheckReturnValue
public Magnitude add(Magnitude m)

Adds two magnitudes together. The magnitudes must have the same units.

Parameters:

m - other magnitude

Returns:

new magnitude with the added values

Throws:

java.lang.IllegalArgumentException - if the units are different

java.lang.NullPointerException - if the other magnitude is null

areSameUnits

public boolean areSameUnits(Magnitude m)

Checks if the units of the two Magnitudes are the same. For the units to be the same, they must be specified in both Magnitudes with the same exponent.

Parameters:

m - other magnitude

Returns:

true if the two Magnitudes are the same or false otherwise

Throws:

java.lang.NullPointerException - if the other magnitude is null

areUnits

public boolean areUnits(java.lang.String units)

Checks whether this Magnitude can be expressed using the specified units.

Parameters:

units - units to test the current Magnitude against

Returns:

true if this Magnitude can be expressed using the specified units or false if otherwise

clearPreferredUnits

public void clearPreferredUnits()

Clears the preferred units. The default units will be the one returned by getBaseUnitsLabel().

clone

public Magnitude clone()

Creates a copy of the Magnitude object.

Overrides:

clone in class java.lang.Object

Returns:

copy of this magnitude

compareTo

public int compareTo(Magnitude m)

Compares two Magnitudes. The two magnitudes must have the same units.

Specified by:

compareTo in interface java.lang.Comparable<Magnitude>

Parameters:

m - other magnitude

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object

Throws:

java.lang.IllegalArgumentException - if the two magnitudes have different units

java.lang.NullPointerException - if the other magnitude is null

div

@CheckReturnValue
public Magnitude div(double k)

Divides this Magnitude by a constant.

Parameters:

k - constant

Returns:

new Magnitude

div

@CheckReturnValue
public Magnitude div(Magnitude m)

Divides two magnitudes. The units are modified based on the units of the two magnitudes.

Parameters:

m - other magnitudes

Returns:

new magnitude with the divided value and units

Throws:

java.lang.NullPointerException - if the other magnitude is null

equals

public boolean equals(Magnitude obj,
                      Magnitude precision)

Checks whether two Magnitudes are almost equal. To be equal they must have the same units and the difference between their value must be less than the precision.

Parameters:

obj - other magnitude

precision - level of precision

Returns:

whether the two Magnitude are almost equal

Throws:

java.lang.IllegalArgumentException - if the precision is less than 0.0

java.lang.IllegalArgumentException - if the precision is not a number (NaN)

equals

public boolean equals(java.lang.Object obj)

Checks whether two Magnitudes are equal. To be equal they must have the same units and the same value.

Overrides:

equals in class java.lang.Object

Parameters:

obj - other magnitude

Returns:

true if they are equal, false otherwise

getBaseUnitExponents

protected double[] getBaseUnitExponents()

Returns a base unit exponents for this magnitude. For unit tests only.

Returns:

array of the unit exponents

getBaseUnitsLabel

public java.lang.String getBaseUnitsLabel()

Returns a string representation of the units of this Magnitude.

Returns:

units as a string

getBaseUnitsValue

public double getBaseUnitsValue()

Returns the value of this Magnitude in the base units.

Returns:

the value in the base units.

getPreferredUnitsLabel

public java.lang.String getPreferredUnitsLabel()

Returns the currently defined preferred units. If no preferred units are set, the base units will be returned.

Returns:

preferred units

getPreferredUnitsValue

public double getPreferredUnitsValue()

Returns the value of this Magnitude in the preferred units.

Returns:

the value in the preferred units.

See Also:

setPreferredUnits(java.lang.String)

getValue

public double getValue(java.lang.String units)

Returns the value of this Magnitude in the specified units.

Parameters:

units - units of the value

Returns:

value in the specified units

Throws:

java.lang.NullPointerException - if the units are null

hashCode

public int hashCode()

Returns the hash code of this Magnitude.

Overrides:

hashCode in class java.lang.Object

Returns:

hash code

isDimensionless

public boolean isDimensionless()

Returns whether this Magnitude has units.

Returns:

true if this Magnitude has no units, false otherwise

isExponent

public boolean isExponent(BaseUnits baseUnit,
                          int value)

Checks if the exponent of the specified base unit is as specified.

Parameters:

baseUnit - base unit to test the exponent of.

value - exponent value

Returns:

true if the value matches the exponent or false otherwise

isInfinite

public boolean isInfinite()

Returns true if the value of this Magnitude is infinitely large, false otherwise.

Returns:

true if the value represented by this object is positive infinity or negative infinity; false otherwise.

isNaN

public boolean isNaN()

Returns true if the value of this Magnitude is a Not-a-Number (NaN), false otherwise.

Returns:

true if the value represented by this object is NaN; false otherwise.

isUnidimensional

public boolean isUnidimensional()

Returns whether this Magnitude has only one type of unit.

Returns:

true if this Magnitude has one type of unit, false otherwise

minus

@CheckReturnValue
public Magnitude minus(Magnitude m)

Subtracts two magnitudes together. The magnitudes must have the same units.

Parameters:

m - other magnitude

Returns:

new magnitude with the subtracted values

Throws:

java.lang.IllegalArgumentException - if the units are different

java.lang.NullPointerException - if the other magnitude is null

modulo

@CheckReturnValue
public Magnitude modulo(Magnitude m)

Returns the modulo of two Magnitude's. The dividend and the divisor must have the same units.

Parameters:

m - other Magnitude

Returns:

new Magnitude

multiply

@CheckReturnValue
public Magnitude multiply(double k)

Multiplies this Magnitude by a constant.

Parameters:

k - constant

Returns:

new Magnitude

multiply

@CheckReturnValue
public Magnitude multiply(Magnitude m)

Multiplies two magnitudes. The units are modified based on the units of the two magnitudes.

Parameters:

m - other magnitudes

Returns:

new magnitude with the multiplied value and units

Throws:

java.lang.NullPointerException - if the other magnitude is null

power

@CheckReturnValue
public Magnitude power(double exponent)

Power of this magnitude.

Parameters:

exponent - exponent

Returns:

a new Magnitude

setPreferredUnits

public void setPreferredUnits(java.lang.String units)

Sets the preferred units for the output ( getPreferredUnitsValue()). The new preferred units must be equivalent to the present unit of this magnitude object.

Parameters:

units - new preferred units

Throws:

java.lang.IllegalArgumentException - if the new preferred units are not equivalent to the present units

toString

public java.lang.String toString()

Returns a String representation. The preferred units are used if they are set. If not the base units are used.

Overrides:

toString in class java.lang.Object

Returns:

a String representation

validateEqualUnits

public void validateEqualUnits(Magnitude m)

Checks if the units of this Magnitude are equal to the units of another Magnitude.

Parameters:

m - other magnitude

Throws:

java.lang.IllegalArgumentException - if the two magnitudes don't have the same units

java.lang.NullPointerException - if the other magnitude is null