$ dimvexa convert 1 ton kg --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"ambiguous_symbol","message":"'ton' is ambiguous: use ton_short or ton_long or tonne, or load a config that resolves it","candidates":["ton_short","ton_long","tonne"],"suggestions":["ton_short","ton_long","tonne"]}}
--- stderr
$ dimvexa convert 1 gal L
[exit 1]
--- stdout
--- stderr
error[ambiguous_symbol]: 'gal' is ambiguous: use gal_us or gal_imp, or load a config that resolves it
$ dimvexa convert 1 kcal J --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"ambiguous_symbol","message":"'kcal' is ambiguous: use kcal_th or kcal_IT, or load a config that resolves it","candidates":["kcal_th","kcal_IT"],"suggestions":["kcal_th","kcal_IT"]}}
--- stderr
$ dimvexa convert 1 H s --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"dimension_mismatch","message":"dimension mismatch: [kg m^2 s^-2 A^-2] cannot be converted to [s]"}}
--- stderr
$ dimvexa convert 1 m s --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"dimension_mismatch","message":"dimension mismatch: [m] cannot be converted to [s]"}}
--- stderr
$ dimvexa convert 1 J/mol.K J/mol/K
[exit 1]
--- stdout
--- stderr
error[ambiguous_expression]: ambiguous expression 'J/mol.K': a multiplication after a division (position 5) can be read two ways; write a/(b.c) or (a/b).c
$ dimvexa convert 20 degC delta_degC
[exit 1]
--- stdout
--- stderr
error[kind_mismatch]: kind mismatch in conversion: absolute_temperature and temperature_difference are not compatible (a temperature point and a temperature difference are different kinds; for a difference use delta_degC)
$ dimvexa convert 5 K delta_degF --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"kind_mismatch","message":"kind mismatch in conversion: absolute_temperature and temperature_difference are not compatible (a temperature point and a temperature difference are different kinds; for a difference use delta_K)","suggestions":["delta_K"]}}
--- stderr
$ dimvexa convert 1 degC/s K/s --json
[exit 1]
--- stdout
{"schema":"dimvexa.convert/3","ok":false,"error":{"code":"refused","message":"refused: 'degC' has an offset (temperature scale) and cannot be part of a compound unit; use the difference unit delta_degC for a temperature difference","suggestions":["delta_degC"]}}
--- stderr
$ dimvexa convert 1 ppm 1
[exit 1]
--- stdout
--- stderr
error[ambiguous_symbol]: 'ppm' is ambiguous: use ppmw (planned) or ppmv (planned) or ppmmol (planned), or load a config that resolves it
$ dimvexa convert 1 m
[exit 2]
--- stdout
--- stderr
error[usage]: expected VALUE FROM TO, got 2 argument(s); try 'dimvexa --help'
Usage:
dimvexa convert VALUE FROM TO [--exact] [--json] [--config NAME_OR_PATH]... [--density NAME_OR_VALUE]
dimvexa VALUE FROM TO [--exact] [--json] [--config NAME_OR_PATH]... [--density NAME_OR_VALUE]
dimvexa units [--groups | GROUP | UNIT] [--json] [--config NAME_OR_PATH]...
dimvexa configs [NAME_OR_PATH] [--json]
dimvexa update [--check] [-y]
Converts VALUE from unit FROM to unit TO.
Commands:
units list the supported units grouped by quantity, and the ambiguous symbols
that are refused
units --groups list only the groups (length, mass, volume, ...) with their sizes
units GROUP list one group, for example: dimvexa units volume
units UNIT show the details of one unit, for example: dimvexa units psi
configs list the configs that ship with dimvexa (us, gb, ...)
configs NAME show what one config contains: names, units and densities with their
conditions and sources; a path shows your own file
update replace this binary with the latest GitHub release (needs curl and tar;
checks the published SHA-256 first; see docs/adr/015-update-command.md)
update --check only report whether a newer release exists; exit 0 up to date, 3 newer
release available, 1 error
update -y do not ask "Update to vX.Y.Z? [y/N]" first (also --yes)
Options:
--exact print the exact result and its decimal: a fraction, with pi or a power of ten when
the value has one (`1/2 pi = 1.5707963267948966`); a whole number is printed once
--json machine-readable output (schema dimvexa.convert/3; dimvexa.units/4 for units,
dimvexa.configs/1 for configs)
--color WHEN auto (default: a terminal, unless NO_COLOR is set), always (also
CLICOLOR_FORCE=1) or never; JSON is never coloured
--pretty --json, indented for reading (same fields, same order)
--config NAME_OR_PATH (beta) apply a config (repeatable, later ones win; see
docs/adr/014-one-config-mechanism.md). A shipped one is named (us, gb,
metric-trade, year-julian, year-civil, water); a file has a path (./mine.toml,
or anything with a / or ending in .toml). Without --config the names stay strict
--density NAME_OR_VALUE use a density for mass <-> volume: a name from a loaded config, for
example --config water --density water_25C, or your own number, for example
--density 998.2067kg/m3. The assumption is printed with the result
--version print version and data table version
-h, --help print this help
Examples:
dimvexa convert 10 m/s km/h
dimvexa convert 1 psi Pa --exact
dimvexa convert 100 degC degF --json
dimvexa convert 100 degC degF --pretty
dimvexa convert 1 ton kg --config us
dimvexa convert 1 mt kg --config metric-trade
dimvexa convert 1 L kg --config water --density water_25C
dimvexa convert 1 L kg --density 998.2067kg/m3
dimvexa convert 1 bbl_oil L --config oil.toml
Precision: the CLI always uses the exact path, so the number printed is the exact result
rounded once to the nearest f64 (0 ulp). The library's fast f64 path is within 1 ulp (linear
units) or 2 ulp (temperature scales such as degC and degF) of it; see docs/precision.md.
Exit codes: 0 success, 1 conversion refused or invalid input, 2 usage error; `update --check`
also exits 3 when a newer release exists.