GNU Units

https://www.gnu.org/software/units/manual/html_node/
Admin
GNU Units is a command-line program that converts quantities between various systems of measurement...
Tokens:61,046
Snippets:496
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### Example locale_map.txt entry for United States

Source: https://www.gnu.org/software/units/manual/html_node/Locale.html

Example entry mapping the Windows locale 'English_United States' to the POSIX locale 'en_US'.

```text
English_United States   en_US

```

--------------------------------

### Example output for conformable script

Source: https://www.gnu.org/software/units/manual/html_node/Scripting-with-Units.html

The output generated by running the conformable script against the scale reading.

```text
        3.75g = 0.1205653 apounce
        3.75g = 0.1205653 fineounce
        3.75g = 0.1205653 ozt
        3.75g = 0.1205653 tradewukiyeh
        3.75g = 0.1205653 troyounce
```

--------------------------------

### Displaying alias definition

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example showing how to display the definition of a unit list alias by entering it at the 'You have:' prompt.

```plaintext
You have: dms
        Definition: unit list, deg;arcmin;arcsec
```

--------------------------------

### Conversion using ftin64 and ftin32 aliases

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example conversions using the 'ftin64' and 'ftin32' aliases, demonstrating the use of the underscore to repeat the previous input.

```plaintext
You have: screwgauge(10) + 1|64 in
You want: ftin64
        13.16 * 1|64 in
You have: _
You want: ftin32
        6.58 * 1|32 in
```

--------------------------------

### Example of unit name completion with ESC ?

Source: https://www.gnu.org/software/units/manual/html_node/Readline-Support.html

Shows the output when typing 'metr' and requesting completion with ESC ?. The list displays all units starting with 'metr'.

```text
You have: metr
metre             metriccup         metrichorsepower  metrictenth
metretes          metricfifth       metricounce       metricton
metriccarat       metricgrain       metricquart       metricyarncount
You have: metr

```

--------------------------------

### Run conformable script with grep

Source: https://www.gnu.org/software/units/manual/html_node/Scripting-with-Units.html

Example of using the conformable script to filter results for a specific scale reading.

```bash
$ conformable 3.75g | grep 0.120
```

--------------------------------

### Get inverse of nonlinear unit using tilde notation

Source: https://www.gnu.org/software/units/manual/html_node/Other-Nonlinear-Units.html

Shows how to get the inverse of a nonlinear unit by prefixing with '~'. The example converts a length back to a wire gauge number.

```text
You have: ~wiregauge(0.090742002 inches)
You want:
        Definition: 11

```

--------------------------------

### Using '_' multiple times

Source: https://www.gnu.org/software/units/manual/html_node/Previous-Result.html

Demonstrates that '_' can be used any number of times. The example shows that '_ _' results in the square of the previous result (m^2).

```text
You have: m
You want:
        Definition: 1 m
You have: _ _
You want:
        Definition: 1 m^2

```

--------------------------------

### Interactive session with conformability error

Source: https://www.gnu.org/software/units/manual/html_node/Logging-Calculations.html

Example showing an invalid sum of non-conformable units (using minutes instead of arcminutes) and the corrected conversion. The error is not logged.

```text
You have: 90 deg - (5 deg + 22 min + 9 sec)
                                   ^
Invalid sum or difference of non-conformable units
You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
You want: dms
        84 deg + 37 arcmin + 51 arcsec
You have: _
You want: deg
        * 84.630833
        / 0.011816024
You have:
```

--------------------------------

### Set the format option with set format = %.9g

Source: https://www.gnu.org/software/units/manual/html_node/Setting-Options-Interactively.html

The 'format' option takes a string, which is a printf(3) format specification. The example sets it to '%.9g'.

```text
You have: set format = %.9g
  format = %.9g
```

--------------------------------

### Conversion using time and usvol aliases

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example conversions using the 'time' and 'usvol' aliases, showing the output format for unit list conversions.

```plaintext
You have: anomalisticyear
You want: time
        1 year + 25 min + 3.4653216 sec
You have: 1|6 cup
You want: usvol
        2 tbsp + 2 tsp
```

--------------------------------

### Example unit list with fractions

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

A unit list showing a combination of cups and teaspoons with fractional amounts. This is the input format used at the 'You want:' prompt.

```plaintext
cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
```

--------------------------------

### Using '_' with nonlinear unit 'circlearea'

Source: https://www.gnu.org/software/units/manual/html_node/Previous-Result.html

Demonstrates using '_' with a nonlinear unit. The example calculates the diameter of a pan from a given oil volume and depth, using the 'circlearea' unit to get the radius in meters, then multiplying by 2 to get the diameter in inches.

```text
You have: 1|2 gallon / 2 in
You want: circlearea
        0.10890173 m
You have: 2 _
You want: in
        * 8.5749393
        / 0.1166189

```

--------------------------------

### Calculating shortest day length

Source: https://www.gnu.org/software/units/manual/html_node/Variables-Assigned-at-Run-Time.html

Example calculating the shortest day of the year by updating the _decl variable.

```text
You have: _decl = -23.44 deg
You have: _day
You want: hms
        7 hr + 8 min + 40.981084 sec
```

--------------------------------

### Example of prompt prefix with Gaussian units

Source: https://www.gnu.org/software/units/manual/html_node/Prompt-Prefix.html

Shows the prompt prefix when the Gaussian unit system is selected with --units. The output displays the 'You have:' prompt with the system name prepended, followed by the conversion result for stC.

```text
(Gaussian) You have: stC
           You want:
        Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s

```

--------------------------------

### Calculating SNR with runtime variables

Source: https://www.gnu.org/software/units/manual/html_node/Variables-Assigned-at-Run-Time.html

Example of calculating the signal-to-noise ratio for a helium–neon laser using intermediate runtime variables.

```text
You have: _lambda = 632.8 nm            # laser wavelength
You have: _nu = c / _lambda             # optical frequency
You have: _photon_energy = h * _nu
You have: _power = 550 uW
You have: _photon_count = _power * 500 ns / _photon_energy
You have: _snr = sqrt(_photon_count)
You have: _snr
You want:
        Definition: sqrt(_photon_count) = 29597.922
```

--------------------------------

### Compact output includes zeros

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example showing that zeros are included in the compact output list for unit list conversions.

```plaintext
You have: liter
You want: cup;1|2 cup;1|4 cup;tbsp
4;0;0;3.6280454
```

--------------------------------

### Interactive session for pressure drop conversion

Source: https://www.gnu.org/software/units/manual/html_node/Logging-Calculations.html

Example of an interactive units session for a fluid-flow conversion, showing the input and output. The session is lengthy and suitable for logging to a project file.

```text
# Conversion factor A1 for pressure drop
# dP = A1 rho f L Q^2/d^5
You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
You want: psi
        * 43.533969
        / 0.022970568
```

--------------------------------

### Root functions sqrt and cuberoot

Source: https://www.gnu.org/software/units/manual/html_node/Built_002din-Functions.html

Shows usage of sqrt and cuberoot functions, including a fractional exponent example and an error when the argument does not have the appropriate root. These functions require that the argument have the appropriate root.

```text
You have: sqrt(acre)
You want: feet
        * 208.71074
        / 0.0047913202

You have: (400 W/m^2 / stefanboltzmann)^(1/4)
You have:
        Definition: 289.80882 K

You have: cuberoot(hectare)
                          ^
Unit not a root

```

--------------------------------

### Find paper sizes using --list-units, grep, and more

Source: https://www.gnu.org/software/units/manual/html_node/Finding-Units.html

Use --list-units with grep to find definitions containing 'paper[[:space:]]' and pipe to more for paging. This example shows a list of defined paper sizes.

```shell
units --list-units | grep 'paper[[:space:]]' | more
A0paper                                841 mm 1189 mm
A10paper                               26 mm 37 mm
A1paper                                594 mm 841 mm
A2paper                                420 mm 594 mm
A3paper                                297 mm 420 mm
A4paper                                210 mm 297 mm
A5paper                                148 mm 210 mm
A6paper                                105 mm 148 mm
A7paper                                74 mm 105 mm
A8paper                                52 mm 74 mm
A9paper                                37 mm 52 mm
  .  .  .
```

--------------------------------

### Verbose reciprocal conversions (tex to typp and mph to sec/mile)

Source: https://www.gnu.org/software/units/manual/html_node/Interactive-Use.html

Shows two verbose reciprocal conversion examples, demonstrating the output format with the reciprocal conversion note.

```text
You have: tex
You want: typp
        reciprocal conversion
        1 / tex = 496.05465 typp
        1 / tex = (1 / 0.0020159069) typp

You have: 20 mph
You want: sec/mile
        reciprocal conversion
        1 / 20 mph = 180 sec/mile
        1 / 20 mph = (1 / 0.0055555556) sec/mile

```

--------------------------------

### Log file content for angle conversion

Source: https://www.gnu.org/software/units/manual/html_node/Logging-Calculations.html

The log file content for the angle conversion example. It shows the corrected conversion and the expansion of the unit list alias.

```text
From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
To:   deg;arcmin;arcsec
        84 deg + 37 arcmin + 51 arcsec
From: _
To:   deg
        * 84.630833
        / 0.011816024
```

--------------------------------

### Using '_' to convert the same input to different units

Source: https://www.gnu.org/software/units/manual/html_node/Previous-Result.html

Shows how to use the underscore ('_') to reference the previous conversion result, allowing the same input to be converted to multiple units. The example converts 2.3 tonrefrigeration to btu/hr and then to kW.

```text
You have: 2.3 tonrefrigeration
You want: btu/hr
        * 27600
        / 3.6231884e-005
You have: _
You want: kW
        * 8.0887615
        / 0.12362832

```

--------------------------------

### Compact output for unit list conversion

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example showing the compact output format (--compact, --terse, or -t) for a unit list conversion, with semicolon-separated conversion factors.

```plaintext
You have: year
You want: day;min;sec
365;348;45.974678
```

--------------------------------

### units --terse mile m

Source: https://www.gnu.org/software/units/manual/html_node/Invoking-Units.html

Command-line example showing the output of the `--terse` option when converting miles to meters. The output is a single conversion factor without clutter, suitable for parsing by another program.

```shell
units --terse mile m
```

--------------------------------

### units startup prompt

Source: https://www.gnu.org/software/units/manual/html_node/Interactive-Use.html

Shows the initial output when invoking units interactively, including the currency exchange rate notice and the 'You have:' prompt.

```text
Currency exchange rates from FloatRates (USD base) on 2023-07-08
3612 units, 109 prefixes, 122 nonlinear units

You have:

```

--------------------------------

### Conversion with prompts (grains to pounds)

Source: https://www.gnu.org/software/units/manual/html_node/Interactive-Use.html

Shows the full interactive session for converting grains to pounds, including the 'You have:' and 'You want:' prompts and the output.

```text
You have: grains
You want: pounds
        * 0.00014285714
        / 7000

```

--------------------------------

### Assigning a runtime variable

Source: https://www.gnu.org/software/units/manual/html_node/Variables-Assigned-at-Run-Time.html

Syntax for assigning a unit expression to a variable name starting with an underscore.

```text
_name = <unit expression>
```

--------------------------------

### Unit lists for angles and time

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Examples of converting angles and time to sums of units using unit lists.

```text
You have: 23.437754 deg
You want: deg;arcmin;arcsec
    23 deg + 26 arcmin + 15.9144 arcsec

```

```text
You have: 7.2319 hr
You want: hr;min;sec
    7 hr + 13 min + 54.84 sec

```

--------------------------------

### Unit definition (jansky)

Source: https://www.gnu.org/software/units/manual/html_node/Interactive-Use.html

Shows the output when pressing Enter at the 'You want:' prompt to get the definition of a unit.

```text
You have: jansky
You want:
        Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2

```

--------------------------------

### Calculating longest day length

Source: https://www.gnu.org/software/units/manual/html_node/Variables-Assigned-at-Run-Time.html

Example calculating the longest day of the year at 55 degrees latitude using runtime variables.

```text
You have: _alt = -50 arcmin
You have: _lat = 55 deg
You have: _decl = 23.44 deg
You have: _num = sin(_alt) - sin(_lat) sin(_decl)
You have: _denom = cos(_lat) cos(_decl)
You have: _sday = 2 (acos(_num / _denom) / circle) 24 hr
You have: _day = _sday siderealday / day
You have: _day
You want: hms
        17 hr + 19 min + 34.895151 sec
```

--------------------------------

### cpi(1975.5) example

Source: https://www.gnu.org/software/units/manual/html_node/US-Consumer-Price-Index.html

Shows the CPI for mid-1975, which is 53.6. The decimal year 1975.5 corresponds to approximately 1 July 1975.

```units
You have: cpi(1975.5)
You want:
        Definition: 53.6

```

--------------------------------

### Volume conversion using numeric factors

Source: https://www.gnu.org/software/units/manual/html_node/Numbers-as-Units.html

Shows how to compute the volume of a box (2 ft by 3 ft by 12 ft) in steres using the units command. The output displays the conversion factor and its reciprocal.

```text
You have: 2 ft 3 ft 12 ft
You want: stere
        * 2.038813
        / 0.49048148

```

--------------------------------

### hypot function example

Source: https://www.gnu.org/software/units/manual/html_node/Multivariate-Functions.html

Computes the length of a hypotenuse given two sides with compatible dimensions. The result is displayed as a definition in the same units as the input.

```units
You have: hypot(3 m, 4 m)
You want: 
        Definition: 5 m

```

--------------------------------

### Query current option values with set u and set d

Source: https://www.gnu.org/software/units/manual/html_node/Setting-Options-Interactively.html

Typing 'set' followed by an option name displays the current value of that option. The example shows querying 'u' (unitlists) and 'd' (digits). For 'digits', the 'format' value is also shown.

```text
You have: set u
  unitlists = yes
You have: set d
  digits = 8
  format = %.8g
```

--------------------------------

### Include a supplemental units data file with !include

Source: https://www.gnu.org/software/units/manual/html_node/Units-Data-Files.html

Use the !include command in the standard units data file to add a site-wide supplemental data file. Later definitions replace earlier ones, so included definitions override those before the !include statement. Run 'units -c' after changes to check for unintended redefinitions.

```plaintext
!include    /usr/local/share/units/local.units

```

--------------------------------

### Defining a localized unit with !locale and !endlocale

Source: https://www.gnu.org/software/units/manual/html_node/Locale.html

Example of a localized unit definition block for the British gallon, using !locale en_GB and !endlocale directives.

```text
!locale en_GB
gallon       4.54609 liter
!endlocale

```

--------------------------------

### Convert to a sum of units (non-list syntax)

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Demonstrates that using a sum of units at the 'You want:' prompt converts to that specific sum, not to the individual units. The result is equivalent to converting to 1.09375 ft.

```text
You have: 12.28125 ft
You want: ft + in + 1|8 in
        * 11.228571
        / 0.089058524

```

```text
You have: 12.28125 ft
You want: 1.09375 ft
        * 11.228571
        / 0.089058524

```

--------------------------------

### Display all interactive options with set

Source: https://www.gnu.org/software/units/manual/html_node/Setting-Options-Interactively.html

Typing 'set' displays a list of all options that can be set interactively, with current and possible values. Options set to non-default values are marked with an asterisk. The output shows the available options and their current values.

```text
You have: set
  q[uiet] = no         (y|n) do/don't suppress prompting
  o[neline] = no       (y|n) do/don't suppress the second line of output
  st[rict] = no        (y|n) do/don't suppress reciprocal unit conversion
                             (e.g. Hz<->s)
  t[erse] = no         (y|n) do/don't give very terse output
  c[ompact] = no       (y|n) do/don't suppress printing tab, SETFLAG, and '/'
                             characters in results
  v[erbose] = 1        (0|1|2) amount of information shown
 *d[igits] = 9         number of significant digits in output
  e[xponential] = no   (y|n) do/don't use exponential ("scientific") notation
 *f[ormat] = %.9g      printf(3) format specification
  u[nitlists] = yes    (y|n) do/don't allow conversion to unit lists
  r[ound] = no         (y|n) do/don't round last element of unit list output
                             to an integer
  sh[owfactor] = no    (y|n) do/don't show non-unity factor before 1|x
                             in multi-unit output
```

--------------------------------

### Sample units data file with basic definitions

Source: https://www.gnu.org/software/units/manual/html_node/Defining-New-Units.html

A short data file defining primitive units, a prefix, derived units, and a corrected redefinition. Note the use of '!' for primitive units, '!dimensionless' for dimensionless units, and the '+' prefix to suppress redefinition warnings. The file also demonstrates comments and the incorrect definition of inch that is later corrected.

```units
m       !               # The meter is a primitive unit
sec     !               # The second is a primitive unit
rad     !dimensionless  # A dimensionless primitive unit
micro-  1e-6            # Define a prefix
minute  60 sec          # A minute is 60 seconds
hour    60 min          # An hour is 60 minutes
inch    72 m            # Inch defined incorrectly terms of meters
ft      12 inches       # The foot defined in terms of inches
mile    5280 ft         # And the mile
+inch   0.0254 m        # Correct redefinition, warning suppressed

```

--------------------------------

### Non-monotonic piecewise linear unit definition

Source: https://www.gnu.org/software/units/manual/html_node/Piecewise-Linear-Units.html

Example of a piecewise linear unit definition that is non-monotonic in the vicinity of 800 grit. The ellipsis indicates omitted points.

```units
ansicoated[micron] \
     . . .
    600 10.55 \
    800 11.5 \
    1000 9.5 \
```

--------------------------------

### Divide units with slash or per

Source: https://www.gnu.org/software/units/manual/html_node/Operators.html

Shows how to divide units using the slash operator or the 'per' keyword.

```text
You have: furlongs per fortnight
You want: m/s
        * 0.00016630986
        / 6012.8727
```

--------------------------------

### Define a piecewise linear unit with continuation characters

Source: https://www.gnu.org/software/units/manual/html_node/Piecewise-Linear-Units.html

Same definition as the previous example but written with continuation characters for readability. The backslash at the end of each line continues the definition.

```units
zincgauge[in] \
     1 0.002  \
    10 0.02   \
    15 0.04   \
    19 0.06   \
    23 0.1
```

--------------------------------

### Unit list for calibration weights

Source: https://www.gnu.org/software/units/manual/html_node/Unit-Lists.html

Example of using a unit list to check a postal scale's accuracy at 1 oz using metric calibration weights.

```text
You have: 1 oz
You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
        20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g

```

--------------------------------

### One-line output with --one-line

Source: https://www.gnu.org/software/units/manual/html_node/Output-Styles.html

Shows the --one-line option, which displays a single line for forward conversions. Note that reciprocal conversions and conformability errors still produce multi-line output.

```shell
$ units --one-line 23ft m
        * 7.0104

```

```shell
$ units --one-line 23ft 1/m
        reciprocal conversion
        * 0.14264521

```

```shell
$ units --one-line 23ft kg
conformability error
        7.0104 m
        1 kg

```

--------------------------------

### Set a boolean option with set quiet = y

Source: https://www.gnu.org/software/units/manual/html_node/Setting-Options-Interactively.html

Boolean options are enabled with 'yes' (or 'y') and disabled with 'no' (or 'n'). The example sets the 'quiet' option to yes, and the program confirms the change.

```text
You have: set quiet = y
  quiet = yes
```
Tokens:
Raw