Search documentation of Localize

# Unit Formatting Cheatsheet

Copy Markdown View Source

## Creating units

    {:ok, unit} = Localize.Unit.new(42, "meter")
    unit = Localize.Unit.new!(42, "meter")          # bang variant

    {:ok, unit} = Localize.Unit.new(3.14, "kilogram")
    {:ok, unit} = Localize.Unit.new(Decimal.new("99.99"), "liter")
    {:ok, unit} = Localize.Unit.new("meter")         # no value (for display names)

## Unit naming

### Simple units

    meter, kilometer, foot, mile, inch, yard
    kilogram, gram, pound, ounce, stone
    second, minute, hour, day, week, month, year
    celsius, fahrenheit, kelvin
    liter, milliliter, gallon, cup, pint

### SI prefixes

    Localize.Unit.new!(1, "kilometer")      # kilo-
    Localize.Unit.new!(1, "centimeter")     # centi-
    Localize.Unit.new!(1, "millisecond")    # milli-
    Localize.Unit.new!(1, "megawatt")       # mega-

### Powers

    Localize.Unit.new!(100, "square-meter")
    Localize.Unit.new!(5, "cubic-meter")

### Compound units (per-expressions)

    Localize.Unit.new!(60, "mile-per-hour")
    Localize.Unit.new!(1000, "kilogram-per-cubic-meter")

## Formatting

### Format styles

Style | Example (42 meters, `:en`) | Example (100 km, `:de`)
--- | --- | ---
`:long` (default) | `"42 meters"` | `"100 Kilometer"`
`:short` | `"42 m"` | `"100 km"`
`:narrow` | `"42m"` | `"100 km"`

    unit = Localize.Unit.new!(42, "meter")
    Localize.Unit.to_string(unit, format: :long)    #=> {:ok, "42 meters"}
    Localize.Unit.to_string(unit, format: :short)   #=> {:ok, "42 m"}
    Localize.Unit.to_string(unit, format: :narrow)  #=> {:ok, "42m"}

### Locale-specific output

    unit = Localize.Unit.new!(2.5, "kilogram")
    Localize.Unit.to_string(unit, locale: :en)   #=> {:ok, "2.5 kilograms"}
    Localize.Unit.to_string(unit, locale: :de)   #=> {:ok, "2,5 Kilogramm"}
    Localize.Unit.to_string(unit, locale: :fr)   #=> {:ok, "2,5 kilogrammes"}

### Plural-aware patterns

    Localize.Unit.to_string(Localize.Unit.new!(1, "kilometer"))
    #=> {:ok, "1 kilometer"}

    Localize.Unit.to_string(Localize.Unit.new!(5.5, "kilometer"))
    #=> {:ok, "5.5 kilometers"}

### Compound unit formatting

    speed = Localize.Unit.new!(60, "mile-per-hour")
    Localize.Unit.to_string(speed)                   #=> {:ok, "60 miles per hour"}
    Localize.Unit.to_string(speed, format: :short)   #=> {:ok, "60 mph"}

    density = Localize.Unit.new!(1000, "kilogram-per-cubic-meter")
    Localize.Unit.to_string(density, format: :short) #=> {:ok, "1,000 kg/m³"}

## Conversion

    {:ok, km} = Localize.Unit.new(1, "kilometer")
    {:ok, m} = Localize.Unit.convert(km, "meter")
    m.value  #=> 1000.0

    {:ok, c} = Localize.Unit.new(100, "celsius")
    {:ok, f} = Localize.Unit.convert(c, "fahrenheit")
    Float.round(f.value, 1)  #=> 212.0

    {:ok, mph} = Localize.Unit.new(60, "mile-per-hour")
    {:ok, mps} = Localize.Unit.convert(mph, "meter-per-second")
    Float.round(mps.value, 2)  #=> 26.82

### Measurement system conversion

    {:ok, meters} = Localize.Unit.new(1000, "meter")
    {:ok, result} = Localize.Unit.convert_measurement_system(meters, :us)
    result.name  #=> "mile"

System | Region | Example preferences
--- | --- | ---
`:metric` | International | kilometer, kilogram, celsius
`:us` | United States | mile, pound, fahrenheit
`:uk` | United Kingdom | mile, stone, celsius

## Arithmetic

### Addition and subtraction

    a = Localize.Unit.new!(1, "kilometer")
    b = Localize.Unit.new!(500, "meter")
    {:ok, sum} = Localize.Unit.Math.add(a, b)
    {sum.name, sum.value}  #=> {"kilometer", 1.5}

### Multiplication

    # Scalar
    u = Localize.Unit.new!(5, "meter")
    {:ok, result} = Localize.Unit.Math.mult(u, 3)
    result.value  #=> 15

    # Different dimensions produce a compound unit
    m = Localize.Unit.new!(2, "meter")
    s = Localize.Unit.new!(3, "second")
    {:ok, compound} = Localize.Unit.Math.mult(m, s)
    compound.name  #=> "meter-second"

    # Same dimension: operand 2 is aligned to operand 1, then squared
    a = Localize.Unit.new!(2, "millimeter")
    b = Localize.Unit.new!(3, "meter")
    {:ok, area} = Localize.Unit.Math.mult(a, b)
    area.name   #=> "square-millimeter"
    area.value  #=> 6000.0

### Division

    # Different dimensions produce a per-expression
    distance = Localize.Unit.new!(100, "meter")
    time = Localize.Unit.new!(10, "second")
    {:ok, speed} = Localize.Unit.Math.div(distance, time)
    speed.name   #=> "meter-per-second"
    speed.value  #=> 10.0

    # Same dimension: cancels to a bare dimensionless scalar
    km = Localize.Unit.new!(10, "kilometer")
    m = Localize.Unit.new!(2, "meter")
    {:ok, ratio} = Localize.Unit.Math.div(km, m)
    ratio  #=> 5000.0

### Negation and inversion

    u = Localize.Unit.new!(5, "meter")
    {:ok, neg} = Localize.Unit.Math.negate(u)
    neg.value  #=> -5

    speed = Localize.Unit.new!(4, "meter-per-second")
    {:ok, inv} = Localize.Unit.Math.invert(speed)
    inv.name   #=> "second-per-meter"
    inv.value  #=> 0.25

## Operator syntax

`use Localize.Unit.Operators` overrides `+`, `-`, `*`, `/` for units within the calling module:

    defmodule MyApp.Example do
      use Localize.Unit.Operators

      def run do
        km = Localize.Unit.new!(1, "kilometer")
        m  = Localize.Unit.new!(500, "meter")

        km + m       #=> %Unit{value: 1.5, name: "kilometer"}
        km - m       #=> %Unit{value: 0.5, name: "kilometer"}
        km * 3       #=> %Unit{value: 3, name: "kilometer"}
        3 * km       #=> %Unit{value: 3, name: "kilometer"}
        km / 2       #=> %Unit{value: 0.5, name: "kilometer"}

        dist = Localize.Unit.new!(100, "meter")
        time = Localize.Unit.new!(10, "second")
        dist / time  #=> %Unit{value: 10.0, name: "meter-per-second"}

        # Standard operators still work
        2 + 3        #=> 5
      end
    end

## Common options

Option | Values | Default
--- | --- | ---
`:locale` | atom, string, `LanguageTag` | `Localize.get_locale()`
`:format` | `:long`, `:short`, `:narrow` | `:long`

## Unit categories

Category | Example units
--- | ---
Length | meter, kilometer, foot, mile, inch, yard
Mass | kilogram, gram, pound, ounce, stone
Duration | second, minute, hour, day, week, month, year
Temperature | celsius, fahrenheit, kelvin
Area | square-meter, hectare, acre
Volume | liter, milliliter, cubic-meter, gallon, cup
Speed | meter-per-second, kilometer-per-hour, mile-per-hour
Energy | joule, kilowatt-hour
Power | watt, kilowatt, megawatt
Pressure | pascal, bar, atmosphere
Frequency | hertz, kilohertz, megahertz

← Previous Page Number Formatting & Parsing Cheatsheet