Coulomb Unit Analysis Library

In coulomb, implicit truncating conversions (e.g., converting Mega * Byte to Byte using an Int type) are generally avoided because they are numerically unsafe.

In coulomb-pureconfig I/O, conversions will only succeed for integer types if:

1. The unit in the configuration source exactly matches the target type.
2. The conversion coefficient between the source unit and the target unit is exactly 1.

Best Practice: To ensure unit conversions always succeed without precision loss, use fractional value types like Float or Double for your Quantity definitions.

// source for a quantity value
val qsrc = ConfigSource.string("""
{
    value: 3
    unit: megabyte
}
""")

// succeeds when type matches
qsrc.load[Quantity[Int, Mega * Byte]]

// succeeds when conversion coefficient is exactly 1
qsrc.load[Quantity[Long, Byte * Mega]]

// fails if conversion is not exactly 1 (e.g. requires truncation)
qsrc.load[Quantity[Int, Kilo * Byte]]

To bridge the gap between runtime unit expressions and static unit types (e.g., when loading unit-aware configurations), use a CoefficientRuntime.

1. Define a CoefficientRuntime (e.g., using MappingCoefficientRuntime.of) and provide the package names containing the unit types you want to support.
2. Use the .toQuantity[ValueType, StaticUnitType] method on a RuntimeQuantity.

Because the conversion depends on runtime data, the result is returned as an Either[_, Quantity[ValueType, StaticUnitType]] to handle cases where units are incompatible.

// 1. Setup the coefficient runtime with package mappings
given given_CRT: CoefficientRuntime = MappingCoefficientRuntime.of[
    "coulomb.units.si" *: 
    "coulomb.units.si.prefixes" *: 
    EmptyTuple
]

// 2. Convert from runtime to static
// Valid conversion
val result1 = rq.toQuantity[Float, Kilo * Meter / Second]

// Valid conversion with different value type
val result2 = rq.toQuantity[Double, Meter / Second]

// This will return a Left (failure) because units are incompatible
val result3 = rq.toQuantity[Float, Second]

In coulomb, certain units represent absolute positions rather than relative amounts. This applies to:

• Temperatures: Absolute temperatures (e.g., Celsius) vs. units of degrees.
• Time: Absolute timestamps (instants) vs. units of duration.

Algebraic Rules for Absolute Values

Because these values are 'anchored' to a reference point (like the Kelvin scale or the Unix epoch), certain operations are invalid:

• Subtraction: Subtracting two absolute temperatures/timestamps yields a Quantity (a delta/duration).
• Addition/Subtraction with Quantity: You can add or subtract a Quantity (delta) to/from an absolute value to get a new absolute value.
• Invalid Operation: Adding two absolute temperatures or two absolute timestamps is a type error (e.g., 10C + 20C is undefined).

// Temperature Example
import coulomb.units.temperature.{*, given}
import coulomb.units.syntax.*

val cels1 = 10d.withTemperature[Celsius]
val cels2 = 20d.withTemperature[Celsius]

val dcels = cels2 - cels1 // Yields a Quantity of degrees
cels2 + dcels            // Valid
// cels1 + cels2          // TYPE ERROR

// Time Example
import coulomb.units.time.{*, given}
import coulomb.units.syntax.*

val date1 = 50d.withEpochTime[365 * Day]
val date2 = 51d.withEpochTime[365 * Day]

val dyear = date2 - date1 // Yields a Quantity of time
date2 + dyear             // Valid
// date1 + date2          // TYPE ERROR

The library provides conversions between coulomb time types and java.time types:

• coulomb time units (e.g., Second, Minute, Hour) $\leftrightarrow$ java.time.Duration.
• coulomb absolute time (EpochTime) $\leftrightarrow$ java.time.Instant.

Explicit Conversions

Use .toQuantity[V, U] to convert a java.time object to a coulomb quantity, and .toDuration or .toInstant to convert back.

import java.time.{ Duration, Instant }
import coulomb.units.time.{*, given}

// extension conversion methods
import coulomb.units.javatime.*

val dur = Duration.ofSeconds(70, 400000000)

// explicit conversion from java.time duration to a coulomb quantity
dur.toQuantity[Double, Minute]

// convert back to java.time
dq.toDuration

// the day of the first human moon landing
val ins = Instant.parse("1969-07-20T00:00:00Z")

// days relative to standard Unix epoch
ins.toEpochTime[Double, Day]

// convert back to java.time
et.toInstant