Formatting Values
From Xojo Documentation
Contents
There are many ways to control the display and formatting of numbers, dates, and times.
Numbers
Numbers are stored unformatted. Fortunately, there are two functions that can format a number: Format and Str.
The Format function makes providing formatting to numbers easy. The resulting number is formatted to use the number formatting of your OS settings. To use this function, pass it a format specification and the number you wish formatted. The Format function then returns a string that represents the number with the formatting applied to it. The syntax for the Format function is:
The Str function works similarly to Format, but it does not use the OS settings to format the number.
For example, the decimal “.” is always used as the decimal separator when Str is used to format the number regardless of what the OS number format setting specifies. Use the Format function for numbers that should be displayed to the user. Use Str function for numbers that should be stored (perhaps in a database or XML file).
FormatSpec
The FormatSpec is a string made up of one or more characters that control how the number will be formatted. For example, the format spec “$###,##0.00” applies the dollars and cents formatting used in the United States.
On Windows, the character that is used as the Decimal and Thousands separator is specified by the user in the Regional Settings Control Panel. On Mac, these characters are specified on the Formats panel of the International system preference.
By default, the FormatSpec applies to all numbers. If you want to specify different FormatSpecs for positive numbers, negative numbers, and zero, simply separate the formats with semi-colons within the FormatSpec. The order in which you supply FormatSpecs is: positive, negative, zero. These characters are used in a FormatSpec:
| Format Character | Description |
|---|---|
| # | Placeholder that displays the digit from the value if it’s present. |
| 0 | Placeholder that displays the digit from the value if it’s present. If no digit is present, 0 (zero) is displayed in its place. |
| . | Placeholder for the position of the decimal character. |
| , | Placeholder that indicates that the number should be formatted with thousands separators. |
| % | Displays the number multiplied by 100 (or as a percent). |
| ( | Displays an open parenthesis. |
| ) | Displays a closing parenthesis. |
| + | Displays a plus sign to the left of the number if the number is positive or a minus sign if the number is negative. |
| - | Displays a minus sign to the left of the number if the number is negative. Nothing is displayed for positive numbers. |
| E or e | Displays the number in scientific notation. |
| \ | Displays the character that follows the backslash. Use this to display other characters in the output. |
Here are some example FormatSpecs and their corresponding output (on a US-based system):
| Format Syntax | Output |
|---|---|
| Format(1.784, "#.##") | 1.78 |
| Format(1.3, "#.0000") | 1.3000 |
| Format(5, "0000") | 0005 |
| Format(0.25, "#%") | 25% |
| Format(145678.5, "###,###.##") | 145,678.5 |
| Format(145678.5, "#.##e+") | 1.46E+05 |
| Format(-3.7, "-#.##") | -3.7 |
| Format(3.7, "+#.##") | +3.7 |
| Format(3.7, "#.##; (#.##); \z\e\r\o") | 3.7 |
| Format(0, "#.##; (#.##); \z\e\r\o") | zero |
Dates
Dates are objects and have properties that hold the date in various different formats. To get a date as a string formatted in a specific way, you simply access the appropriate property.
| Property | Default Output (on US-based systems) |
|---|---|
| ShortDate | 10/31/18 |
| LongDate | Wednesday, October 31, 2018 |
| AbbreviatedDate | Wed, Oct 31, 2018 |
Date formats are controlled by the user’s Date Properties (Windows) or Date Formats (Mac) system settings. On Mac, the Date Formats dialog is accessed from the Formats panel of the “Languages & Text” system preference (Click Customize... in the Date area in the Formats panel). On Windows, Date Properties is a screen in the Regional Options control panel. Users can choose the order of the day, month, year, as well as the separators.
The Date class’s ShortDate, AbbreviatedDate, and LongDate properties use whatever format that the user has set in these system settings and may not match what is in the table.
To get the current date in any of these formats, simply create and instantiate a date object and then access the appropriate property. In this example, the current date formatted as a long date, is assigned to a variable:
The TotalSeconds property of a Date object is the “master” property that stores the date/time associated with the object. The TotalSeconds property is defined as the number of seconds since Jan 1, 1904.
Other property values are derived from TotalSeconds. If you change the value of the TotalSeconds property, the values of the Year, Month, Day, Hour, Minute, and Second properties change to reflect the second on which TotalSeconds occurs. Conversely, if you change any of these properties, the value of TotalSeconds changes commensurately.
Times
Time values are stored as part of a date. Date objects have two properties that store time values in two different formats. These properties can returned a time value:
| Property | Default Output (on US-based systems) |
|---|---|
| ShortTime | 2:32 PM |
| LongTime | 2:32:34 PM |
To get the current time in either of these formats, create and instantiate a Date object and then access the appropriate property. In this example, the current time formatted as a LongTime, is assigned to a variable:
As is the case with date formats, several aspects of the ShortTime and LongTime formats are controlled by the user via the Time screen in the Regional Settings Control panel on Windows or the Time Formats panel in “Languages & Text” preferences (Mac).
See Also
Format, Str functions; Date class; UserGuide:Framework, UserGuide:Localization topics