From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

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.


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.


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 followed by the % character.
( 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.

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.

Var s As String
s = Format(3560.3, "\$###,##0.00")

See Also

TextEdit.Mask, TextEdit.Format properties, TextField.