From 46ba81a45f7cb10c7f870bbf6946a46207ee353c Mon Sep 17 00:00:00 2001 From: Alessio Leonardo Tomei <122273875+T0mexX@users.noreply.github.com> Date: Tue, 18 Mar 2025 10:31:21 +0100 Subject: Unit System v2 (#243) * Separated `Time` unit into `TimeDelta` and `TimeStamp` + small fixes Addition and subtruction between `Timestamp`s is not allowed, but any other `Unit` operation/comparison is. `TimeDelta`s can be added/subtructed to/form `Timestamp`s. Deserialization of `Timestamp`: - `Number` -> interpreted as millis from Epoch - `Instant` (string representation) -> converted to Timestamp - `Duration` (string representation) -> interpreted as duration since Epoch (warn msg is logged) Deserialization of `TimeDelta` is the same as `Time` was before, with the diference that when an `Instant` is converted to an timedelta since Epoch a warning message is logged. * Unit System v2 - Merged `BoundedPercentage` and `UnboundedPercentage` - Overrided all operation defined in `Unit` in all subclasses to avoid as much as possible value classes being boxed in bytecode. If units are used as generics (hence also functions defined in Unit) they are boxed (as double would if used as generic). - All units companions now subclass `UnitId`, and can be used as keys (e.g `Map`), while offering `max` `min` and `zero` methods. - Division between the same unit now returns `Percentage` - Added `Iterable.averageOfUnitOrNull(selector (T) -> )` - `ifNeg0ThenPos0()` now is optional and not invoked on every constructor - Now methods in `Unit` are all abstract, forcing override and avoid boxing in some cases - Added `@UnintendedOperation` and `UnitOperationException` for methods that must be defined but are not intended for use (e.g. `Timestamp` + `Timestamp`) --- .../main/kotlin/org/opendc/common/units/Energy.kt | 145 +++++++++++++++++++-- 1 file changed, 131 insertions(+), 14 deletions(-) (limited to 'opendc-common/src/main/kotlin/org/opendc/common/units/Energy.kt') diff --git a/opendc-common/src/main/kotlin/org/opendc/common/units/Energy.kt b/opendc-common/src/main/kotlin/org/opendc/common/units/Energy.kt index 467192a0..f54fe515 100644 --- a/opendc-common/src/main/kotlin/org/opendc/common/units/Energy.kt +++ b/opendc-common/src/main/kotlin/org/opendc/common/units/Energy.kt @@ -20,13 +20,19 @@ * SOFTWARE. */ -@file:OptIn(InternalUse::class) +@file:OptIn(InternalUse::class, NonInlinableUnit::class) package org.opendc.common.units import kotlinx.serialization.Serializable import org.opendc.common.annotations.InternalUse -import org.opendc.common.units.Time.Companion.toTime +import org.opendc.common.units.TimeDelta.Companion.toTimeDelta +import org.opendc.common.utils.DFLT_MIN_EPS +import org.opendc.common.utils.approx +import org.opendc.common.utils.approxLarger +import org.opendc.common.utils.approxLargerOrEq +import org.opendc.common.utils.approxSmaller +import org.opendc.common.utils.approxSmallerOrEq import org.opendc.common.utils.fmt import org.opendc.common.utils.ifNeg0thenPos0 import java.time.Duration @@ -42,7 +48,18 @@ public value class Energy private constructor( // In Joule override val value: Double, ) : Unit { - override fun new(value: Double): Energy = Energy(value.ifNeg0thenPos0()) + override fun toString(): String = fmtValue() + + override fun fmtValue(fmt: String): String = + if (value <= 1000.0) { + "${toJoule().fmt(fmt)} Joule" + } else { + "${toKJoule().fmt(fmt)} KJoule" + } + + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Conversions to Double + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// public fun toJoule(): Double = value @@ -52,22 +69,118 @@ public value class Energy private constructor( public fun toKWh(): Double = toWh() / 1000 - override fun toString(): String = fmtValue() + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Operation Override (to avoid boxing of value classes in byte code) + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// - override fun fmtValue(fmt: String): String = - if (value >= 1000.0) { - "${toJoule().fmt(fmt)} Joule" + public override fun ifNeg0ThenPos0(): Energy = Energy(value.ifNeg0thenPos0()) + + public override operator fun plus(other: Energy): Energy = Energy(value + other.value) + + public override operator fun minus(other: Energy): Energy = Energy(value - other.value) + + public override operator fun div(scalar: Number): Energy = Energy(value / scalar.toDouble()) + + public override operator fun div(other: Energy): Percentage = Percentage.ofRatio(value / other.value) + + public override operator fun times(scalar: Number): Energy = Energy(value * scalar.toDouble()) + + public override operator fun times(percentage: Percentage): Energy = Energy(value * percentage.value) + + public override operator fun unaryMinus(): Energy = Energy(-value) + + public override operator fun compareTo(other: Energy): Int = this.value.compareTo(other.value) + + public override fun isZero(): Boolean = value == .0 + + public override fun approxZero(epsilon: Double): Boolean = value.approx(.0, epsilon = epsilon) + + public override fun approx( + other: Energy, + minEpsilon: Double, + epsilon: Double, + ): Boolean = this == other || this.value.approx(other.value, minEpsilon, epsilon) + + public override infix fun approx(other: Energy): Boolean = approx(other, minEpsilon = DFLT_MIN_EPS) + + public override fun approxLarger( + other: Energy, + minEpsilon: Double, + epsilon: Double, + ): Boolean = this.value.approxLarger(other.value, minEpsilon, epsilon) + + public override infix fun approxLarger(other: Energy): Boolean = approxLarger(other, minEpsilon = DFLT_MIN_EPS) + + public override fun approxLargerOrEq( + other: Energy, + minEpsilon: Double, + epsilon: Double, + ): Boolean = this.value.approxLargerOrEq(other.value, minEpsilon, epsilon) + + public override infix fun approxLargerOrEq(other: Energy): Boolean = approxLargerOrEq(other, minEpsilon = DFLT_MIN_EPS) + + public override fun approxSmaller( + other: Energy, + minEpsilon: Double, + epsilon: Double, + ): Boolean = this.value.approxSmaller(other.value, minEpsilon, epsilon) + + public override infix fun approxSmaller(other: Energy): Boolean = approxSmaller(other, minEpsilon = DFLT_MIN_EPS) + + public override fun approxSmallerOrEq( + other: Energy, + minEpsilon: Double, + epsilon: Double, + ): Boolean = this.value.approxSmallerOrEq(other.value, minEpsilon, epsilon) + + public override infix fun approxSmallerOrEq(other: Energy): Boolean = approxSmallerOrEq(other, minEpsilon = DFLT_MIN_EPS) + + public override infix fun max(other: Energy): Energy = if (this.value > other.value) this else other + + public override infix fun min(other: Energy): Energy = if (this.value < other.value) this else other + + public override fun abs(): Energy = Energy(kotlin.math.abs(value)) + + public override fun roundToIfWithinEpsilon( + to: Energy, + epsilon: Double, + ): Energy = + if (this.value in (to.value - epsilon)..(to.value + epsilon)) { + to } else { - "${toKJoule().fmt(fmt)} KJoule" + this } - public operator fun div(time: Time): Power = Power.ofWatts(toWh() / time.toHours()) + public fun max( + a: Energy, + b: Energy, + ): Energy = if (a.value > b.value) a else b - public operator fun div(duration: Duration): Power = this / duration.toTime() + public fun min( + a: Energy, + b: Energy, + ): Energy = if (a.value < b.value) a else b - public companion object { - @JvmStatic - public val ZERO: Energy = Energy(.0) + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Unit Specific Operations + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + public operator fun div(timeDelta: TimeDelta): Power = Power.ofWatts(toWh() / timeDelta.toHours()) + + public operator fun div(duration: Duration): Power = this / duration.toTimeDelta() + + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Companion + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + public companion object : UnitId { + @JvmStatic override val zero: Energy = Energy(.0) + + @JvmStatic override val max: Energy = Energy(Double.MAX_VALUE) + + @JvmStatic override val min: Energy = Energy(Double.MIN_VALUE) + + public operator fun Number.times(unit: Frequency): Frequency = unit * this @JvmStatic @JvmName("ofJoule") @@ -87,9 +200,13 @@ public value class Energy private constructor( private val JOULES = Regex("\\s*(?:j|(?:joule|Joule)(?:|s))") + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // Serializer + // ////////////////////////////////////////////////////////////////////////////////////////////////////////////// + /** * Serializer for [Energy] value class. It needs to be a compile - * time constant in order to be used as serializer automatically, + * time constant to be used as serializer automatically, * hence `object :` instead of class instantiation. * * ```json -- cgit v1.2.3