Package edu.wpi.first.units

Class MutableMeasure<U extends Unit<U>>

java.lang.Object
edu.wpi.first.units.MutableMeasure<U>
Type Parameters:
U - the type of the unit of measure
All Implemented Interfaces:
Measure<U>, Comparable<Measure<U>>
public final class MutableMeasure<U extends Unit<U>>
extends Object
implements Measure<U>
A specialization of Measure that allows for mutability. This is intended to be used for memory use reasons (such as on the memory-restricted roboRIO 1 or 2 or SBC coprocessors) and should NOT be exposed in the public API for a class that uses it.

The advantage of using this class is to reuse one instance of a measurement object, as opposed to instantiating a new immutable instance every time an operation is performed. This will reduce memory pressure, but comes at the cost of increased code complexity and sensitivity to race conditions if misused.

Any unsafe methods are prefixed with mut_*, such as mut_plus(Measure) or mut_replace(Measure). These methods will change the internal state of the measurement object, and as such can be dangerous to use. They are primarily intended for use to track internal state of things like sensors

  • Method Details

    • mutable

      public static <U extends Unit<U>> MutableMeasure<U> mutable​(Measure<U> measure)
      Creates a new mutable measure that is a copy of the given one.
      Type Parameters:
      U - the type of the units of measure
      Parameters:
      measure - the measure to create a mutable copy of
      Returns:
      a new mutable measure with an initial state equal to the given measure

    • zero

      public static <U extends Unit<U>> MutableMeasure<U> zero​(U unit)
      Creates a new mutable measure with a magnitude of 0 in the given unit.
      Type Parameters:
      U - the type of the units of measure
      Parameters:
      unit - the unit of measure
      Returns:
      a new mutable measure

    • ofBaseUnits

      public static <U extends Unit<U>> MutableMeasure<U> ofBaseUnits​(double baseUnitMagnitude, U unit)
      Creates a new mutable measure in the given unit with a magnitude equal to the given one in base units.
      Type Parameters:
      U - the type of the units of measure
      Parameters:
      baseUnitMagnitude - the magnitude of the measure, in terms of the base unit of measure
      unit - the unit of measure
      Returns:
      a new mutable measure

    • ofRelativeUnits

      public static <U extends Unit<U>> MutableMeasure<U> ofRelativeUnits​(double relativeMagnitude, U unit)
      Creates a new mutable measure in the given unit with a magnitude in terms of that unit.
      Type Parameters:
      U - the type of the units of measure
      Parameters:
      relativeMagnitude - the magnitude of the measure
      unit - the unit of measure
      Returns:
      a new mutable measure

    • magnitude

      public double magnitude()
      Description copied from interface: Measure
      Gets the unitless magnitude of this measure.
      Specified by:
      magnitude in interface Measure<U extends Unit<U>>
      Returns:
      the magnitude in terms of the unit.

    • baseUnitMagnitude

      public double baseUnitMagnitude()
      Description copied from interface: Measure
      Gets the magnitude of this measure in terms of the base unit. If the unit is the base unit for its system of measure, then the value will be equivalent to Measure.magnitude().
      Specified by:
      baseUnitMagnitude in interface Measure<U extends Unit<U>>
      Returns:
      the magnitude in terms of the base unit

    • unit

      public U unit()
      Description copied from interface: Measure
      Gets the units of this measure.
      Specified by:
      unit in interface Measure<U extends Unit<U>>
      Returns:
      the unit

    • mut_setMagnitude

      public void mut_setMagnitude​(double magnitude)
      Sets the new magnitude of the measurement. The magnitude must be in terms of the unit().
      Parameters:
      magnitude - the new magnitude of the measurement

    • mut_setBaseUnitMagnitude

      public void mut_setBaseUnitMagnitude​(double baseUnitMagnitude)
      Sets the new magnitude of the measurement. The magnitude must be in terms of the base unit of the current unit.
      Parameters:
      baseUnitMagnitude - the new magnitude of the measurement

    • mut_replace

      public MutableMeasure<U> mut_replace​(Measure<U> other)
      Overwrites the state of this measure and replaces it with values from the given one.
      Parameters:
      other - the other measure to copy values from
      Returns:
      this measure

    • mut_replace

      public MutableMeasure<U> mut_replace​(double magnitude, U unit)
      Overwrites the state of this measure with new values.
      Parameters:
      magnitude - the new magnitude in terms of the new unit
      unit - the new unit
      Returns:
      this measure

    • mut_acc

      public MutableMeasure<U> mut_acc​(double raw)
      Increments the current magnitude of the measure by the given value. The value must be in terms of the current unit.
      Parameters:
      raw - the raw value to accumulate by
      Returns:
      the measure

    • mut_acc

      public MutableMeasure<U> mut_acc​(Measure<U> other)
      Increments the current magnitude of the measure by the amount of the given measure.
      Parameters:
      other - the measure whose value should be added to this one
      Returns:
      the measure

    • mut_plus

      public MutableMeasure<U> mut_plus​(Measure<U> other)
      Adds another measurement to this one. This will mutate the object instead of generating a new measurement object.
      Parameters:
      other - the measurement to add
      Returns:
      this measure

    • mut_plus

      public MutableMeasure<U> mut_plus​(double magnitude, U unit)
      Adds another measurement to this one. This will mutate the object instead of generating a new measurement object. This is a denormalized version of mut_plus(Measure) to avoid having to wrap raw numbers in a Measure object and pay for an object allocation.
      Parameters:
      magnitude - the magnitude of the other measurement.
      unit - the unit of the other measurement
      Returns:
      this measure

    • mut_minus

      public MutableMeasure<U> mut_minus​(Measure<U> other)
      Subtracts another measurement to this one. This will mutate the object instead of generating a new measurement object.
      Parameters:
      other - the measurement to add
      Returns:
      this measure

    • mut_minus

      public MutableMeasure<U> mut_minus​(double magnitude, U unit)
      Subtracts another measurement to this one. This will mutate the object instead of generating a new measurement object. This is a denormalized version of mut_minus(Measure) to avoid having to wrap raw numbers in a Measure object and pay for an object allocation.
      Parameters:
      magnitude - the magnitude of the other measurement.
      unit - the unit of the other measurement
      Returns:
      this measure

    • mut_times

      public MutableMeasure<U> mut_times​(double multiplier)
      Multiplies this measurement by some constant value. This will mutate the object instead of generating a new measurement object.
      Parameters:
      multiplier - the multiplier to scale the measurement by
      Returns:
      this measure

    • mut_times

      public MutableMeasure<U> mut_times​(Measure<? extends Dimensionless> multiplier)
      Multiplies this measurement by some constant value. This will mutate the object instead of generating a new measurement object.
      Parameters:
      multiplier - the multiplier to scale the measurement by
      Returns:
      this measure

    • mut_divide

      public MutableMeasure<U> mut_divide​(double divisor)
      Divides this measurement by some constant value. This will mutate the object instead of generating a new measurement object.
      Parameters:
      divisor - the divisor to scale the measurement by
      Returns:
      this measure

    • mut_divide

      public MutableMeasure<U> mut_divide​(Measure<? extends Dimensionless> divisor)
      Divides this measurement by some constant value. This will mutate the object instead of generating a new measurement object.
      Parameters:
      divisor - the divisor to scale the measurement by
      Returns:
      this measure

    • copy

      public Measure<U> copy()
      Description copied from interface: Measure
      Returns an immutable copy of this measure. The copy can be used freely and is guaranteed never to change.
      Specified by:
      copy in interface Measure<U extends Unit<U>>
      Returns:
      the copied measure

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object