1UNITS(1) General Commands Manual UNITS(1)
2
6 units - unit conversion program
7
9 The `units' program converts quantities expressed in various scales to
10 their equivalents in other scales. The `units' program can handle mul‐
11 tiplicative scale changes as well as nonlinear conversions such as
12 Fahrenheit to Celsius. Temperature conversions require a special syn‐
13 tax. See the examples below.
14 The units are defined in an external data file. You can use the exten‐
16 sive data file that comes with this program, or you can provide your
17 own data file to suit your needs.
18 You can use the program interactively with prompts, or you can use it
20 from the command line.
21
23 To invoke units for interactive use, type `units' at your shell prompt.
24 The program will print something like this:
25 2131 units, 53 prefixes, 24 nonlinear units
27 You have:
29 At the `You have:' prompt, type the quantity and units that you are
31 converting from. For example, if you want to convert ten meters to
32 feet, type `10 meters'. Next, `units' will print `You want:'. You
33 should type the type of units you want to convert to. To convert to
34 feet, you would type `feet'. Note that if the readline library was
35 compiled in then the tab key can be used to complete unit names. See
36 Readline support, for more information about readline.
37 The answer will be displayed in two ways. The first line of output,
39 which is marked with a `*' to indicate multiplication, gives the result
40 of the conversion you have asked for. The second line of output, which
41 is marked with a `/' to indicate division, gives the inverse of the
42 conversion factor. If you convert 10 meters to feet, `units' will
43 print
44 * 32.808399
46 / 0.03048
47 which tells you that 10 meters equals about 32.8 feet. The second num‐
49 ber gives the conversion in the opposite direction. In this case, it
50 tells you that 1 foot is equal to about 0.03 dekameters since the
51 dekameter is 10 meters. It also tells you that 1/32.8 is about .03.
52 The `units' program prints the inverse because sometimes it is a more
54 convenient number. In the example above, for example, the inverse
55 value is an exact conversion: a foot is exactly .03048 dekameters. But
56 the number given the other direction is inexact.
57 If you try to convert grains to pounds, you will see the following:
59 You have: grains
61 You want: pounds
62 * 0.00014285714
63 / 7000
64 From the second line of the output you can immediately see that a grain
66 is equal to a seven thousandth of a pound. This is not so obvious from
67 the first line of the output. If you find the output format confus‐
68 ing, try using the `--verbose' option:
69 You have: grain
71 You want: aeginamina
72 grain = 0.00010416667 aeginamina
73 grain = (1 / 9600) aeginamina
74 If you request a conversion between units which measure reciprocal
76 dimensions, then `units' will display the conversion results with an
77 extra note indicating that reciprocal conversion has been done:
78 You have: 6 ohms
80 You want: siemens
81 reciprocal conversion
82 * 0.16666667
83 / 6
84 Reciprocal conversion can be suppressed by using the `--strict' option.
86 As usual, use the `--verbose' option to get more comprehensible output:
87 You have: tex
89 You want: typp
90 reciprocal conversion
91 1 / tex = 496.05465 typp
92 1 / tex = (1 / 0.0020159069) typp
93 You have: 20 mph
95 You want: sec/mile
96 reciprocal conversion
97 1 / 20 mph = 180 sec/mile
98 1 / 20 mph = (1 / 0.0055555556) sec/mile
99 If you enter incompatible unit types, the `units' program will print a
101 message indicating that the units are not conformable and it will dis‐
102 play the reduced form for each unit:
103 You have: ergs/hour
105 You want: fathoms kg^2 / day
106 conformability error
107 2.7777778e-11 kg m^2 / sec^3
108 2.1166667e-05 kg^2 m / sec
109 If you only want to find the reduced form or definition of a unit, sim‐
111 ply press return at the `You want:' prompt. Here is an example:
112 You have: jansky
114 You want:
115 Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
116 The output from `units' indicates that the jansky is defined to be
118 equal to a fluxunit which in turn is defined to be a certain combina‐
119 tion of watts, meters, and hertz. The fully reduced (and in this case
120 somewhat more cryptic) form appears on the far right.
121 Some named units are treated as dimensionless in some situations.
123 These include the radian and steradian. These units will be treated as
124 equal to 1 in units conversions. Power is equal to torque times angu‐
125 lar velocity. This conversion can only be performed if the radian is
126 dimensionless.
127 You have: (14 ft lbf) (12 radians/sec)
129 You want: watts
130 * 227.77742
131 / 0.0043902509
132 Note that named dimensionaless units are not treated as dimensionless
134 in other contexts. They cannot be used as exponents so for example,
135 `meter^radian' is not allowed.
136 If you want a list of options you can type `?' at the `You want:'
138 prompt. The program will display a list of named units which are con‐
139 formable with the unit that you entered at the `You have:' prompt
140 above. Note that conformable unit combinations will not appear on this
141 list.
142 Typing `help' at either prompt displays a short help message. You can
144 also type `help' followed by a unit name. This will invoke a pager on
145 the units data base at the point where that unit is defined. You can
146 read the definition and comments that may give more details or histori‐
147 cal information about the unit.
148 Typing `search text' will display a list of all of the units whose
150 names contain `text' as a substring along with their definitions. This
151 may help in the case where you aren't sure of the right unit name.
152
154 The `units' program can perform units conversions non-interactively
155 from the command line. To do this, type the command, type the original
156 units expression, and type the new units you want. You will probably
157 need to protect the units expressions from interpretation by the shell
158 using single quote characters.
159 If you type
161 units '2 liters' 'quarts'
163 then `units' will print
165 * 2.1133764
167 / 0.47317647
168 and then exit. The output tells you that 2 liters is about 2.1 quarts,
170 or alternatively that a quart is about 0.47 times 2 liters.
171 If the conversion is successful, then `units' will return success (0)
173 to the calling environment. If `units' is given non-conformable units
174 to convert, it will print a message giving the reduced form of each
175 unit and it will return failure (nonzero) to the calling environment.
176 When `units' is invoked with only one argument, it will print out the
178 definition of the specified unit. It will return failure if the unit
179 is not defined and success if the unit is defined.
180
182 In order to enter more complicated units or fractions, you will need to
183 use operations such as powers, products and division. Powers of units
184 can be specified using the `^' character as shown in the following
185 example, or by simple concatenation: `cm3' is equivalent to `cm^3'. If
186 the exponent is more than one digit, the `^' is required. An exponent
187 like `2^3^2' is evaluated right to left. The `^' operator has the sec‐
188 ond highest precedence. The `**' operator is provided as an alterna‐
189 tive exponent operator.
190 You have: cm^3
192 You want: gallons
193 * 0.00026417205
194 / 3785.4118
195 You have: arabicfoot * arabictradepound * force
197 You want: ft lbf
198 * 0.7296
199 / 1.370614
200 Multiplication of units can be specified by using spaces, or an aster‐
202 isk (`*'). If `units' is invoked with the `--product' option then the
203 hyphen (`-') also acts as a multiplication operator. Division of units
204 is indicated by the slash (`/') or by `per'.
205 You have: furlongs per fortnight
207 You want: m/s
208 * 0.00016630986
209 / 6012.8727
210 Historically, multiplication in units was assigned a higher precedence
212 than division. This disagrees with the usual precedence rules which
213 give multiplication and division equal precedence, and it has been a
214 source of confusion for people who think of units as a calculator.
215 By default, multiplication using the star (`*') now has the same prece‐
217 dence as division and hence follows the usual precedence rules. If
218 units is invoked with the the `--oldstar' option then then the old
219 behavior is activated and `*' will have the same precedence as the
220 other multiplication operators described next.
221 Multiplication using a space or using the hyphen has a higher prece‐
223 dence than division and is evaluated left to right. So @samp{m/s
224 s/day} is equivalent to `m / s s day' and has dimensions of length per
225 time cubed. Similarly, `1/2 meter' refers to a unit of reciprocal
226 length equivalent to .5/meter, which is probably not what you would
227 intend if you entered that expression.
228 You can indicate division of numbers with the vertical dash (`|'), so
230 if you wanted half a meter you could write @samp{1|2 meter}. This
231 operator has the highest precedence so the square root of two thirds
232 could be written `2|3^1|2'.
233 You have: 1|2 inch
235 You want: cm
236 * 1.27
237 / 0.78740157
238 Parentheses can be used for grouping as desired.
240 You have: (1/2) kg / (kg/meter)
242 You want: league
243 * 0.00010356166
244 / 9656.0833
245 Prefixes are defined separately from base units. In order to get cen‐
247 timeters, the units database defines `centi-' and `c-' as prefixes.
248 Prefixes can appear alone with no unit following them. An exponent
249 applies only to the immediately preceding unit and its prefix so that
250 `cm^3' or `centimeter^3' refer to cubic centimeters but `centi*meter^3'
251 refers to hundredths of cubic meters. Only one prefix is permitted per
252 unit, so `micromicrofarad' will fail, but `micro*microfarad' will work,
253 as will `micro microfarad'..
254 For `units', numbers are just another kind of unit. They can appear as
256 many times as you like and in any order in a unit expression. For
257 example, to find the volume of a box which is 2 ft by 3 ft by 12 ft in
258 steres, you could do the following:
259 You have: 2 ft 3 ft 12 ft
261 You want: stere
262 * 2.038813
263 / 0.49048148
264 You have: $ 5 / yard
266 You want: cents / inch
267 * 13.888889
268 / 0.072
269 And the second example shows how the dollar sign in the units conver‐
271 sion can precede the five. Be careful: `units' will interpret `$5'
272 with no space as equivalent to dollars^5.
273 Outside of the SI system, it is often desirable to add values of dif‐
275 ferent units together. You may also wish to use `units' as a calcula‐
276 tor that keeps track of units. Sums of conformable units are written
277 with the `+' character.
278 You have: 2 hours + 23 minutes + 32 seconds
280 You want: seconds
281 * 8612
282 / 0.00011611705
283 You have: 12 ft + 3 in
285 You want: cm
286 * 373.38
287 / 0.0026782366
288 You have: 2 btu + 450 ft lbf
290 You want: btu
291 * 2.5782804
292 / 0.38785542
293 The expressions which are added together must reduce to identical
295 expressions in primitive units, or an error message will be displayed:
296 You have: 12 printerspoint + 4 heredium
298 ^
299 Illegal sum of non-conformable units
300 Historically `-' has been used for products of units, which complicates
302 its iterpretation in `units'. Because `units' provides several other
303 ways to obtain unit products, and because `-' is a subtraction operator
304 in general algebraic expressions, `units' treats the binary `-' as a
305 subtraction operator by default. This behavior can be altered using
306 the `--product' option which causes `units' to treat the binary `-'
307 operator as a product operator. Note that when `-' is a multiplication
308 operator it has the same precedence as `*', but when `-' is a subtrac‐
309 tion operator it has the lower precedence as the addition operator.
310 When `-' is used as a unary operator it negates its operand. Regard‐
312 less of the `units' options, if `-' appears after `(' or after `+' then
313 it will act as a negation operator. So you can always compute 20
314 degrees minus 12 minutes by entering `20 degrees + -12 arcmin'. You
315 must use this construction when you define new units because you cannot
316 know what options will be in force when your definition is processed.
317 The `+' character sometimes appears in exponents like `3.43e+8'. This
319 leads to an ambiguity in an expression like `3e+2 yC'. The unit `e' is
320 a small unit of charge, so this can be regarded as equivalent to
321 `(3e+2) yC' or `(3 e)+(2 yC)'. This ambiguity is resolved by always
322 interpreting `+' as part of an exponent if possible.
323 Several built in functions are provided: `sin', `cos', `tan', `ln',
325 `log', `log2', `exp', `acos', `atan' and `asin'. The `sin', `cos', and
326 `tan' functions require either a dimensionless argument or an argument
327 with dimensions of angle.
328 You have: sin(30 degrees)
330 You want:
331 Definition: 0.5
332 You have: sin(pi/2)
334 You want:
335 Definition: 1
336 You have: sin(3 kg)
338 ^
339 Unit not dimensionless
340 The other functions on the list require dimensionless arguments. The
342 inverse trigonometric functions return arguments with dimensions of
343 angle.
344 If you wish to take roots of units, you may use the `sqrt' or `cube‐
346 root' functions. These functions require that the argument have the
347 appropriate root. Higher roots can be obtained by using fractional
348 exponents:
349 You have: sqrt(acre)
351 You want: feet
352 * 208.71074
353 / 0.0047913202
354 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
356 You have:
357 Definition: 289.80882 K
358 You have: cuberoot(hectare)
360 ^
361 Unit not a root
362 Nonlinear units are represented using functional notation. They make
364 possible nonlinear unit conversions such temperature. This is differ‐
365 ent from the linear units that convert temperature differences. Note
366 the difference below. The absolute temperature conversions are handled
367 by units starting with `temp', and you must use functional notation.
368 The temperature differences are done using units starting with `deg'
369 and they do not require functional notation.
370 You have: tempF(45)
372 You want: tempC
373 7.2222222
374 You have: 45 degF
376 You want: degC
377 * 25
378 / 0.04
379 Think of `tempF(x)' not as a function but as a notation which indicates
381 that `x' should have units of `tempF' attached to it. See Nonlinear
382 units. The first conversion shows that if it's 45 degrees Fahrenheit
383 outside it's 7.2 degrees Celsius. The second conversions indicates
384 that a change of 45 degrees Fahrenheit corresponds to a change of 25
385 degrees Celsius.
386 Some other examples of nonlinears units are ring size and wire gauge.
388 There are numerous different gauges and ring sizes. See the units
389 database for more details. Note that wire gauges with multiple zeroes
390 are signified using negative numbers where two zeroes is -1. Alterna‐
391 tively, you can use the synonyms `g00', `g000', and so on that are
392 defined in the units database.
393 You have: wiregauge(11)
395 You want: inches
396 * 0.090742002
397 / 11.020255
398 You have: brwiregauge(g00)
400 You want: inches
401 * 0.348
402 / 2.8735632
403 You have: 1 mm
405 You want: wiregauge
406 18.201919
407
409 You invoke `units' like this:
410 units [OPTIONS] [FROM-UNIT [TO-UNIT]]
412 If the FROM-UNIT and TO-UNIT are omitted, then the program will use
414 interactive prompts to determine which conversions to perform. See
415 Interactive use. If both FROM-UNIT and TO-UNIT are given, `units' will
416 print the result of that single conversion and then exit. If only
417 FROM-UNIT appears on the command line, `units' will display the defini‐
418 tion of that unit and exit. Units specified on the command line will
419 need to be quoted to protect them from shell interpretation and to
420 group them into two arguments. See Command line use.
421 The following options allow you to read in an alternative units file,
423 check your units file, or change the output format:
424 -c, --check
426 Check that all units and prefixes defined in the units data file
427 reduce to primitive units. Print a list of all units that can‐
428 not be reduced. Also display some other diagnostics about sus‐
429 picious definitions in the units data file. Note that only def‐
430 initions active in the current locale are checked.
431 --check-verbose
433 Like the `-check' option, this option prints a list of units
434 that cannot be reduced. But to help find unit definitions that
435 cause endless loops, it lists the units as they are checked. If
436 `units' hangs, then the last unit to be printed has a bad defi‐
437 nition. Note that only definitions active in the current locale
438 are checked.
439 -o format, --output-format format
441 Use the specified format for numeric output. Format is the same
442 as that for the printf function in the ANSI C standard. For
443 example, if you want more precision you might use `-o %.15g'.
444 -f filename, --file filename
446 Instruct `units' to load the units file `filename'. If `file‐
447 name' is the empty string (`-f "') then the default units file
448 will be loaded. This enables you to load the default file plus
449 a personal units file. Up to 25 units files may be specified on
450 the command line. This option overrides the `UNITSFILE' envi‐
451 ronment variable.
452 -h, --help
454 Print out a summary of the options for `units'.
455 -m, --minus
457 Causes `-' to be interpreted as a subtraction operator. This is
458 usually the default behavior.
459 -p, --product
461 Causes `-' to be interpreted as a multiplication operator when
462 it has two operands. It will as a negation operator when it has
463 only one operand: `(-3)'. Note that by default `-' is treated
464 as a subtraction operator.
465 , --oldstar Causes `*' to have the old style precedence, higher than
467 the precedence of division so that `1/2*3' will equal `6'.
468 , --newstar Forces `*' to have the new (default) precedence which fol‐
470 lows the usual rules of algebra: the precedence of `*' is the same as
471 the precedence of `/', so that `1/2*3' will equal `3/2'.
472 , --compact Give compact output featuring only the conversion factor.
474 This turns off the `--verbose' option.
475 -q, --quiet, --silent
477 Suppress prompting of the user for units and the display of sta‐
478 tistics about the number of units loaded.
479 -s, --strict
481 Suppress conversion of units to their reciprocal units. For
482 example, `units' will normally convert hertz to seconds because
483 these units are reciprocals of each other. The strict option
484 requires that units be strictly conformable to perform a conver‐
485 sion, and will give an error if you attempt to convert hertz to
486 seconds.
487 -1, --one-line
489 Give only one line of output (the forward conversion). Do not
490 print the reverse conversion. Note that if a reciprocal conver‐
491 sion is performed then `units' will print still print the
492 "reciprocal conversion" line.
493 -t, --terse
495 Give terse output when converting units. This option can be
496 used when calling `units' from another program so that the out‐
497 put is easy to parse. This option has the combined effect of
498 these options: `--strict' `--quiet' `--one-line' `--compact'.
499 -v, --verbose
501 Give slightly more verbose output when converting units. When
502 combined with the `-c' option this gives the same effect as
503 `--check-verbose'.
504 -V, --version
506 Print program version number, tell whether the readline library
507 has been included, and give the location of the default units
508 data file.
509
511 The conversion information is read from a units data file which is
512 called `units.dat' and is probably located in the `/usr/local/share'
513 directory. If you invoke `units' with the `-V' option, it will print
514 the location of this file. The default file includes definitions for
515 all familiar units, abbreviations and metric prefixes. It also
516 includes many obscure or archaic units.
517 Many constants of nature are defined, including these:
519 pi ratio of circumference to diameter
521 c speed of light
522 e charge on an electron
523 force acceleration of gravity
524 mole Avogadro's number
525 water pressure per unit height of water
526 Hg pressure per unit height of mercury
527 au astronomical unit
528 k Boltzman's constant
530 mu0 permeability of vacuum
531 epsilon0 permitivity of vacuum
532 G gravitational constant
533 mach speed of sound
534 The database includes atomic masses for all of the elements and numer‐
535 ous other constants. Also included are the densities of various ingre‐
536 dients used in baking so that `2 cups flour_sifted' can be converted to
537 `grams'. This is not an exhaustive list. Consult the units data file
538 to see the complete list, or to see the definitions that are used.
539 The unit `pound' is a unit of mass. To get force, multiply by the
541 force conversion unit `force' or use the shorthand `lbf'. (Note that
542 `g' is already taken as the standard abbreviation for the gram.) The
543 unit `ounce' is also a unit of mass. The fluid ounce is `fluidounce'
544 or `floz'. British capacity units that differ from their US counter‐
545 parts, such as the British Imperial gallon, are prefixed with `br'.
546 Currency is prefixed with its country name: `belgiumfranc', `britain‐
547 pound'.
548 The US Survey foot, yard, and mile can be obtained by using the `US'
550 prefix. These units differ slightly from the international length
551 units. They were in general use until 1959, and are still used for
552 geographic surveys. The acre is officially defined in terms of the US
553 Survey foot. If you want an acre defined according to the interna‐
554 tional foot, use `intacre'. The difference between these units is
555 about 4 parts per million. The British also used a slightly different
556 length measure before 1959. These can be obtained with the prefix
557 `UK'.
558 When searching for a unit, if the specified string does not appear
560 exactly as a unit name, then the `units' program will try to remove a
561 trailing `s' or a trailing `es'. If that fails, `units' will check for
562 a prefix. All of the standard metric prefixes are defined.
563 To find out what units and prefixes are available, read the standard
565 units data file.
566
568 All of the units and prefixes that `units' can convert are defined in
569 the units data file. If you want to add your own units, you can supply
570 your own file. You can also add your own units definitions in the
571 `.units.dat' file in your home directory. If this file exists it is
572 read before the units data file. It will not be read if any units
573 files are specified on the command line.
574 A unit is specified on a single line by giving its name and an equiva‐
576 lence. Comments start with a `#' character, which can appear anywhere
577 in a line. The backslash character (`´) acts as a continuation charac‐
578 ter if it appears as the last character on a line, making it possible
579 to spread definitions out over several lines if desired. A file can be
580 included by giving the command `!include' followed by the file's name.
581 The file will be sought in the same directory as the parent file unless
582 a full path is given.
583 Unit names must not contain any of the operator characters `+', `-',
585 `*', `/', `|', `^' or the parentheses. They cannot begin with a digit
586 or a decimal point (`.'), nor can they end with a digit (except for
587 zero). Be careful to define new units in terms of old ones so that a
588 reduction leads to the primitive units, which are marked with `!' char‐
589 acters. Dimensionless units are indicated by using the string `!dimen‐
590 sionless' for the unit definition.
591 When adding new units, be sure to use the `-c' option to check that the
593 new units reduce properly. If you create a loop in the units defini‐
594 tions, then `units' will hang when invoked with the `-c' options. You
595 will need to use the `--check-verbose' option which prints out each
596 unit as it checks them. The program will still hang, but the last unit
597 printed will be the unit which caused the infinite loop.
598 If you define any units which contain `+' characters, carefully check
600 them because the `-c' option will not catch non-conformable sums. Be
601 careful with the `-' operator as well. When used as a binary operator,
602 the `-' character can perform addition or multiplication depending on
603 the options used to invoke `units'. To ensure consistent behavior use
604 `-' only as a unary negation operator when writing units definitions.
605 To multiply two units leave a space or use the `*' operator with care,
606 recalling that it has two possible precedence values and may require
607 parentheses to ensure consistent behavior. To compute the difference
608 of `foo' and `bar' write `foo+(-bar)' or even `foo+-bar'.
609 Here is an example of a short units file that defines some basic units:
611 m ! # The meter is a primitive unit
613 sec ! # The second is a primitive unit
614 rad !dimensionless # The second is a primitive unit
615 micro- 1e-6 # Define a prefix
616 minute 60 sec # A minute is 60 seconds
617 hour 60 min # An hour is 60 minutes
618 inch 0.0254 m # Inch defined in terms of meters
619 ft 12 inches # The foot defined in terms of inches
620 mile 5280 ft # And the mile
621 A unit which ends with a `-' character is a prefix. If a
623 prefix definition contains any `/' characters, be sure
624 they are protected by parentheses. If you define `half-
625 1/2' then `halfmeter' would be equivalent to `1 / 2
626 meter'.
627
629 Some units conversions of interest are nonlinear; for example, tempera‐
630 ture conversions between the Fahrenheit and Celsius scales cannot be
631 done by simply multiplying by conversions factors.
632 When you give a linear unit definition such as `inch 2.54 cm' you are
634 providing information that `units' uses to convert values in inches
635 into primitive units of meters. For nonlinear units, you give a func‐
636 tional definition that provides the same information.
637 Nonlinear units are represented using a functional notation. It is
639 best to regard this notation not as a function call but as a way of
640 adding units to a number, much the same way that writing a linear unit
641 name after a number adds units to that number. Internally, nonlinear
642 units are defined by a pair of functions which convert to and from lin‐
643 ear units in the data file, so that an eventual conversion to primitive
644 units is possible.
645 Here is an example nonlinear unit definition:
647 tempF(x) [1;K] (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
649 A nonlinear unit definition comprises a unit name, a dummy parameter
651 name, two functions, and two corresponding units. The functions tell
652 `units' how to convert to and from the new unit. In order to produce
653 valid results, the arguments of these functions need to have the cor‐
654 rect dimensions. To facilitate error checking, you may specify the
655 dimensions.
656 The definition begins with the unit name followed immediately (with no
658 spaces) by a `(' character. In parentheses is the name of the parame‐
659 ter. Next is an optional specification of the units required by the
660 functions in this definition. In the example above, the `tempF' func‐
661 tion requires an input argument conformable with `1'. For normal non‐
662 linear units definitions the forward function will always take a dimen‐
663 sionless argument. The inverse function requires an input argument
664 conformable with `K'. In general the inverse function will need units
665 that match the quantity measured by your nonlinear unit. The sole pur‐
666 pose of the expression in brackets to enable `units' to perform error
667 checking on function arguments.
668 Next the function definitions appear. In the example above, the
670 `tempF' function is defined by
671 tempF(x) = (x+(-32)) degF + stdtemp
673 This gives a rule for converting `x' in the units `tempF' to linear
675 units of absolute temperature, which makes it possible to convert from
676 tempF to other units.
677 In order to make conversions to Fahrenheit possible, you must give a
679 rule for the inverse conversions. The inverse will be `x(tempF)' and
680 its definition appears after a `;' character. In our example, the
681 inverse is
682 x(tempF) = (tempF+(-stdtemp))/degF + 32
684 This inverse definition takes an absolute temperature as its argument
686 and converts it to the Fahrenheit temperature. The inverse can be
687 omitted by leaving out the `;' character, but then conversions to the
688 unit will be impossible. If the inverse is omitted then the `--check'
689 option will display a warning. It is up to you to calculate and enter
690 the correct inverse function to obtain proper conversions. The
691 `--check' option tests the inverse at one point and print an error if
692 it is not valid there, but this is not a guarantee that your inverse is
693 correct.
694 If you wish to make synonyms for nonlinear units, you still need to
696 define both the forward and inverse functions. Inverse functions can
697 be obtained using the `~' operator. So to create a synonym for `tempF'
698 you could write
699 fahrenheit(x) [1;K] tempF(x); ~tempF(fahrenheit)
701 You may occasionally wish to define a function that operates on units.
703 This can be done using a nonlinear unit definition. For example, the
704 definition below provides conversion between radius and the area of a
705 circle. Note that this definition requires a length as input and pro‐
706 duces an area as output, as indicated by the specification in brackets.
707 circlearea(r) [m;m^2] pi r^2 ; sqrt(circlearea/pi)
709 Sometimes you may be interested in a piecewise linear unit such as many
711 wire gauges. Piecewise linear units can be defined by specifying con‐
712 versions to linear units on a list of points. Conversion at other
713 points will be done by linear interpolation. A partial definition of
714 zinc gauge is
715 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
717 In this example, `zincgauge' is the name of the piecewise linear unit.
719 The definition of such a unit is indicated by the embedded `[' charac‐
720 ter. After the bracket, you should indicate the units to be attached
721 to the numbers in the table. No spaces can appear before the `]' char‐
722 acter, so a definition like `foo[kg meters]' is illegal; instead write
723 `foo[kg*meters]'. The definition of the unit consists of a list of
724 pairs optionally separated by commas. This list defines a function for
725 converting from the piecewise linear unit to linear units. The first
726 item in each pair is the function argument; the second item is the
727 value of the function at that argument (in the units specified in
728 brackets). In this example, we define `zincgauge' at five points. For
729 example, we set `zincgauge(1)' equal to `0.002 in'. Definitions like
730 this may be more readable if written using continuation characters
731 as
732 zincgauge[in] \
733 1 0.002 \
734 10 0.02 \
735 15 0.04 \
736 19 0.06 \
737 23 0.1
738 With the preceeding definition, the following conversion can be per‐
740 formed:
741 You have: zincgauge(10)
743 You want: in
744 * 0.02
745 / 50
746 You have: .01 inch
747 You want: zincgauge
748 5
749 If you define a piecewise linear unit that is not strictly monotonic,
751 then the inverse will not be well defined. If the inverse is requested
752 for such a unit, `units' will return the smallest inverse. The
753 `--check' option will print a warning if a non-monotonic piecewise lin‐
754 ear unit is encountered.
755
757 Some units have different values in different locations. The localiza‐
758 tion feature accomodates this by allowing the units database to specify
759 region dependent definitions. A locale region in the units database
760 begins with `!locale' followed by the name of the locale. The leading
761 `!' must appear in the first column of the units database. The locale
762 region is terminated by `!endlocale'. The following example shows how
763 to define a couple units in a locale.
764 !locale en_GB
766 ton brton
767 gallon brgallon
768 !endlocale
769 The current locale is specified by the `LOCALE' environment variable.
771 Note that the `-c' option only checks the definitions which are active
772 for the current locale.
773
775 The `units' programs uses the following environment variables.
776 LOCALE Specifies the locale. The default is `en_US'. Sections of the
778 units database are specific to certain locales.
779 PAGER Specifies the pager to use for help and for displaying the con‐
781 formable units. The help function browses the units database
782 and calls the pager using the `+nn' syntax for specifying a line
783 number. The default pager is `more', but `less', `emacs', or
784 `vi' are possible alternatives.
785 UNITSFILE
787 Specifies the units database file to use (instead of the
788 default). This will be overridden by the `-f' option. Note that
789 you can only specify a single units database using this environ‐
790 ment variable.
791
793 If the `readline' package has been compiled in, then when `units' is
794 used interactively, numerous command line editing features are avail‐
795 able. To check if your version of `units' includes the readline,
796 invoke the program with the `--version' option.
797 For complete information about readline, consult the documentation for
799 the readline package. Without any configuration, `units' will allow
800 editing in the style of emacs. Of particular use with `units' are the
801 completion commands.
802 If you type a few characters and then hit `ESC' followed by the `?' key
804 then `units' will display a list of all the units which start with the
805 characters typed. For example, if you type `metr' and then request
806 completion, you will see something like this:
807 You have: metr
809 metre metriccup metrichorsepower metrictenth
810 metretes metricfifth metricounce metricton
811 metriccarat metricgrain metricquart metricyarncount
812 You have: metr
813 If there is a unique way to complete a unitname, you can hit the tab
815 key and `units' will provide the rest of the unit name. If `units'
816 beeps, it means that there is no unique completion. Pressing the tab
817 key a second time will print the list of all completions.
818
820 /usr/share/units.dat - the standard units data file
821
823 Adrian Mariano (adrian@cam.cornell.edu)
824 25 Sep 2007 UNITS(1)