Querying units of measurement

Including queries in macros : Understanding the available query criteria : Querying units of measurement

Querying units of measurement

You can query units of measurement, such as to convert values. Linear-dimension units (such as millimeters, inches, meters, centimeters, and points) are supported, as are angle units (such as degrees and radians) and file-size units (such as bytes, kilobytes, megabytes, and gigabytes).

To provide a constant unit of measurement, you must include the unit value and unit of measurement in braces ( {} ):

•

{1 in} — equals one inch

•

{1 mm} — equals one millimeter

Certain math operations can be performed on units of measurement, as in the following examples:

•

{1 cm} + {1 mm} — yields {1.1 cm}

•

{1 pt} * 3 — yields {3 pt}

Units of measurement support the following query criteria:


Query criteria	Description	Example and result
unit.BaseValue()	Returns the base value of the unit, in base units. Base units are chosen for the category, and all the other units are internally represented in terms of these base units.	`{1 in}.baseValue` Yields 254000
unit.Category()	Returns a string describing the unit category	`{1 in³}.category` Yields 'Linear Dimensions'
unit.Convert(string)	Converts the unit value to another unit of measurement of the same category	`{1 in³}.convert('mm')` Yields 16387.064 mm³
unit.DisplayUnit()	Returns the unit name and possible unit power (such as 'mm' or 'cm³')	`{1 in³}.displayUnit` Yields 'in³'
unit.Power()	Returns the power of the unit	`{1 in³}.power` Yields 3
unit.Unit()	Returns the unit name as a string	`{1 in³}.unit` Yields 'in'
unit.Value()	Returns the value of the unit, in the current units of measurement	`{1 in³}.value` Yields 1

Handling exponents when querying units of measurement

In addition to multiplication and division, queries on units of measurement support exponents. Units of different degrees can be specified by using the following general syntax:

{value unit^power}

Consider the following examples:

•

{2 mm^2} — yields 2 square millimeters

•

{3 in^3} — yields 3 cubic inches

Units of power zero (such as {2 mm^0}) evaluate to regular numeric values. For example, {2 mm^0} equals 2.

Powers of 2 and 3 can be specified by using (respectively) the special characters ² (U+00B2) and ³ (U+00B3) after the unit of measurement, as in the following examples:

•

{2 mm²} — yields 2 square millimeters

•

{3 in³} — yields 3 cubic inches

Multiplying units increases the power of the unit, while dividing them decreases the power:

•

{2 mm} * {2 mm} — yields {4 mm²}

•

{4 mm²} / {1 mm} — yields {4 mm}

Comparing units can be done only with units of the same power:

•

{2 mm} * {2 mm} = {4 mm²} — yields True (because the comparison is correct)

•

{2 mm} * {2 mm} = {4 mm} — yields an error (because mm² is being compared to mm)

However, different units of the same unit category can be used in expressions:

•

{1 in} = {72 pt} — yields True (because inches and points belong to the same unit category)

To eliminate rounding error, comparisons of units of measurement are performed with reduced precision. The default precision level is three decimal places of the largest unit in the comparison. For precise comparison, the precise-equality operator ( == ) can be used. Consider the following expressions, given that one millimeter equals 2.83464566929134 points:

•

{1 mm} = {2.835 pt} — yields True

•

{1 mm} == {2.835 pt} — yields False

When converting units, the unit power must be considered. To convert values between different units, the unit.convert method must be used. Consider the following examples:

•

{1 in}.convert('mm') — yields {25.4 mm}

•

{1 in²}.convert('mm') — yields {645.16 mm²}