Si

The library implements quantities and units which included to basic SI.

The International System of Units, internationally known by the abbreviation SI (from French Système International), is the modern form of the metric system and the world's most widely used system of measurement. Established and maintained by the General Conference on Weights and Measures, it is the only system of measurement with an official status in nearly every country in the world, employed in science, technology, industry, and everyday commerce.

Installation

If available in Hex, the package can be installed by adding si to your list of dependencies in mix.exs:

def deps do
  [
    {:si, "~> 1.0"}
  ]
end

Basic usage

Unit creation

iex(1)> SI.Unit.Kilogram.create(12.3)
%SI.Unit.Kilogram{value: 12.3}

Unit converting

For example if we wanna convert kilograms to grams we can use following code:

iex(1)> kg = SI.Unit.Kilogram.create(12.3)
%SI.Unit.Kilogram{value: 12.3}
iex(1)> SI.Unit.Gram.create(kg)
%SI.Unit.Gram{value: 12300}

Adding custom conversions

By default library provides converting between units in the same quantity. That means, by default we can convert nanogram to kilogram or decagram to gram because they are belongs the same quantity. Converting between different quantities will raise an error.

iex(1)> SI.Unit.Gram.create SI.Unit.Ampere.create(123)
** (Protocol.UndefinedError) protocol SI.Unit.Gram.Converter not implemented for %SI.Unit.Ampere{value: 123.0} of type SI.Unit.Ampere (a struct). This protocol is implemented for the
 following type(s): Float, Integer, SI.Unit.Attogram, SI.Unit.Centigram, SI.Unit.Decagram, SI.Unit.Decigram, SI.Unit.Exagram, SI.Unit.Femtogram, SI.Unit.Gigagram, SI.Unit.Hectogram, 
SI.Unit.Kilogram, SI.Unit.Megagram, SI.Unit.Microgram, SI.Unit.Milligram, SI.Unit.Nanogram, SI.Unit.Petagram, SI.Unit.Picogram, SI.Unit.Teragram
    (si 1.0.0) lib/unit/gram.ex:3: SI.Unit.Gram.Converter.impl_for!/1
    (si 1.0.0) lib/unit/gram.ex:3: SI.Unit.Gram.Converter.create/1
    iex:1: (file)

But you can make your own converting protocol if it necessary.

defimpl SI.Unit.Gram.Converter, for: SI.Unit.Ampere do
  def create(term), do: SI.Unit.Gram.create(term.value * 3)
end

and now new converting is allowed

iex(1)> SI.Unit.Gram.create SI.Unit.Ampere.create(123)
%SI.Unit.Gram{value: 369.0}

Available modules

Basically SI provides 7 quantities and 7 basic units for them.

Quantities and they inits

Basic units

Getting all default available modules

Getting all default quantities

iex(1)> SI.quantities
[
  m: SI.Quantity.Mass,
  n: SI.Quantity.AmountOfSubstance,
  t: SI.Quantity.Time,
  T: SI.Quantity.ThermodynamicTemperature,
  lv: SI.Quantity.LuminousIntensity,
  l: SI.Quantity.Length,
  I: SI.Quantity.ElectricCurrent
]

Getting all default available modules grouped by quantity symbols

iex(1)> SI.units
[
  t: [
    s: SI.Unit.Second,
    Es: SI.Unit.Exasecond,
    Ps: SI.Unit.Petasecond,
    Ts: SI.Unit.Terasecond,
    Gs: SI.Unit.Gigasecond,
    Ms: SI.Unit.Megasecond,
    ks: SI.Unit.Kilosecond,
    hs: SI.Unit.Hectosecond,
    das: SI.Unit.Decasecond,
    ds: SI.Unit.Decisecond,
    cs: SI.Unit.Centisecond,
    ms: SI.Unit.Millisecond,
    us: SI.Unit.Microsecond,
    ns: SI.Unit.Nanosecond,
    ps: SI.Unit.Picosecond,
    fs: SI.Unit.Femtosecond,
    as: SI.Unit.Attosecond
  ],
  T: [
    K: SI.Unit.Kelvin,
    EK: SI.Unit.Exakelvin,
    PK: SI.Unit.Petakelvin,
    TK: SI.Unit.Terakelvin,
    GK: SI.Unit.Gigakelvin,
    MK: SI.Unit.Megakelvin,
    kK: SI.Unit.Kilokelvin,
    hK: SI.Unit.Hectokelvin,
    daK: SI.Unit.Decakelvin,
    dK: SI.Unit.Decikelvin,
    cK: SI.Unit.Centikelvin,
    mK: SI.Unit.Millikelvin,
    uK: SI.Unit.Microkelvin,
    nK: SI.Unit.Nanokelvin,
    pK: SI.Unit.Picokelvin,
    fK: SI.Unit.Femtokelvin,
    aK: SI.Unit.Attokelvin
  ],
  lv: [
    cd: SI.Unit.Candela,
    Ecd: SI.Unit.Exacandela,
    Pcd: SI.Unit.Petacandela,
    Tcd: SI.Unit.Teracandela,
    Gcd: SI.Unit.Gigacandela,
    Mcd: SI.Unit.Megacandela,
    kcd: SI.Unit.Kilocandela,
    hcd: SI.Unit.Hectocandela,
    dacd: SI.Unit.Decacandela,
    dcd: SI.Unit.Decicandela,
    ccd: SI.Unit.Centicandela,
    mcd: SI.Unit.Millicandela,
    ucd: SI.Unit.Microcandela,
    ncd: SI.Unit.Nanocandela,
    pcd: SI.Unit.Picocandela,
    fcd: SI.Unit.Femtocandela,
    acd: SI.Unit.Attocandela
  ],
  l: [
    m: SI.Unit.Meter,
    Em: SI.Unit.Exameter,
    Pm: SI.Unit.Petameter,
    Tm: SI.Unit.Terameter,
    Gm: SI.Unit.Gigameter,
    Mm: SI.Unit.Megameter,
    km: SI.Unit.Kilometer,
    hm: SI.Unit.Hectometer,
    dam: SI.Unit.Decameter,
    dm: SI.Unit.Decimeter,
    cm: SI.Unit.Centimeter,
    mm: SI.Unit.Millimeter,
    um: SI.Unit.Micrometer,
    nm: SI.Unit.Nanometer,
    pm: SI.Unit.Picometer,
    fm: SI.Unit.Femtometer,
    am: SI.Unit.Attometer
  ],
  I: [
    A: SI.Unit.Ampere,
    EA: SI.Unit.Exaampere,
    PA: SI.Unit.Petaampere,
    TA: SI.Unit.Teraampere,
    GA: SI.Unit.Gigaampere,
    MA: SI.Unit.Megaampere,
    kA: SI.Unit.Kiloampere,
    hA: SI.Unit.Hectoampere,
    daA: SI.Unit.Decaampere,
    dA: SI.Unit.Deciampere,
    cA: SI.Unit.Centiampere,
    mA: SI.Unit.Milliampere,
    uA: SI.Unit.Microampere,
    nA: SI.Unit.Nanoampere,
    pA: SI.Unit.Picoampere,
    fA: SI.Unit.Femtoampere,
    aA: SI.Unit.Attoampere
  ],
  n: [
    mol: SI.Unit.Mole,
    Emol: SI.Unit.Examole,
    Pmol: SI.Unit.Petamole,
    Tmol: SI.Unit.Teramole,
    Gmol: SI.Unit.Gigamole,
    Mmol: SI.Unit.Megamole,
    kmol: SI.Unit.Kilomole,
    hmol: SI.Unit.Hectomole,
    damol: SI.Unit.Decamole,
    dmol: SI.Unit.Decimole,
    cmol: SI.Unit.Centimole,
    mmol: SI.Unit.Millimole,
    umol: SI.Unit.Micromole,
    nmol: SI.Unit.Nanomole,
    pmol: SI.Unit.Picomole,
    fmol: SI.Unit.Femtomole,
    amol: SI.Unit.Attomole
  ],
  m: [
    g: SI.Unit.Gram,
    Eg: SI.Unit.Exagram,
    Pg: SI.Unit.Petagram,
    Tg: SI.Unit.Teragram,
    Gg: SI.Unit.Gigagram,
    Mg: SI.Unit.Megagram,
    kg: SI.Unit.Kilogram,
    hg: SI.Unit.Hectogram,
    dag: SI.Unit.Decagram,
    dg: SI.Unit.Decigram,
    cg: SI.Unit.Centigram,
    mg: SI.Unit.Milligram,
    ug: SI.Unit.Microgram,
    ng: SI.Unit.Nanogram,
    pg: SI.Unit.Picogram,
    fg: SI.Unit.Femtogram,
    ag: SI.Unit.Attogram
  ]
]

Prefixes

Every single basic unit by default has "prefixed" definitions.

Example for SI.Unit.Gram

Every "prefixed" unit has been created using multiplier module

Docs

The docs can be found at https://hexdocs.pm/si.

License

The SI is released under the Apache License 2.0 - see the LICENSE file.