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.kilo.to(String))      # 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, the prefixes, 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)        # => "5000.0 m"
5000.meter.kilo.to(String)   # => "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)   # => "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)   # => "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)   # => "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)   # => "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)   # => "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)                  # => "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)   # => "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)   # => "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)   # => "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)   # => "470.0 Ω"

coulomb

coulomb(value: Number) -> Measure

value coulombs, as a Measure.

Parameters
value
the quantity

Returns the charge

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

to

to(measure: Measure, _, in: SIPrefix) -> String

Renders a measure as its value followed by its unit symbol.

Parameters
String
the target type

Returns the rendered measure

Examples
5000.meter.to(String)   # => "5000.0 m"
12.volt.to(String)      # => "12.0 V"

mega

mega(measure: Measure) -> Measure

The same measure, displayed with the mega- prefix.

Parameters
measure
the measure to rescale for display

Returns the same quantity, displayed in mega-units

Examples
5000000.watt.mega.to(String)   # => "5.0 MW"

giga

giga(measure: Measure) -> Measure

The same measure, displayed with the giga- prefix.

Parameters
measure
the measure to rescale for display

Returns the same quantity, displayed in giga-units

milli

milli(measure: Measure) -> Measure

The same measure, displayed with the milli- prefix.

Parameters
measure
the measure to rescale for display

Returns the same quantity, displayed in milli-units

Examples
0.5.watt.milli.to(String)   # => "500.0 mW"

micro

micro(measure: Measure) -> Measure

The same measure, displayed with the micro- prefix.

Parameters
measure
the measure to rescale for display

Returns the same quantity, displayed in micro-units

nano

nano(measure: Measure) -> Measure

The same measure, displayed with the nano- prefix.

Parameters
measure
the measure to rescale for display

Returns the same quantity, displayed in nano-units

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)   # => "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)   # => "6.0 J"
(12.volt * 2.ampere).to(String)      # => "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, for display.

A display prefix carries the unit it will display, for example Kilo(Watt * Hour). Pass one to to(String, in:) to render a measure at that scale.

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.

Prefixes on an existing measure select its display unit.

factor

factor : Float

kind

kind : Atom

symbol

symbol : String

kilo

kilo : Measure

The same measure, displayed with the kilo- prefix.

Returns the same quantity, displayed in kilo-units

Examples
5000.meter.kilo.to(String)   # => "5.0 km"

*

*(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)