units

stable

Unit conversion plugin covering length, mass, temperature, time, speed, area, volume, pressure, energy, data, and angle units. Supports single and batch conversions with formatting.

use plugin units::{convert, available_units, categories, …}

7 functions Math

/ filter jk navigate Esc clear

Functions (7)

convert Convert a value between two units
available_units List all unit symbols, optionally by category
categories List all available unit categories
unit_info Get name, category, and symbol for a unit
format Format a numeric value with its unit symbol
convert_many Convert a value into multiple target units at once
is_compatible Check if two units can be converted between

Overview

units is a stateless conversion toolkit that turns a numeric value plus two unit symbols into a converted value, with no handles or objects to manage — every call takes plain numbers and short symbol strings (e.g. "km", "ft", "c", "kwh") and returns a result immediately. Units are grouped into eleven categories (length, mass, temperature, time, speed, area, volume, pressure, energy, data, and angle), and a conversion only succeeds when both units share a category; mixing across categories is an error.

The mental model is symbol-driven: discover what is available with categories and available_units, inspect a single symbol with unit_info, check two symbols agree with is_compatible, then convert with convert (one target), convert_many (several targets at once), or render the result for display with format. Temperatures (c, f, k) are handled with their proper offsets rather than simple ratios.

Common patterns

Convert a value and render it with a fixed number of decimals:

use plugin units::{convert, format}

let km = convert(26.2, "mi", "km")
print("marathon: {format(km, "km", 1)}")

Guard a conversion with is_compatible before calling convert:

use plugin units::{is_compatible, convert}

let from = "kb"
let to = "mb"
if is_compatible(from, to) {
  print("{convert(2048.0, from, to)} {to}")
} else {
  print("{from} and {to} are not the same kind of unit")
}

Fan a single measurement out to several units in one call:

use plugin units::{convert_many}

let sizes = convert_many(1.0, "km", ["m", "ft", "mi"])
print("1 km = {sizes["m"]} m = {sizes["ft"]} ft = {sizes["mi"]} mi")

convert(value, from_unit, to_unit) → float

Convert a value between two units

Converts value from from_unit to to_unit. Both units must belong to the same category. Use the unit symbol (e.g. "km", "ft", "c", "kwh"). Temperatures (c, f, k) are handled correctly.

use plugin units::{convert}

let meters = convert(5.0, "km", "m")
print(meters)

let fahrenheit = convert(100.0, "c", "f")
print(fahrenheit)

let mb = convert(2048.0, "kb", "mb")
print(mb)

Conversions span every category, including speed and angle — just keep both symbols in the same family:

use plugin units::{convert}

print(convert(100.0, "km_h", "mph"))
print(convert(180.0, "deg", "rad"))
print(convert(1.0, "h", "s"))

available_units(category?) → table

List all unit symbols, optionally by category

Returns a table of unit symbols. Pass a category name (e.g. "length", "mass", "temperature") to filter, or call with no argument to list all units.

use plugin units::{available_units}

let length_units = available_units("length")
let all_units = available_units()

The returned table is array-style (1-indexed), so you can iterate the symbols of a category:

use plugin units::{available_units}

for sym in available_units("data") {
  print(sym)
}

categories() → table

List all available unit categories

Returns a list of all available unit category names: length, mass, temperature, time, speed, area, volume, pressure, energy, data, angle.

use plugin units::{categories}

let cats = categories()
print(cats[1])

unit_info(unit) → table

Get name, category, and symbol for a unit

Returns a table with name, category, and symbol for the given unit symbol.

use plugin units::{unit_info}

let info = unit_info("km")
print(info["name"])
print(info["category"])

format(value, unit, decimals?) → string

Format a numeric value with its unit symbol

Formats a number with its unit symbol. decimals controls decimal places (default 2).

use plugin units::{convert, format}

let dist = convert(26.2, "mi", "km")
print(format(dist, "km", 1))

print(format(100.0, "c", 0))

convert_many(value, from_unit, targets) → table

Convert a value into multiple target units at once

Converts a single value from from_unit into multiple target units at once. Returns a table mapping each target symbol to the converted value.

use plugin units::{convert_many}

let results = convert_many(1.0, "km", ["m", "mi", "ft"])
print(results["m"])
print(results["mi"])

Because the result is keyed by target symbol, it is handy for building a small comparison table from one source value:

use plugin units::{convert_many, format}

let temps = convert_many(100.0, "c", ["f", "k"])
print("100 C = {format(temps["f"], "f", 1)} = {format(temps["k"], "k", 2)}")

is_compatible(unit_a, unit_b) → bool

Check if two units can be converted between

Returns true if the two unit symbols belong to the same category and can therefore be converted between each other.

use plugin units::{is_compatible}

print(is_compatible("km", "mi"))
print(is_compatible("km", "kg"))

View source code