units for Tessel

A Tessel library

Engineering units for Tessel apps.

Every unit, prefix and dimension pint knows, plus the ones engineers use that it doesn't: psf, pcf, cfs, gpm, MGD and more. Convert numbers, read what people type, keep quantities whose sums check their dimensions, and switch a whole display from kN-m to kip-ft.

tessel add units

MIT licence · Tessel 0.10 or later · no dependencies

The example converter: 5' 6 1/4" typed in, shown as a length of 1.68275 m, 1682.75 mm, 66.25 in, 5.52083 ft and more, and as 66.25 in in the US kip-in system

What it does

Every picture here is the converter that comes with the library, run by Tessel without a window and saved.

3 kN/m + 200 lbf/ft typed in: a force per length of 5.91878 kN/m, also shown in N/m, N/mm, lbf/ft, klf, lbf/in and kip/in

Reads what people type

Feet and inches, fractions, sums of different units, and plain numbers in the field's own unit. The answer comes in the unit your field is in.

let mm = try units.read("5' 6 1/4\"", unit: "mm")    // 1682.75
let w = try units.read("3 kN/m + 200 lbf/ft", unit: "kN/m")
100 kN·m typed in and the US kip-ft system picked: 73.7562 kip·ft, with the moment also in N·m, kN·mm, lbf·ft and kip·in

Unit systems

Six systems, from SI and kN-mm to US and kip-in, each with a unit for every dimension. Switch one and every value on screen follows. You can make your own.

if let us = units.system("US kip-ft") {
    print(us.showValue(100.0, "kN·m"))      // 73.76 kip·ft
}
68 °F typed in: a temperature of 20 °C, 293.15 K, 68 °F and 527.67 °R

Temperatures and decibels

°C, °F and °R convert with their own zeros, and dB, dBm and Np with their scales. Inside a unit like W/(m·°C), a degree is a difference, as in pint.

units.convert(68.0, from: "°F", to: "°C")      // 20
units.convert(10.0, from: "dBm", to: "mW")     // 10
3 kN typed in and mm asked for: the message reads mm is a length, not a force

Mistakes say what's wrong

Every function that can fail returns a Result with a message to show: an unknown unit, two things that don't add up, a bracket that isn't closed.

units.read("3 kN", unit: "mm")
// fails: mm is a length, not a force

In a program

Keep plain Floats and convert where values come in and go out, or let Quantity values carry their dimension and check every sum.

Numbers and quantities

Conversions give plain numbers. Quantities multiply into new dimensions: a length squared times a load per length is a moment.

import units

fn main() {
    // Plain numbers in, plain numbers out.
    let m = try units.convert(3.0, from: "ft", to: "m")             // 0.9144
    let gamma = try units.convert(120.0, from: "pcf", to: "kN/m³")  // 18.85
    // What people type into a field, in the field's unit.
    let mm = try units.read("5' 6 1/4\"", unit: "mm")               // 1682.75
    // Quantities that check their dimensions.
    let span = try units.quantity(6.0, "m")
    let load = try units.quantity(12.0, "kN/m")
    let moment = span.power(2.0).times(load).scaled(1.0 / 8.0)      // w L² / 8
    print(moment.show("kN·m"))                                      // 54.00 kN·m
    print(units.feetInches(mm, unit: "mm"))                         // 5' 6 1/4"
    if let us = units.system("US kip-ft") {
        print(us.show(moment))                                      // 39.83 kip·ft
    }
}

A number field

read gives the value in the field's unit, or a message to show beside the field. Formatting writes values back neatly.

import units

// What's typed in a number field, applied in the field's unit.
fn apply(_ typed: String, _ fieldUnit: String) -> String {
    match units.read(typed, unit: fieldUnit) {
        .ok(x) -> units.format(x, fieldUnit, decimals: 1)
        .failure(e) -> e.message
    }
}

fn main() {
    print(apply("20 ft", "mm"))                    // 6096.0 mm
    print(apply("6 m + 250", "mm"))                // 6250.0 mm
    print(apply("3 kg", "mm"))                     // mm is a length, not a mass
    print(units.autoPrefix(0.0012, "m"))           // 1.20 mm
    print(units.feetInches(1.0, unit: "m"))        // 3' 3 3/8"
    print(units.dimension("kN/m³").valueOr(""))    // unit_weight
}

Reading what's typed

read(text, unit:) gives the value in the field's unit. A plain number is in that unit, also next to one with a unit.

TypedIn a field inGives
2*3.5 + 1anything8
3 ftmm914.4
5'6", 5' 6", 5 ft 6 inin66
5' 6 1/4"in66.25
1/4 in, 3/8"in0.25, 0.375
1 m + 50mm1050
10 kN / 2 mkN/m5
3 kN/m + 200 lbf/ftkN/m5.919
68 °F, -40 °C°C20, −40
10 dBmmW10
sqrt(16 m²)m4
asin(0.5)deg30
50 %(none)0.5

Units are written with ·, *, ×, a space or /, and powers as ^2, **2, ² or m2: kN·m, m^3/s, kg m**-3, W/(m·K). Functions: sqrt abs round sin cos tan asin acos atan ln log exp and pi; sin, cos and tan of a plain number take degrees, as in CAD programs.

pint's names, and more

The table is made from pint's own definitions, and names are found the way pint finds them: the name as it is, then a prefix and a name (kft, µs, KiB), then the same without an "s" on the end (kips, meters).

units adds
An angle dimensionrpm converts to rad/s and deg/s, but not to Hz: in pint it does, with a hidden 2π. A bit is a dimension too.
Engineering unitspsf ksf tsf pcf kcf pci plf klf cfs cms lps lpm gpm gpd MGD MCM ha_m ac_ft inH2O meter_H2O fpm var ppb dozen, and ' and " for feet and inches. pcf is a unit weight: 120 pcf is 18.85 kN/m³.
pint's names that may surpriseAre
mil1/64,000 of a turn; a thousandth of an inch is thou
C, Fcoulomb and farad; write °C or degC, °F or degF
ton, galthe short ton and the US gallon; t is a tonne
han hour

Checked against pint

A Python program asks pint for the answers to thousands of random cases: names, units written several ways, conversions, typed sums and quantity arithmetic. The library has to agree with every one.

34,431checks in the library's tests, all passing
14,229cases with pint's answers, from 4,179 names to 3,700 conversions
440units in the table, 1,014 names, any SI or binary prefix
15UI checks driving the converter headless

Reference

Units and converting

FunctionGives
convert(x, from:, to:)x in another unit, temperatures and dB included.
factor(from:, to:)What to multiply by (not for °C, °F or dB).
toSI(x, unit), fromSI(v, unit)A value in SI base units, and back.
unit(text), isUnit(text)A Unit (factor, dims, offset, log scale), and whether the text is one.
info(name), allUnits()A table unit's name, symbol, names, factor and dimension; all the names.

Reading and quantities

Function or methodGives
read(text, unit:)What's typed, as a number in the field's unit.
readQuantity(text), quantity(x, unit)A Quantity: a value in SI base units with its dimension.
q.to(unit)The value in a unit that measures the same thing.
q.plus(r), q.minus(r)Sums that check the dimensions agree.
q.times(r), q.over(r), q.scaled(k), q.power(p), q.squareRoot()Products, quotients and powers, in new dimensions.
q.dimension(), q.show(unit, decimals:, sig:, trim:)What it measures, and text like "54.00 kN·m".

Writing values

FunctionGives
format(x, unit, decimals:, sig:, trim:)"12.50 kN·m", or significant figures, or without zeros at the end.
pretty(unit)"kg m**-3" written as "kg·m⁻³".
autoPrefix(x, unit, …)The SI prefix that reads well: 0.0012 m is "1.20 mm".
feetInches(x, unit:, denominator:)5' 6 1/4", to the nearest 1/16 inch; read reads it back.

Dimensions and systems

FunctionGives
dimension(unit), dimensionNames(unit)"unit_weight", "force_per_length", "angular_velocity"; all the names (kN·m is energy, moment, torque).
dimensionOf(name), siUnit(dims), sameDimension(a, b)A dimension's powers, its SI unit ("kg·m⁻¹·s⁻²"), and whether two units convert.
unitsFor(dimension), commonUnits(dimension)Every unit of a dimension, and the usual few for a unit picker.
system(name), systemNames()SI, SI kN-m, SI kN-mm, US, US kip-ft and US kip-in.
s.unitForUnit(unit), s.unitForDimension(name), s.convert(x, from:), s.show(q), s.showValue(x, unit)A system's unit for something, a value in it, and the value as text.

The unit definitions come from pint, under its BSD licence; the library is MIT.