calc: User-Defined Units
12.4 User-Defined Units
=======================
Calc provides ways to get quick access to your selected “favorite”
units, as well as ways to define your own new units.
To select your favorite units, store a vector of unit names or
expressions in the Calc variable ‘Units’. The ‘u 1’ through ‘u 9’
commands (‘calc-quick-units’) provide access to these units. If the
value on the top of the stack is a plain number (with no units
attached), then ‘u 1’ gives it the specified units. (Basically, it
multiplies the number by the first item in the ‘Units’ vector.) If the
number on the stack _does_ have units, then ‘u 1’ converts that number
to the new units. For example, suppose the vector ‘[in, ft]’ is stored
in ‘Units’. Then ‘30 u 1’ will create the expression ‘30 in’, and ‘u 2’
will convert that expression to ‘2.5 ft’.
The ‘u 0’ command accesses the tenth element of ‘Units’. Only ten
quick units may be defined at a time. If the ‘Units’ variable has no
stored value (the default), or if its value is not a vector, then the
quick-units commands will not function. The ‘s U’ command is a
convenient way to edit the ‘Units’ variable; Operations on
Variables.
The ‘u d’ (‘calc-define-unit’) command records the units expression
on the top of the stack as the definition for a new, user-defined unit.
For example, putting ‘16.5 ft’ on the stack and typing ‘u d rod’ defines
the new unit ‘rod’ to be equivalent to 16.5 feet. The unit conversion
and simplification commands will now treat ‘rod’ just like any other
unit of length. You will also be prompted for an optional English
description of the unit, which will appear in the Units Table. If you
wish the definition of this unit to be displayed in a special way in the
Units Table buffer (such as with an asterisk to indicate an approximate
value), then you can call this command with an argument, ‘C-u u d’; you
will then also be prompted for a string that will be used to display the
definition.
The ‘u u’ (‘calc-undefine-unit’) command removes a user-defined unit.
It is not possible to remove one of the predefined units, however.
If you define a unit with an existing unit name, your new definition
will replace the original definition of that unit. If the unit was a
predefined unit, the old definition will not be replaced, only
“shadowed.” The built-in definition will reappear if you later use ‘u u’
to remove the shadowing definition.
To create a new fundamental unit, use either 1 or the unit name
itself as the defining expression. Otherwise the expression can involve
any other units that you like (except for composite units like ‘mfi’).
You can create a new composite unit with a sum of other units as the
defining expression. The next unit operation like ‘u c’ or ‘u v’ will
rebuild the internal unit table incorporating your modifications. Note
that erroneous definitions (such as two units defined in terms of each
other) will not be detected until the unit table is next rebuilt; ‘u v’
is a convenient way to force this to happen.
Temperature units are treated specially inside the Calculator; it is
not possible to create user-defined temperature units.
The ‘u p’ (‘calc-permanent-units’) command stores the user-defined
units in your Calc init file (the file given by the variable
‘calc-settings-file’, typically ‘~/.emacs.d/calc.el’), so that the units
will still be available in subsequent Emacs sessions. If there was
already a set of user-defined units in your Calc init file, it is
replaced by the new set. (General Mode Commands, for a way to
tell Calc to use a different file for the Calc init file.)