Package edu.wpi.first.units

Class UnitBuilder<U extends Unit>

java.lang.Object
edu.wpi.first.units.UnitBuilder<U>
Type Parameters:
U - the type of the unit
public final class UnitBuilder<U extends Unit> extends Object
Builder used for easily deriving new units from existing ones. When deriving a new unit, the base unit class must redeclare the constructor (U, UnaryFunction, UnaryFunction, String, String). The unit builder class will invoke this constructor automatically and build the new unit. Alternatively, new units can be derived by passing an explicit constructor function to make(UnitConstructorFunction).

  • Constructor Details

    • UnitBuilder

      public UnitBuilder(U base)
      Creates a new unit builder object, building off of a base unit. The base unit does not have to be the base unit of its unit system; furlongs work just as well here as meters.
      Parameters:
      base - the unit to base the new unit off of

  • Method Details

    • offset

      public UnitBuilder<U> offset(double offset)
      Sets the unit conversions based on a simple offset. The new unit will have its values equal to (base value - offset).
      Parameters:
      offset - the offset
      Returns:
      this builder

    • mappingInputRange

      public UnitBuilder<U>.MappingBuilder mappingInputRange(double minBase, double maxBase)
      Defines a mapping for values within the given input range. This method call should be immediately followed by .toOutputRange, eg mappingInputRange(1, 2).toOutputRange(3, 4), which will return the unit builder for continued chaining.
      Parameters:
      minBase - the minimum input value (does not have to be absolute)
      maxBase - the maximum output value (does not have to be absolute)
      Returns:
      a builder object used to define the output range

    • fromBase

      public UnitBuilder<U> fromBase(UnaryFunction fromBase)
      Sets the conversion function to transform values in the base unit to values in the derived unit.
      Parameters:
      fromBase - the conversion function
      Returns:
      the unit builder, for continued chaining

    • toBase

      public UnitBuilder<U> toBase(UnaryFunction toBase)
      Sets the conversion function to transform values in the derived unit to values in the base unit.
      Parameters:
      toBase - the conversion function
      Returns:
      the unit builder, for continued chaining

    • named

      public UnitBuilder<U> named(String name)
      Sets the name of the new unit.
      Parameters:
      name - the new name
      Returns:
      the unit builder, for continued chaining

    • symbol

      public UnitBuilder<U> symbol(String symbol)
      Sets the symbol of the new unit.
      Parameters:
      symbol - the new symbol
      Returns:
      the unit builder, for continued chaining

    • splitInto

      public UnitBuilder<U> splitInto(double fraction)
      Helper for defining units that are a scalar fraction of the base unit, such as centimeters being 1/100th of the base unit (meters). The fraction value is specified as the denominator of the fraction, so a centimeter definition would use splitInto(100) instead of splitInto(1/100.0).
      Parameters:
      fraction - the denominator portion of the fraction of the base unit that a value of 1 in the derived unit corresponds to
      Returns:
      the unit builder, for continued chaining

    • aggregate

      public UnitBuilder<U> aggregate(double aggregation)
      Helper for defining units that are a scalar multiple of the base unit, such as kilometers being 1000x of the base unit (meters).
      Parameters:
      aggregation - the magnitude required for a measure in the base unit to equal a magnitude of 1 in the derived unit
      Returns:
      the unit builder, for continued chaining

    • make

      public U make(UnitBuilder.UnitConstructorFunction<U> constructor)
      Creates the new unit based off of the builder methods called prior, passing them to a provided constructor function.
      Parameters:
      constructor - the function to use to create the new derived unit
      Returns:
      the new derived unit
      Throws:
      NullPointerException - if the unit conversions, unit name, or unit symbol were not set

    • make

      public U make()
      Creates the new unit based off of the builder methods called prior.
      Returns:
      the new derived unit
      Throws:
      NullPointerException - if the unit conversions, unit name, or unit symbol were not set
      RuntimeException - if the base unit does not define a constructor accepting the conversion functions, unit name, and unit symbol - in that order