coulomb-units

The coulomb-units package defines several groups of commonly used units.

Quick Start

documentation

API documentation for coulomb-units can be viewed here.

packages

Include coulomb-units with your Scala project:

libraryDependencies += "com.manyangled" %% "coulomb-core" % "0.8.0"
libraryDependencies += "com.manyangled" %% "coulomb-units" % "0.8.0"

import

In order to use a unit definition, both the unit type and its corresponding context variable (aka "given") must be in scope. In Scala 3 one does this with the following idiom:

// import both types and context variables ("givens")
import coulomb.units.mksa.{*, given}
import coulomb.units.us.{*, given}
import coulomb.units.accepted.{*, given}

examples

// Working with units of power
val watts = 1d.withUnit[Watt]
// watts: Quantity[Double, Watt] = 1.0

// watts are equivalent to volt-amps
watts.toUnit[Volt * Ampere]
// res0: Quantity[Double, *[Volt, Ampere]] = 1.0

// convert watts to horsepower
watts.toUnit[Horsepower]
// res1: Quantity[Double, Horsepower] = 0.0013410220895950279

// Working with units of volume
val volume = 1d.withUnit[Meter ^ 3]
// volume: Quantity[Double, ^[Meter, 3]] = 1.0

// common metric unit of volume
volume.toUnit[Liter]
// res2: Quantity[Double, Liter] = 1000.0

// United States Gallons
volume.toUnit[Gallon]
// res3: Quantity[Double, Gallon] = 264.1720523581484

// Traditional hydrological units
volume.toUnit[Acre * Foot]
// res4: Quantity[Double, *[Acre, Foot]] = 8.107131937899125E-4

physical constants

Physical constants are closely related to units, in that any physical constant can also be thought of (and used) as a unit in and of itself.

For example, the speed of light (in a vacuum) is a physical constant whose value is close to 300 million meters per second, but we also use this constant as a unit, for example physicists may say that an object traveling at 30 million m/s has a velocity of "0.1c"

The coulomb-units package provides a selection of physical constants, and allows the user to work with these as either units or constant values:

import coulomb.units.constants.{*, given}

// the "constant" function gives a physical constant as a Quantity object with a particular value type
val c = constant[Double, SpeedOfLight]
// c: Quantity[Double, /[Meter, Second]] = 2.99792458E8

// use the speed of light as a unit to express a velocity as a fraction of light speed
val v = 30e6.withUnit[Meter / Second]
// v: Quantity[Double, /[Meter, Second]] = 3.0E7
v.toUnit[SpeedOfLight]
// res5: Quantity[Double, SpeedOfLight] = 0.10006922855944561

java.time conversions

In coulomb-units, standard Quantity of time units such as Second, Minute or Hour corresponds to Duration in java.time. Similarly, absolute time instants represented by EpochTime correspond to Instant in java.time.

The coulomb-units package implements both explicit and implicit conversions between coulomb and java.time values, some of which are shown here:

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

// explicit conversion methods
import coulomb.units.javatime.*
// implicit and explicit conversions
import coulomb.units.javatime.conversions.all.given

val dur = Duration.ofSeconds(70, 400000000)
// dur: Duration = PT1M10.4S

// explicit conversion from java.time duration to a coulomb quantity
dur.toQuantity[Double, Minute]
// res6: Quantity[Double, Minute] = 1.1733333333333333

// corresponding implicit conversion
val dq: Quantity[Double, Minute] = dur
// dq: Quantity[Double, Minute] = 1.1733333333333333

// convert back to java.time
dq.toDuration
// res7: Duration = PT1M10.399999999S

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

// days relative to standard Unix epoch
ins.toEpochTime[Double, Day]
// res8: DeltaQuantity[Double, Day, Second] = -165.0

// corresponding implicit conversion
val et: EpochTime[Double, Day] = ins
// et: DeltaQuantity[Double, Day, Second] = -165.0

// convert back to java.time
et.toInstant
// res9: Instant = 1969-07-20T00:00:00Z