org.xspace.mx
Interface Measurement

All Known Subinterfaces:
Angle, Length, Mass, Time
All Known Implementing Classes:
Angle, BaseUnit, BaseUnit, ImmutableAngle, ImmutableLength, ImmutableMass, ImmutableTime, Length, Mass, Time

public interface Measurement

The Measurement interface connects the value of a measurement to a system of units. It is the motivation behind the entire system.

Since:
0.1

Method Summary
 Measurement copy()
          Returns a new instance of a Measurement that is "equivalent" in value to this Measurement.
 Measurement div(double scaling)
          Divides this Measurement by a scalar value.
 Measurement div(Measurement other)
          Divides this Measurement by the other Measurement.
 java.lang.String getAbbr()
          An abbreviated description of the units of this Measurement
 java.lang.String getDescription()
          A description of the units of this Measurement
 SystemOfUnits getSystem()
          The system of units being used by this Measurement.
 Unit[] getSystemDimensions()
          An array of Units within the SystemOfUnits being used by this Measurement.
 double getSystemValue()
          The internal value of this measurement.
 double getValue(Measurement multipleOf)
          The value of this measurement relative to the dimensions of the input measurement.
 Measurement minus(Measurement other)
          Subtracts the other Measurement to this Measurement.
 Measurement mult(double scaling)
          Multiplies this Measurement by a scalar value.
 Measurement mult(Measurement other)
          Multiplies the other Measurement to this Measurement.
 Measurement plus(Measurement other)
          Adds the other Measurement to this Measurement.
 Measurement pow(double power)
          Raises this Measurement to the specified power.
 Measurement root(double power)
          Tales the root this Measurement by the specified power.
 

Method Detail

copy

public Measurement copy()
Returns a new instance of a Measurement that is "equivalent" in value to this Measurement.

Returns:
A new instance of a Measurement that is "equivalent" in value to this Measurement.

getSystem

public SystemOfUnits getSystem()

The system of units being used by this Measurement.

Knowledge of SystemOfUnits being used is vital for proper implementations of any of the arithmetic methods: plus(Measurement), minus(Measurement), mult(Measurement), div(Measurement). Both Measurements must reference the same SystemOfUnits for a proper comparison.

For example, if Person A weighs items in terms of kilograms, and Person B weighs items in terms of pounds, then they must both agree on a common system of units before they can properly compare weights. Their decision could be to measure items using the SI system of units, Imperial system of units, or perhaps some other one.

Returns:
Returns the system of units being used by this Measurement.
See Also:
getSystemDimensions()

getSystemDimensions

public Unit[] getSystemDimensions()

An array of Units within the SystemOfUnits being used by this Measurement.

This array of Dimensions is vital for proper implementations of any of the arithmetic methods: plus(Measurement), minus(Measurement), mult(Measurement), div(Measurement), pow(double), root(double).

For example, if this Measurement measures the speed of five meters per second, then this method would return an array of Dimensions that contains:

Returns:
Returns an array of Units being used by this Measurement.
See Also:
getSystem()

getSystemValue

public double getSystemValue()

The internal value of this measurement. Meant to be used in the implementations of the other methods.

For example, an implementation might store the value of the measurement as a multiple of the "standard units" of the SystemOfUnits being used.

Returns:
Returns the internal value of this Measurement.

getValue

public double getValue(Measurement multipleOf)
The value of this measurement relative to the dimensions of the input measurement.

Parameters:
multipleOf - The Measurement to compared with
Returns:
The value of this Measurement as a multiple of the input parameter.

plus

public Measurement plus(Measurement other)
                 throws MeasurementException

Adds the other Measurement to this Measurement.

Depending on the implementation, this may or may not alter this object.

Parameters:
other - The Measurement that is added to this Measurement
Returns:
A Measurement object that reflects the result of this addition.
Throws:
MeasurementException - if both Measurements cannot be added.

This could occur if they were not referring to the same SystemOfUnits.

This could occur if they did not possess the exact same array of Units.

See Also:
getSystem(), getSystemDimensions()

minus

public Measurement minus(Measurement other)
                  throws MeasurementException

Subtracts the other Measurement to this Measurement.

Depending on the implementation, this may or may not alter this object.

Parameters:
other - The Measurement that is subtracted to this Measurement
Returns:
A Measurement object that reflects the result of this subtraction.
Throws:
MeasurementException - if both Measurements cannot be subtracted.

This could occur if they were not referring to the same SystemOfUnits.

This could occur if they did not possess the exact same array of Units.

See Also:
getSystem(), getSystemDimensions()

mult

public Measurement mult(Measurement other)

Multiplies the other Measurement to this Measurement.

Depending on the implementation, this may or may not alter this object.

Parameters:
other - The Measurement that is multiplied by this Measurement
Returns:
A Measurement object that reflects the result of this multiplication

mult

public Measurement mult(double scaling)

Multiplies this Measurement by a scalar value. This does not affect the Units of the Measurement.

Depending on the implementation, this may or may not alter this object.

For example, if the Measurement represents five meters per second (5 [m / s]), and it is multiplied by 2, then the result will be ten meters per second (10 [m / s]).

Parameters:
scaling - A scalar value that multiplies this Measurement
Returns:
A Measurement object that reflects the result of this multiplication

div

public Measurement div(Measurement other)

Divides this Measurement by the other Measurement.

Depending on the implementation, this may or may not alter this object.

Parameters:
other - The Measurement that divided into this Measurement
Returns:
A Measurement object that reflects the result of this division

div

public Measurement div(double scaling)

Divides this Measurement by a scalar value. This does not affect the Units of the Measurement.

Depending on the implementation, this may or may not alter this object.

For example, if the Measurement represents five meters per second (5 [m / s]), and it is divided by 2, then the result will be two-and-a-half meters per second (2.5 [m / s]).

Parameters:
scaling - A scalar value that multiplies this Measurement
Returns:
A Measurement object that reflects the result of this multiplication

pow

public Measurement pow(double power)

Raises this Measurement to the specified power.

Depending on the implementation, this may or may not alter this object.

For example, if the Measurement represents five meters per second (5 [m / s]), and it is raised to the power of two, the result will be twenty-five meters squared per second squared (25 [m^2 / s^2]).

Parameters:
power - The power that this Measurement is raised to
Returns:
A Measurement object that reflects the result of raising the Measurement to the desired power
See Also:
root(double)

root

public Measurement root(double power)

Tales the root this Measurement by the specified power.

Depending on the implementation, this may or may not alter this object.

For example, if the Measurement represents nine square meters (9 [m^2]), and the square root is taken (power = 2), the result will be three meters (3 [m]).

Parameters:
power - The power that this Measurement is lowered by
Returns:
A Measurement object that reflects the result of lowering the Measurement by the desired power
See Also:
pow(double)

getDescription

public java.lang.String getDescription()
A description of the units of this Measurement

Returns:
A description of the units of this Measurement

getAbbr

public java.lang.String getAbbr()
An abbreviated description of the units of this Measurement

Returns:
An abbreviated description of the units of this Measurement