Unit Formats

Unit Formats control the display and formatting of units for numeric values, such as time intervals, length or distance, mass or weight.

Understanding Unit Formats

Without a unit format, the numeric value displays the full name of the unit type. For example:

In many cases, the default behavior is perfectly fine, but there are other times when you need more control of formatting. For example:

Without using a unit format, you can only display 4425 minutes as minutes, or as hours, or as days. A better format might be 3 days 1 hour 45 minutes, which is much easier to understand. To achieve this, you can apply either of the following formats:

Elements of Unit Formats

Unit formats can range from simple to rather complex. The easiest way to understand them is to begin with the basics and add in other options as required.

The Basics

The most basic unit formats are text strings where one or more unit tokens, or unit names, are replaced by a number in the final result. You can use a singular or plural unit name, or even an abbreviation, and capitalization doesn't matter. The name just needs to identify a unit type. For example:

If more than one unit name is included in the unit format, SenseTalk works from left to right, replacing each token in turn with the whole number of units of that type that add up to the numeric value. In the following example, SenseTalk:

• Determines that 483 seconds is equal to 8.05 minutes.
• Replaces the [min] token with the whole number 8.
• Allocates the remainder, 0.05 minutes or 3 seconds, to the next token.

Unit Names in Tokens

As mentioned earlier, the syntax that you use for unit tokens, or unit names, is flexible. You can include singular, or plural names, or even abbreviations. For example, you can write the unit token that represents hours as [hours] or [hour] or [hrs] or [hr]. The following unit format strings look slightly differently but apply the same formatting.

Number Formats

Number formats let you control whether whole numbers or fractions, including the number of digits and decimal places, are displayed. In the following example, the dot in [seconds .] allows the display of any fractions of a second:

The .### in [seconds .###] displays fractions of a second up to three decimal places:

The 00 in [minutes 00] displays two digits for this unit type, even if there are zero minutes. The 00.000 in [seconds 00] displays two digits before, and three digits after the decimal place, to display fractions of a second or zeros:

You can also use the unitFormats global property to set the number format for one or more unit types.

Default Number Format

If the unit token does not include a number format, it defaults to 0. To override this default for the current token and all subsequent tokens, use an asterisk (*):

Unit Names (@tokens)

The (@) sign is a special token which appears after the unit name token within the unit format. When the format is applied, this special token is automatically replaced by the correct singular or plural form of the unit name:

Additionally, the unit name of the token in front of the (@) sign is applied to the value, including any abbreviation or changes in capitalization:

Conditional Segments

A question mark in a unit token indicates a conditional unit. This lets you suppress a unit if the value is zero. For example:

If the value for a conditional unit is zero, the text following that unit is also suppressed:

To apply this format, the system breaks it down into segments, with one segment for each unit token:

• [hours?] grueling @
• [minutes] @.

The question mark after hours makes this segment conditional. If the number of hours is zero, the entire segment is left out.

Mutually Exclusive Alternative Formats

A vertical bar (|) separates mutually exclusive formats. If the first format results in zero, the next is tried, and so on until a format is applied to a single unit type. For example:

If the unit format string in the example was applied to a numeric value of 43 inches, the following formats would be checked in turn:

• [miles] - 43 inches is less than one mile, so this segment is skipped.
• [yards] - 43 inches is more than one yard, so this segment is used and the remaining segments, [feet] and [inches], are ignored.

The result is 1 yard.

Mutually exclusive formats are useful for displaying byte sizes. For example, to show a file size in the most appropriate unit:

In this case, question marks are needed because the number formats include a decimal place. Without question marks, every value would display as GB even when it is less than 1 GB. With question marks, the numeric value must be at least 1 GB for that format to be applied.

Subsegments in Alternative Formats

To allow the formatting of more than one unit type, each alternative format can include subsegments. For example, the following unit format string contains two alternative formats, for larger and smaller units of length, each with two unit subsegments:

If the unit format string in the example was applied to a numeric value of one mile or more:

• [mi?] @ [yd] @ is used.
• [ft?] @ [in] @ is ignored.

If the value is less than 1 mile but at least 1 yard:

• [yd] @ is used.
• [mi?] @ is ignored.

If the value is less than 1 yard, the first alternative format [mi?] @ [yd] @ is skipped.

Simplified Formats

You can use a simplified format to display all units of a type, or family, in the same unit. For example, all lengths displayed in feet. In this case, use the format feet, which is treated as [feet] @.

When you're adding units of different types together, such as yards and inches, you might use the as feet operator to display the result in feet. However, there are still advantages to using a format to control this, such as assigning a format to a variable.

You can also use a simplified format for mutually exclusive formats:

Introduce a number format into the first alternate format followed by an asterisk (*) to make it the default for the rest of the format.

Question marks are needed in each of the GB, MB, and KB sections of this format because a number format with a decimal place is being used for each of those alternatives.

Custom Conditional Values

By default, 1 is the minimum number that triggers the formatting in a conditional segment.

When a value is less than 1, the conditional segment is skipped, and the next segment is processed. To change the value that causes the conditional segment to be triggered, include a number before the unit name within a token. In this example, feet are only displayed when the length is at least 2 feet rather than the default of 1 foot.

In the following example, the first alternative format is only used when the numeric value is at least 1.1 GB. If the value is less than 1.1 GB, the next segment is tested.

Escaping Special Characters

Unit formats use the following characters for special purposes: | , @ , [ , ] , \ , { , and }. The final two characters are reserved for future use. To include any of these characters in the text of a unit format outside of a [ ] token, enter a backslash (\) before the character.

 

This topic was last updated on May 03, 2022, at 01:36:18 PM.

Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant