BunyipsLib/au.edu.sa.mbhs.studentrobotics.bunyipslib.external.units/MutableMeasure

MutableMeasure

class MutableMeasure> : Measure

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 or mut_replace. 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

Since

1.0.0-pre

Parameters

the type of the unit of measure

Types

Companion

object Companion

Functions

baseUnitMagnitude

open override fun baseUnitMagnitude(): Double

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 magnitude.

copy

open override fun copy(): Measure

Returns an immutable copy of this measure. The copy can be used freely and is guaranteed never to change.

equals

open operator override fun equals(other: Any?): Boolean

hashCode

open override fun hashCode(): Int

magnitude

open override fun magnitude(): Double

Gets the unitless magnitude of this measure.

mut_acc

fun mut_acc(other: Measure): MutableMeasure

Increments the current magnitude of the measure by the amount of the given measure.

fun mut_acc(raw: Double): MutableMeasure

Increments the current magnitude of the measure by the given value. The value must be in terms of the current unit.

mut_divide

fun mut_divide(divisor: Measure<out Dimensionless>): MutableMeasure

fun mut_divide(divisor: Double): MutableMeasure

Divides this measurement by some constant value. This will mutate the object instead of generating a new measurement object.

mut_minus

fun mut_minus(other: Measure): MutableMeasure

Subtracts another measurement to this one. This will mutate the object instead of generating a new measurement object.

fun mut_minus(magnitude: Double, unit: U): MutableMeasure

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 to avoid having to wrap raw numbers in a Measure object and pay for an object allocation.

mut_plus

fun mut_plus(other: Measure): MutableMeasure

Adds another measurement to this one. This will mutate the object instead of generating a new measurement object.

fun mut_plus(magnitude: Double, unit: U): MutableMeasure

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 to avoid having to wrap raw numbers in a Measure object and pay for an object allocation.

mut_replace

fun mut_replace(other: Measure): MutableMeasure

Overwrites the state of this measure and replaces it with values from the given one.

fun mut_replace(magnitude: Double, unit: U): MutableMeasure

Overwrites the state of this measure with new values.

mut_setBaseUnitMagnitude

fun mut_setBaseUnitMagnitude(baseUnitMagnitude: Double)

Sets the new magnitude of the measurement. The magnitude must be in terms of the base unit of the current unit.

mut_setMagnitude

fun mut_setMagnitude(magnitude: Double)

Sets the new magnitude of the measurement. The magnitude must be in terms of the unit.

mut_times

fun mut_times(multiplier: Measure<out Dimensionless>): MutableMeasure

fun mut_times(multiplier: Double): MutableMeasure

Multiplies this measurement by some constant value. This will mutate the object instead of generating a new measurement object.

toString

open override fun toString(): String

unit

open override fun unit(): U

Gets the units of this measure.

Inherited functions

compareTo

open infix operator override fun compareTo(other: Measure): Int

diff

@JvmStatic

infix fun Measure<Angle>.diff(target: Measure<Angle>): Measure<Angle>

Calculates the shortest difference between two given angles.

div

open operator fun <U2 : Unit<U2>> div(other: Measure<U2>): Measure<*>

Divides this measurement by another measure and performs some dimensional analysis to reduce the units.

open operator fun div(divisor: Double): Measure

Divides this measurement by some constant divisor and returns the result. This is equivalent to times(1 / divisor)

open infix fun gt(o: Measure): Boolean

Checks if this measure is greater than another measure of the same unit.

gte

open infix fun gte(o: Measure): Boolean

Checks if this measure is greater than or equivalent to another measure of the same unit.

open infix fun in(unit: Unit): Double

Converts this measure to a measure with a different unit of the same type, eg minutes to seconds. Converting to the same unit is equivalent to calling magnitude.

isEquivalent

open infix fun isEquivalent(other: Measure<*>): Boolean

Checks if this measure is equivalent to another measure of the same unit.

isNear

open infix fun Measure<*>.isNear(varianceThreshold: Double): Boolean

Checks if this measure is near another measure of the same unit. Provide a variance threshold for use for a +/- scalar, such as 0.05 for +/- 5%.

open infix fun Measure.isNear(tolerance: Measure): Boolean

Checks if this measure is near another measure of the same unit, with a specified tolerance of the same unit.

open infix fun lt(o: Measure): Boolean

Checks if this measure is less than another measure of the same unit.

lte

open infix fun lte(o: Measure): Boolean

Checks if this measure is less than or equivalent to another measure of the same unit.

minus

open operator fun minus(other: Measure): Measure

Subtracts another measure from this one. The resulting measure has the same unit as this one.

moveTowards

@JvmStatic

fun Measure<Angle>.moveTowards(target: Measure<Angle>, maxDelta: Measure<Angle>): Measure<Angle>

Same as moveTowards, but makes sure the values interpolate correctly when they wrap around 1 revolution (360 degrees).

mutableCopy

open fun mutableCopy(): MutableMeasure

Creates a new mutable copy of this measure.

negate

open fun negate(): Measure

Negates this measure and returns the result.

per

open infix fun <U2 : Unit<U2>> per(denominator: U2): Measure<Per<U, U2>>

Creates a relational measure equivalent to this one per some other unit.

open infix fun per(period: Measure<Time>): Measure<Velocity>

Creates a velocity measure by dividing this one by a time period measure.

open infix fun per(time: Time): Measure<Velocity>

Creates a velocity measure equivalent to this one per a unit of time.

plus

open operator fun plus(other: Measure): Measure

Adds another measure to this one. The resulting measure has the same unit as this one.

smoothDamp

@JvmStatic

fun Measure<Angle>.smoothDamp(target: Measure<Angle>, currentVelocity: Reference<Double>, smoothTime: Measure<Time>, maxVelocity: Number, deltaTime: Measure<Time>): Measure<Angle>

Gradually changes an angle towards a desired goal over time.

times

open operator fun <U2 : Unit<U2>> times(other: Measure<U2>): Measure<*>

Generates a new measure that is equal to this measure multiplied by another. Some dimensional analysis is performed to reduce the units down somewhat; for example, multiplying a Measure<Time> by a Measure<Velocity<Distance>> will return just a Measure<Distance> instead of the naive Measure<Mult<Time, Velocity<Distance>>. This is not guaranteed to perform perfect dimensional analysis.

open operator fun times(multiplier: Double): Measure

Multiplies this measurement by some constant multiplier and returns the result. The magnitude of the result will be the base magnitude multiplied by the scalar value. If the measure uses a unit with a non-linear relation to its base unit (such as Fahrenheit for temperature), then the result will only be a multiple in terms of the base unit.

open infix fun to(unit: Unit): Double

Converts this measure to a measure with a different unit of the same type, eg minutes to seconds. Converting to the same unit is equivalent to calling magnitude.

toLongString

open fun toLongString(): String

Returns a string representation of this measurement in a longhand form. The name of the backing unit is used, rather than its symbol, and the magnitude is represented in a full string, not scientific notation. (Very large values may be represented in scientific notation, however)

toScientificString

open fun toScientificString(): String

Returns a string representation of this measurement in a scientific shorthand form. The symbol of the backing unit is used, rather than the full name, and the magnitude is represented in scientific notation.

toShortString

open fun toShortString(): String

Returns a string representation of this measurement in the default form. The symbol of the backing unit is used, rather than the full name, and the magnitude is represented in full, not in scientific notation. (Very large values may be represented in scientific notation, however)

unaryMinus

open operator fun unaryMinus(): Measure

Negates this measure and returns the result.

wrap

@JvmStatic

fun Measure<Angle>.wrap(): Measure<Angle>

Normalizes the given angle to be within the range of [0, 2pi) radians or [0, 360) degrees.

wrapDelta

@JvmStatic

fun Measure<Angle>.wrapDelta(): Measure<Angle>

Wraps an angle to the range -pi to pi radians.