Package edu.wpi.first.units

Class Unit

java.lang.Object
edu.wpi.first.units.Unit
Direct Known Subclasses:
AngleUnit, CurrentUnit, DimensionlessUnit, DistanceUnit, EnergyUnit, MassUnit, MultUnit, PerUnit, TemperatureUnit, TimeUnit, VoltageUnit
public abstract class Unit extends Object
Unit of measurement that defines a quantity, such as grams, meters, or seconds.

This is the base class for units. Actual units (such as Units.Grams and Units.Meters) can be found in the Units class.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Unit(Unit baseUnit, double baseUnitEquivalent, String name, String symbol)
    Creates a new unit with the given name and multiplier to the base unit.
    protected
    Unit(Unit baseUnit, UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol)
    Creates a new unit defined by its relationship to some base unit.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object o)
     
    boolean
    equivalent(Unit other)
    Checks if this unit is equivalent to another one.
    double
    fromBaseUnits(double valueInBaseUnits)
    Converts a value in terms of base units to a value in terms of this unit.
    Unit
    getBaseUnit()
    Gets the base unit of measurement that this unit is derived from.
    UnaryFunction
    getConverterFromBase()
    Gets the conversion function used to convert values to terms of this unit.
    UnaryFunction
    getConverterToBase()
    Gets the conversion function used to convert values to base unit terms.
    int
    hashCode()
     
    boolean
    isBaseUnit()
    Checks if this unit is the base unit for its own system of measurement.
    abstract MutableMeasure<?,?,?>
    mutable(double initialMagnitude)
    Creates a new mutable measurement that is initialized to the given magnitude in terms of this unit.
    String
    name()
    Gets the name of this unit.
    abstract Measure<?>
    of(double magnitude)
    Creates a new immutable measurement of the given magnitude in terms of this unit.
    abstract Measure<?>
    ofBaseUnits(double baseUnitMagnitude)
    Creates a new immutable measurement of the given magnitude in terms of this unit's base unit.
    Measure<?>
    one()
    Gets a measure with a magnitude of 1.0 in terms of this unit.
    abstract Unit
    per(TimeUnit time)
    Combines this unit with a unit of time.
    String
    symbol()
    Gets the symbol of this unit.
    double
    toBaseUnits(double valueInNativeUnits)
    Converts a value in terms of this unit to a value in terms of the base unit.
    String
    toString()
     
    Measure<?>
    zero()
    Gets a measure of zero magnitude in terms of this unit.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Unit

      protected Unit(Unit baseUnit, UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol)
      Creates a new unit defined by its relationship to some base unit.
      Parameters:
      baseUnit - the base unit, e.g. Meters for distances. Set this to null if the unit being constructed is its own base unit
      toBaseConverter - a function for converting units of this type to the base unit
      fromBaseConverter - a function for converting units of the base unit to this one
      name - the name of the unit. This should be a singular noun (so "Meter", not "Meters")
      symbol - the short symbol for the unit, such as "m" for meters or "lb." for pounds

    • Unit

      protected Unit(Unit baseUnit, double baseUnitEquivalent, String name, String symbol)
      Creates a new unit with the given name and multiplier to the base unit.
      Parameters:
      baseUnit - the base unit, e.g. Meters for distances
      baseUnitEquivalent - the multiplier to convert this unit to the base unit of this type. For example, meters has a multiplier of 1, mm has a multiplier of 1e3, and km has multiplier of 1e-3.
      name - the name of the unit. This should be a singular noun (so "Meter", not "Meters")
      symbol - the short symbol for the unit, such as "m" for meters or "lb." for pounds

  • Method Details

    • of

      public abstract Measure<?> of(double magnitude)
      Creates a new immutable measurement of the given magnitude in terms of this unit. Implementations are strongly recommended to sharpen the return type to a unit-specific measurement implementation.
      Parameters:
      magnitude - the magnitude of the measurement.
      Returns:
      the measurement object

    • ofBaseUnits

      public abstract Measure<?> ofBaseUnits(double baseUnitMagnitude)
      Creates a new immutable measurement of the given magnitude in terms of this unit's base unit. Implementations are strongly recommended to sharpen the return type to a unit-specific measurement implementation.
      Parameters:
      baseUnitMagnitude - the magnitude in terms of the base unit
      Returns:
      the measurement object

    • mutable

      public abstract MutableMeasure<?,?,?> mutable(double initialMagnitude)
      Creates a new mutable measurement that is initialized to the given magnitude in terms of this unit. Implementations are strongly recommended to sharpen the return type to a unit-specific measurement implementation.
      Parameters:
      initialMagnitude - the initial magnitude of the mutable measurement
      Returns:
      the mutable measurement object

    • zero

      public Measure<?> zero()
      Gets a measure of zero magnitude in terms of this unit. The returned object is guaranteed to be of the same type returned by of(double). Subclasses are encouraged to override this method to sharpen the return type.
      Returns:
      a zero-magnitude measure of this unit

    • one

      public Measure<?> one()
      Gets a measure with a magnitude of 1.0 in terms of this unit. The returned object is guaranteed to be of the same type returned by of(double). Subclasses are encouraged to override this method to sharpen the return type.
      Returns:
      a measure of magnitude 1.0 in terms of this unit

    • per

      public abstract Unit per(TimeUnit time)
      Combines this unit with a unit of time. This often - but not always - results in a velocity. Subclasses should sharpen the return type to be unit-specific.
      Parameters:
      time - the unit of time
      Returns:
      the combined unit

    • getBaseUnit

      public Unit getBaseUnit()
      Gets the base unit of measurement that this unit is derived from. If the unit is the base unit, the unit will be returned.

      NOTE: Subclasses must override this method to provide the correct return type. Failing to do say will make unit combinations that use it break at runtime! 

      
   Unit baseUnit = new Unit(null, ...);
   baseUnit.getBaseUnit(); // returns baseUnit

   Unit derivedUnit = new Unit(baseUnit, ...);
   derivedUnit.getBaseUnit(); // returns baseUnit
      Returns:
      the base unit

    • isBaseUnit

      public boolean isBaseUnit()
      Checks if this unit is the base unit for its own system of measurement.
      Returns:
      true if this is the base unit, false if not

    • fromBaseUnits

      public double fromBaseUnits(double valueInBaseUnits)
      Converts a value in terms of base units to a value in terms of this unit.
      Parameters:
      valueInBaseUnits - the value in base units to convert
      Returns:
      the equivalent value in terms of this unit

    • toBaseUnits

      public double toBaseUnits(double valueInNativeUnits)
      Converts a value in terms of this unit to a value in terms of the base unit.
      Parameters:
      valueInNativeUnits - the value in terms of this unit to convert
      Returns:
      the equivalent value in terms of the base unit

    • getConverterToBase

      public UnaryFunction getConverterToBase()
      Gets the conversion function used to convert values to base unit terms. This generally shouldn't need to be used directly; prefer toBaseUnits(double) instead.
      Returns:
      the conversion function

    • getConverterFromBase

      public UnaryFunction getConverterFromBase()
      Gets the conversion function used to convert values to terms of this unit. This generally shouldn't need to be used directly; prefer fromBaseUnits(double) instead.
      Returns:
      the conversion function

    • equivalent

      public boolean equivalent(Unit other)
      Checks if this unit is equivalent to another one. Equivalence is determined by both units having the same base type and treat the same base unit magnitude as the same magnitude in their own units, to within Measure.EQUIVALENCE_THRESHOLD.
      Parameters:
      other - the unit to compare to.
      Returns:
      true if both units are equivalent, false if not

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • name

      public String name()
      Gets the name of this unit.
      Returns:
      the unit's name

    • symbol

      public String symbol()
      Gets the symbol of this unit.
      Returns:
      the unit's symbol

    • toString

      public String toString()
      Overrides:
      toString in class Object