Format
From Xojo Documentation
Returns as a string a formatted version of the number passed based on the parameters specified. The Format function is similar to the way spreadsheet applications format numbers. Format will use the information based on the user’s locale even if the user’s locale is a Unicode-only locale.
Syntax
result=Format(number, formatSpec)
| Part | Type | Description |
|---|---|---|
| result | String | The formatted number (ASCII encoded). |
| number | Double | The number to be formatted. |
| formatSpec | String | Defines the formatting to be applied to the number passed. |
Notes
The formatSpec is a string made up of one or more special characters that control how the number will be formatted:
| Character | Description |
|---|---|
| # | Placeholder that displays the digit from the value if it is present.
If fewer placeholder characters are used than in the passed number, then the result is rounded. |
| 0 | Placeholder that displays the digit from the value if it is present.
If no digit is present, 0 (zero) is displayed in its place. |
| . | Placeholder for the position of the decimal point. |
| , | Placeholder that indicates that the number should be formatted with thousands separators. |
| % | Displays the number multiplied by 100. |
| ( | Displays an open paren. |
| ) | Displays a closing paren. |
| + | Displays the 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. There is no effect for positive numbers. |
| E or e | Displays the number in scientific notation. |
| \character | Displays the character that follows the backslash. Use this to display a character that is also used in the formatSpec. |
The absolute value of the number is displayed. You must use the + or - signs if you want the sign displayed.
Although the special formatting characters are U.S. characters, the actual characters that will appear are based on the current operating system settings. For example, Windows uses the settings in the user's Regional and Language Options Control Panel. Formatting characters are specified in similar ways on other operating systems.
The formatSpec can be made up of up to three formats separated by semicolons. The first format is the format to be used for positive numbers. The second format is the format to be used for negative numbers and the third format is the format to be used for zero.
Examples
The following are several examples that use the various special formatting characters.
| Format | Number | Formatted String |
|---|---|---|
| #.## | 1.786 | 1.79 |
| #.0000 | 1.3 | 1.3000 |
| 0000 | 5 | 0005 |
| #% | 0.25 | 25% |
| ###,###.## | 145678.5 | 145,678.5 |
| #.##e | 145678.5 | 1.46e+5 |
| -#.## | -3.7 | -3.7 |
| +#.## | 3.7 | +3.7 |
| #.##;(#.##);\z\e\r\o | 3.7 | 3.7 |
| #.##;(#.##);\z\e\r\o | -3.7 | (3.7) |
| #.##;(#.##);\z\e\r\o | 0 | zero |
The following example returns the number 3560.3 formatted as $3,560.30.
See Also
TextEdit.Mask, TextEdit.Format properties, TextField.