Package edu.wpi.first.units

Class Unit<U extends Unit<U>>

java.lang.Object
edu.wpi.first.units.Unit<U>
Type Parameters:
U - the self type, e.g. class SomeUnit extends Unit<SomeUnit>
Direct Known Subclasses:
Angle, Current, Dimensionless, Distance, Energy, Mass, Mult, Per, Power, Temperature, Time, Velocity, Voltage
public class Unit<U extends Unit<U>> 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(U baseUnit, double baseUnitEquivalent, String name, String symbol)
    Creates a new unit with the given name and multiplier to the base unit.
    protected
    Unit(U 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
    double
    convertFrom(double magnitude, Unit<U> otherUnit)
    Converts a magnitude in terms of another unit of the same dimension to a magnitude in terms of this unit.
    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.
    U
    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.
    <U2 extends Unit<U2>>
    Mult<U,U2>
    mult(U2 other)
    Takes this unit and creates a new combinatory unit equivalent to this unit multiplied by another.
    String
    name()
    Gets the name of this unit.
    Measure<U>
    of(double magnitude)
    Creates a new measure of this unit with the given value.
    Measure<U>
    ofBaseUnits(double baseUnitMagnitude)
    Creates a new measure with a magnitude equal to the given base unit magnitude, converted to be in terms of this unit.
    Measure<U>
    one()
    Gets a measure with a magnitude of 1 in terms of this unit.
    <D extends Unit<D>>
    Per<U,D>
    per(D denominator)
    Takes this unit and creates a new proportional unit where this unit is the numerator and the given denominator is the denominator.
    Velocity<U>
    per(Time period)
    Creates a velocity unit derived from this one.
    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<U>
    zero()
    Gets a measure with a magnitude of 0 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(U 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(U 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

    • getBaseUnit

      public U 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. 
      
   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

    • convertFrom

      public double convertFrom(double magnitude, Unit<U> otherUnit)
      Converts a magnitude in terms of another unit of the same dimension to a magnitude in terms of this unit. 
         Inches.convertFrom(12, Feet) // 144.0
   Kilograms.convertFrom(2.2, Pounds) // 0.9979024
      Parameters:
      magnitude - a magnitude measured in another unit
      otherUnit - the unit to convert the magnitude to
      Returns:
      the corresponding value in terms of this 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

    • of

      public Measure<U> of(double magnitude)
      Creates a new measure of this unit with the given value. The resulting measure is immutable and cannot have its value modified.
      Parameters:
      magnitude - the magnitude of the measure to create
      Returns:
      the measure

    • ofBaseUnits

      public Measure<U> ofBaseUnits(double baseUnitMagnitude)
      Creates a new measure with a magnitude equal to the given base unit magnitude, converted to be in terms of this unit.
      Parameters:
      baseUnitMagnitude - the magnitude of the measure in terms of the base unit
      Returns:
      the measure

    • zero

      public Measure<U> zero()
      Gets a measure with a magnitude of 0 in terms of this unit.
      Returns:
      the zero-valued measure

    • one

      public Measure<U> one()
      Gets a measure with a magnitude of 1 in terms of this unit.
      Returns:
      the 1-valued measure

    • per

      public Velocity<U> per(Time period)
      Creates a velocity unit derived from this one. Can be chained to denote velocity, acceleration, jerk, etc. 
         Meters.per(Second) // linear velocity
   Kilograms.per(Second) // mass flow
   Feet.per(Second).per(Second).of(32) // roughly 1G of acceleration
      Parameters:
      period - the time period of the velocity, such as seconds or milliseconds
      Returns:
      a velocity unit corresponding to the rate of change of this unit over time

    • per

      public <D extends Unit<D>> Per<U,D> per(D denominator)
      Takes this unit and creates a new proportional unit where this unit is the numerator and the given denominator is the denominator. 
         Volts.per(Meter) // V/m
      Type Parameters:
      D - the type of the denominator units
      Parameters:
      denominator - the denominator of the proportional unit
      Returns:
      a combined proportional unit

    • mult

      public <U2 extends Unit<U2>> Mult<U,U2> mult(U2 other)
      Takes this unit and creates a new combinatory unit equivalent to this unit multiplied by another. 
         Volts.mult(Meter) // V*m
      Type Parameters:
      U2 - the type of the unit to multiply by
      Parameters:
      other - the unit to multiply by
      Returns:
      a combined unit equivalent to this unit multiplied by the other

    • 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