Version: 23.4

# Using Numbers with Units

In SenseTalk, you can use numbers, either as numerals or text, for many types of operations and comparisons. Numbers often represent a quantity of some particular type, not merely an abstract value. For instance, the area of a rectangle might be referenced as "9 square inches" or an account balance might contain \$698.53.

SenseTalk lets you associate a unit type such as inches or dollars with a number to add meaning and relevance. Assignments to variables and calculations using those values maintain and convert units as needed.

## Working with Units​

To specify a numeric value with a unit type, you include the unit name after the value. (The exception to this rule is the dollar symbol — \$ — as described below.) SenseTalk recognizes singular, plural, and abbreviated unit names as well as "square" and "cubic" modifiers for area and volume:

``put 3 ft --> "3 feet"set weight to four gramsput 9 sq in --> "9 square inches"``

Note: You do not include a period with unit abbreviations.

You can use chained values of the same type, with one value after another or with values joined by `and`. Such representations are commonly used for weight or distance measurements:

``put 6 ft 3 in --> "6.25 feet"set weight to 2 pounds and 3 ouncesput weight --> "2.1875 pounds"``

As you begin to see in the examples above, you can mix units in your expressions. Units are preserved or converted as needed in assignments and calculations:

``put 3 ft into widthadd 1 yard to width -- 1 yard is automatically converted to 3 ft in order to add it to the existing widthput width --> "6 feet"put width * 4 feet into areaput area --> "24 square feet"add 2 liters to area -- throws a mismatched units exception``

You can combine units to form complex unit types such as speed (distance per timeInterval) or volume (length times width times depth):

``set speed to 25 mi/hrput speed --> "25 miles per hour"put 3 hrs 45 min * speed --> "93.75 miles"set accelerationOfGravity to 32 ft/s^2set flow to 5 gallons per minuteset clickRate to 500/hrset price to \$5.96 per lb -- same as: 5.96 dollars per poundset weight to 4 ozput price * weight --> "\$1.49"``

### A Note on Unit Compatibility​

SenseTalk converts units to combine values when it makes sense (as in combining 3 feet and 1 yard to get 6 feet). However, if you try to combine units that can't logically be combined (such as a flat area measurement and a volume measurement), you will get an error.

Units must be compatible (represent the same type of measure) to be added, subtracted or compared. That is, a unit of length (for example) can be added to another unit of length, even if the specific unit type is different (meters + feet + inches = OK!). These types are said to be compatible.

However, attempting to perform addition, subtraction, or comparison with incompatible units will throw an exception:

``put average(4 in, 5 ft, 1 meter) --> 0.8752 metersput average(4 in, 5 ft, 1 pint) -- throws an exception because of differing unit types``

## Unit Conversions​

As mentioned above, SenseTalk will automatically convert values from one unit type to another. This ability can be particularly useful in mathematical operations. You can also explicitly convert units from one type to another.

SenseTalk automatically converts values to compatible units for addition and subtraction operations, and to compare two values for equality. For addition and subtraction, the resulting value will favor one unit type over another based on the internal ordering of the units in the system.

For example, adding inches and centimeters gives the result in centimeters regardless of the order of the operands. Adding meters and centimeters results in meters. However, you can use the `as` operator to specify the result type:

``put 8 inches + 3 cm -- converts 8 inches to centimeters and adds 3 centimeters to it,      -- so prints: "23.32 centimeters"put (8 inches + 3 cm) as inches -- as above, but converts to inches before output,      -- so prints: "9.181102 inches"``

Addition or subtraction of a number with a unit type and a plain number (i.e., a number without a unit type) results in an error.

### Multiplication, Division​

When multiplying and dividing with units, whether the unit is maintained or converted is a little more complicated. You can use plain numbers to multiply or divide numbers with units, and the result preserves the unit type:

``set height to 20 feetset width to 3 times heightput width --> 60 feetset var1 to 2put 10 hours / var1 --> 5 hours``

When dividing where both numbers include units, values with compatible unit types are converted to the same unit, just as for addition. The units, however, are dropped from the results:

``Put 4 yards divided by 2 feet -- Prints: "6" (4 yards can be divided into 6 2-foot segments)``

When numbers with units are multiplied, whether compatible or incompatible, the units are kept and a complex unit type is formed. For example, dividing miles by hours will keep both units, resulting in a value with the complex unit type miles per hour:

``put 500 miles divided by 4 hours --> 125 miles per hourput 4 yard * 2 feet --> 24 square feetput 2 liters times 2 liters --> 4 liters^2``

You can use lists of units with mathematical operators. With multiplication and division, you can use a single plain number against a list. With addition, subtraction, multiplication, and division, you can use multiple lists of numbers with units, provided the number of items in the lists match:

``put [4 oz, 2 g, 0.3 m] / 3 --> [1.333333 ounces,0.666667 grams,0.1 meters]``
``put [4 oz, 2 g, 0.3 m] + [4 oz, 2 g, 0.3 m] --> [8 ounces,4 grams,0.6 meters]``
``put [4 oz, 2 g, 0.3 m] - [4 oz, 2 g, 0.3 m] --> [0 ounces,0 grams,0 meters]``
``put [4 oz, 2 g, 0.3 m] * [4 oz, 2 g, 0.3 m] --> [16 ounces^2,4 grams^2,0.09 square meters]``
``put [4 oz, 2 g, 0.3 m] / [4 oz, 2 g, 0.3 m] --> [1,1,1]``

### Ranges​

You can use units when you specify a range. If a unit is specified for only one end of a range, the other end is assumed to be the same unit type:

``put 3..7 m/s --> 3 meters per second to 7 meters per second``

Similarly, the `between` operator assumes matching units if units are given for only the second value:

``put 4 cm is between 1 and 3 inches --> True``

### Conversion with As​

You can use the `as` operator to convert a value to a specific unit:

``put 5 feet as inches --> 60 inchesput 27 grams as oz --> 0.952397 ouncesput totalWeight as kilogramsset distance to (var1 + var2) as yards``

In the final example above, it is necessary to enclose "var1 + var2" in parentheses to ensure that the final result will be expressed in yards. Without the parentheses (i.e., "var1 + var2 as yards"), the value of var2 would be converted to yards before adding to the value of var1 because the `as` operator has a higher order of precedence than the `+` operator. So the resulting unit might be yards or something else, depending on the units of var1.

### The Convert Command​

A value in a variable can be converted to a particular unit by using the `convert` command. If the source value being converted is not a variable or other container, the resulting value is stored in the variable `it`.

``convert depth to fathoms -- the value in depth is now in fathomsconvert 3.5 gallons to cc -- the result is stored in it``

Note: The convert command can also be used to convert date and time formats, as described in Date and Time Values in SenseTalk.

### The Units Property​

It's possible to access or change the `units` property of a variable directly. However, note that this method doesn't convert the value:

``set width to 6 ftput width's units --> feetput width --> 6 feetconvert width to yardsput width's units --> yardsput width --> 2 yardsset width's units to "feet"-- this sets the value's unit directly, replacing the previous unitput width's units --> feetput width --> 2 feet``

Note that width's `units` property could also be referred to as `width.units` or `the units of width`. Remember that changing the units property directly doesn't perform a value conversion, so be sure to use this method with care.

You might want to set the units for a plain number value that doesn't already have a unit. For example, a handler might assume that a parameter passed in represents meters if it's not explicitly given in some other unit:

``put areaOfCircle(6 in) --> 113.097336 square inchesput areaOfCircle(4) --> 50.265482 square metersfunction areaOfCircle radius  if radius.units is empty then set units of radius to "meters"  return pi * radius squaredend areaOfCircle``

## Unit Types​

SenseTalk supports units for time intervals (duration in days, minutes, etc.), length or distance (miles, feet, meters, etc.), mass or weight (grams, ounces, etc.), liquid measures (liters, gallons, etc.), rotation and angles (degrees, radians, etc.), electrical measures (amps, volts, etc.), and many others.

You can test values to see if they are of a particular type by using the `is a` operator:

``if mySize is not a length then put "size must be a length"if amount is a weight then set calculateByWeight to true``

### Currency​

You can specify currency amounts in dollars by preceding a value with a dollar sign (\$), since that's the common method for writing monetary amounts. Currency can also be specified by using unit names such as dollars and cents following the number, as with other unit types:

``set cost to 5 dollars and 27 centsset cost to \$5.27``

## Unit Type Functions​

### `FormattedUnits` Function​

Behavior: Applies a unit format to a numeric value with units and returns the formatted value. Learn more about how to write unit formats.

Parameters: The unit format string followed by the value that you would like to format. Alternatively, the same result is achieved by using the format operator to apply a unit format to a numeric value.

Syntax:
formattedUnits(unitFormat, valueWithUnits)
valueWithUnits {with | using} format unitFormat

Example:

``put formattedUnits("[miles] @, [feet] @", 8765 ft) --> 1 mile, 3485 feetput formattedUnits("[earthMass] @ + [moonMass] @", 1 sunMass) --> 332948 earthMasses + 28 moonMassesput 35 ounces using format "[lb] lb [oz] oz" --> 2 lb 3 oz``

Related:

### `SplitUnits` Function​

Behavior: Converts a numeric value of a certain unit type into a specified list of units that add up to the original value. For example, convert a weight into pounds and ounces, or a duration into hours, minutes, and seconds.

This function cycles through the requested unit names in order, and allocates the whole number of each of those units in turn from the original value. The final unit in the list receives the remaining part of the value, including any fractional part.

Parameters: The value that you want to convert, or 'split', followed by the names of the units that you want to convert the value to, either as separate parameters, or as a list of names.

Pass in `“”` or `empty` as an additional unit type when you don't want to return a fraction for the final unit. See the example.

Syntax:
splitUnits(valueWithUnits, listOfRequestedUnitNames)
splitUnits(valueWithUnits, unitName1 {, unitName2, …})

Example:

``put splitUnits(4288.321 seconds, ["hrs","mins","secs",empty]) --> [1 hour,11 minutes,28 seconds] // Use 'empty' to absorb any amount that is smaller than the final unit typeput splitUnits(4288.321 seconds, "hrs", "mins", "secs") --> [1 hour,11 minutes,28.321 seconds]``

Related:

### `UnitNames` Function​

Behavior: Returns a list of all unit names that SenseTalk recognizes, or a list of all unit names for a specific unit type.

Parameter:

• (Default) Use `"all"`, or no parameter, to get a list of all unit names in SenseTalk.
• Pass the name of a unit type, such as `"length"`, to get a list of all units of that type.

Syntax:
unitNames({unitTypeOrAll})

Example:

``put unitNames("speed") --> ["knot","mph","mps","kph","knots"]put unitNames() into allUnitNames``

Related:

### `UnitTypes` Function​

Behavior: Returns a list of the names of all unit types that SenseTalk recognizes, with or without synonyms.

Parameter:

• (Default) Use `"all"`, or no parameter, to get a list of all unit types in SenseTalk, including synonyms.
• Pass in `"standard"`, to get a list of only the standard names for each unit type, excluding synonyms.

Syntax:
unitTypes({allOrStandard})

Example:

``put unitTypes("standard") --> ["length","mass","byteSize","duration","calendarDuration","rotation","electric_charge","area","volume","electric_current","force","pressure","stress","energy","power","electric_potential","electric_resistance","resistance","electric_conductance","conductance","electric_capacitance","magnetic_flux","inductance","magnetic_flux_density","frequency","velocity","acceleration","flow","angular_velocity","temperature_difference","currency"]``

Related:

### `UnitType` Function​

Behavior: Returns the standard unit type for a unit name, or the unit name of a numeric value.

Parameter: Accepts either a unit name or numeric value with units.

Syntax:
unitType({unitNameOrValueWithUnits})

Example:

``put unitType("weight") --> massput unitType(765 ft) --> length``

Related:

## Units Global Properties​

SenseTalk has three global properties that affect the configuration and formatting of units in SenseTalk.

### `the unitFormats` Global Property​

Values: A property list that holds the default unit format for one or more unit types.

Default: `{:}` An empty property list.

Behavior: Determines the format used for displaying values with units. If the `unitFormats` property includes a format for a given unit type, that format is used unless a different specific format is requested for the value.

The keys of the `unitFormats` must be valid unit types returned by the `unitTypes` function. The corresponding value for each unit type must be a unit format string.

note

The keys for unit types are standardized automatically to the standard name for that type. For example, assigning a format to the key `weight` is perfectly valid, but actually sets the `mass` property of the `unitFormats`. See example.

Example:

``set the unitFormats.weight to "[lbs?] @ [oz.] @" // This actually sets the 'mass' propertyput 67 ounces --> 4 lb 3 ozput 5432 grams --> 11 lbs 15.608161 oz``

Example:

``put 5432 sec --> 5432 secondsset the unitFormats.duration to "[hours 00]:[minutes 00]:[seconds 00]"put 5432 sec --> 01:30:32``

Example:

``set the unitFormats to {duration: "[hrs? 00*]:[mins]:[secs]",byteSize: "[GB? 0.0*] @||MB?||KB?||Bytes",electric_current: "Milliamp 0.###",}put 139 sec --> 02:19put 789234 bytes --> 770.7 KBput 5.6 amperes --> 5600 Milliamps``

### `the unitsEnabled` Global Property​

Values: `True`, `False`

Default: `True`

Behavior: Turns the units system on or off. When `the unitsEnabled` is set to `False`, most units are ignored. For compatibility with earlier versions, units of duration (hours, minutes, seconds, etc.) and dataSize (kilobytes, megabytes, etc.) are honored when `the unitsEnabled` is turned off. Other units are ignored.

### `the strictUnits` Global Property​

Values: `True`, `False`

Default: `True`

Behavior: Controls how strictly the units system is honored. Setting the property to `False` makes the system more relaxed about unit operations. For example, if you set this property to `False`, then add a plain number to one with units, SenseTalk treats the plain number as having the same units (so 7 ft + 3 = 10 feet) rather than throwing an exception. Other operations will drop the units (e.g., specifying a range of 4 acres to 6 lbs will give "4 to 6" and 3 ft + 4 gallons = 7).