kex docs Standard Library

Units.SI

module Units.SI

SI units: metres, grams, watts, volts and the rest, with prefixes and dimensional arithmetic.

Opt-in: nothing here is in scope until using Units.SI.

using Units.SI

main do
  IO.printLine(3.kilowatt.to(String))           # prints: 3.0 kW
  IO.printLine(5000.meter.to(String, in: Kilo(Meter)).or("")) # prints: 5.0 km
  IO.printLine((100.meter / 10.second).to(String)) # prints: 10.0 m/s
end

Every value is a Measure from the prelude, so the arithmetic, conversion and comparison described there apply unchanged. What this module adds is the SI vocabulary (including fused spellings such as kilometer), the prefixes as units of their own (Kilo(Meter), for convertTo and to(String, in:)), and a table of which dimension results from multiplying or dividing two others, so 2.newton * 3.meter answers in joules and 100.meter / 10.second in metres per second.

meter

meter(value: Number) -> Measure

value metres, as a Measure.

Parameters
value
the quantity

Returns the length

Examples
5000.meter.to(String)        # => Just("5000.0 m")
5000.meter.to(String, in: Kilo(Meter))   # => Just("5.0 km")

gram

gram(value: Number) -> Measure

value grams, as a Measure.

Parameters
value
the quantity

Returns the mass

Examples
500.gram.to(String)   # => Just("500.0 g")

kelvin

kelvin(value: Number) -> Measure

value kelvin, as a Measure.

Parameters
value
the quantity

Returns the temperature

Examples
300.kelvin.to(String)   # => Just("300.0 K")

liter

liter(value: Number) -> Measure

value litres, as a Measure.

Parameters
value
the quantity

Returns the volume

Examples
2.liter.to(String)   # => Just("2.0 L")

newton

newton(value: Number) -> Measure

value newtons, as a Measure.

Parameters
value
the quantity

Returns the force

Examples

Force times distance is energy

(2.newton * 3.meter).to(String)   # => Just("6.0 J")

joule

joule(value: Number) -> Measure

value joules, as a Measure.

Parameters
value
the quantity

Returns the energy

Examples
100.joule.to(String)   # => Just("100.0 J")

watt

watt(value: Number) -> Measure

value watts, as a Measure.

Parameters
value
the quantity

Returns the power

Examples
3.kilowatt.to(String)                  # => Just("3.0 kW")
1500.watt.to(String, in: Kilo(Watt))   # => Just("1.5 kW")

Power times time is energy

(3.kilowatt * 2.hour).to(String)   # => Just("21600000.0 J")

volt

volt(value: Number) -> Measure

value volts, as a Measure.

Parameters
value
the quantity

Returns the voltage

Examples
12.volt.to(String)   # => Just("12.0 V")

ampere

ampere(value: Number) -> Measure

value amperes, as a Measure.

Parameters
value
the quantity

Returns the current

Examples

Voltage times current is power

(12.volt * 2.ampere).to(String)   # => Just("24.0 W")

ohm

ohm(value: Number) -> Measure

value ohms, as a Measure.

Parameters
value
the quantity

Returns the resistance

Examples
470.ohm.to(String)   # => Just("470.0 Ω")

coulomb

coulomb(value: Number) -> Measure

value coulombs, as a Measure.

Parameters
value
the quantity

Returns the charge

Examples
3.coulomb.to(String)   # => Just("3.0 C")

per

per(measure: Measure, other: Measure) -> Measure

Divides one measure by another, naming the resulting dimension.

The spelled-out form of /: 100.meter.per(10.second) and 100.meter / 10.second are the same call. Metres over seconds is speed, energy over time is power, force over area is pressure: the dimension table decides, and the symbol follows it.

Parameters
measure
the numerator
other
the denominator

Returns the quotient, in its derived unit

Examples
100.meter.per(10.second).to(String)   # => Just("10.0 m/s")

times

times(measure: Measure, other: Measure) -> Measure

Multiplies one measure by another, naming the resulting dimension.

The spelled-out form of *. Force times distance is energy, voltage times current is power, power times time is energy.

Parameters
measure
the first factor
other
the second factor

Returns the product, in its derived unit

Examples
2.newton.times(3.meter).to(String)   # => Just("6.0 J")
(12.volt * 2.ampere).to(String)      # => Just("24.0 W")

type SIUnit

The SI units this module names.

Each carries its dimension (:length, :mass, :power, …) and its symbol, which is what a Measure built from it displays with.

Variants

  • Meter
  • Gram
  • Kelvin
  • Liter
  • Newton
  • Joule
  • Watt
  • Volt
  • Ampere
  • Ohm
  • Coulomb

Implements Unit.

Functions

factor Unit

factor(_)

kind Unit

kind(_)

symbol Unit

symbol(_)

*

*(_, _) -> UnitDefinition

type SIPrefix

A decimal prefix applied to a unit, which is a unit itself.

Kilo(Meter) is the kilometre and Kilo(Watt * Hour) the kilowatt-hour. Like any other Unit, one can be converted to with convertTo or displayed in with to(String, in:). Writing a measure in one is spelled out instead: 5.kilometer.

5000.meter.convertTo(Kilo(Meter))       # => Ok(5.0 km)
1500.watt.to(String, in: Kilo(Watt))    # => Just("1.5 kW")

Variants

  • Kilo(Unit)
  • Mega(Unit)
  • Giga(Unit)
  • Milli(Unit)
  • Micro(Unit)
  • Nano(Unit)

Implements Unit.

Functions

factor Unit

factor(_)

kind Unit

kind(_)

symbol Unit

symbol(_)

extends UnitDefinition

More functions for UnitDefinition, added by this module.

Implements Unit.

extends Measure

More functions for Measure, added by this module.

Displaying a measure in a prefixed unit: the prelude's to(String, in:), for this module's units.

factor

factor : Float

kind

kind : Atom

symbol

symbol : String

to

to(String: Type, in: SIPrefix, format: NumberFormat) -> String?

Renders the measure in a prefixed unit.

Answers None when the measure and the target unit are of different dimensions: you cannot express watts in metres, and this says so rather than producing a wrong number.

Parameters
String
the target type
in
the prefixed unit to display in

Returns the rendered measure, or None

Examples
5000.meter.to(String, in: Kilo(Meter))   # => Just("5.0 km")
1500.watt.to(String, in: Kilo(Watt))     # => Just("1.5 kW")

A mismatched dimension answers None

1500.watt.to(String, in: Kilo(Meter))   # => None

rescaled

rescaled(factor: Float, kind: Atom, symbol: String) -> Measure?

The measure in a unit of factor, or None across dimensions.

prefixScaled

prefixScaled(factor: Float) -> Number

Divides the canonical value by a prefix factor. The conversion is exact in principle (0.000005 W is 5 μW) but neither the measured value nor the prefix factor is exactly representable in binary, so the quotient lands an ulp or two off (5.000000000000001). Round back to 15 significant digits, comfortably inside a double's ~15.95, so prefixed measures read the way they were written. The result is always a Float; the annotation says Number because Integer / Float infers Integer.

*

*(other: Measure) -> Measure

/

/(other: Measure) -> Measure

product

product(other) -> Measure

quotient

quotient(other) -> Measure

productKind

productKind(left, _)

quotientKind

quotientKind(left, _)

productSymbol

productSymbol(_, left, right)

quotientSymbol

quotientSymbol(_, left, right)