Formats a string, number or variant data type to a format expression.
Format returns a string.
expression
Expression to be formatted.
fmt
A string of characters that specify how the expression is to displayed. or the name of a commonly-used format that has been
predefined in BlueZone Basic. Do not mix different type format expressions in a single fmt parameter.
If the fmt parameter is omitted or is zero-length and the expression parameter is a numeric, Format[$] provides the same functionality as the Str[$] function by converting the numeric value to the appropriate return data type, Positive numbers convert to strings using Format[$] lack the leading space reserved for displaying the sign of the value, whereas those converted using Str[$] retain the leading space.
To format numbers, you can use the commonly-used formats that have been predefined in BlueZone Basic, or you can create user-defined
formats with standard characters that have special meaning when used in a format expression.
Display a digit or a zero
If the number being formatted has fewer digits than there are zeros (on either side of the decimal) in the format expression,
leading or trailing zeros are displayed. If the number has more digits to the right of the decimal separator than there are
zeros to the right of the decimal separator in the format expression, the number is rounded to as many decimal places as there
are zeros. If the number has more digits to left of the decimal separator than there are zeros to the left of the decimal
separator in the format expression, the extra digits are displayed without modification.
# Digit placeholder
Displays a digit or nothing. If there is a digit in the expression being formatted in the position where the # appears in
the format string, displays it; otherwise, nothing is displayed.
. Decimal placeholder
The decimal placeholder determines how many digits are displayed to the left and right of the decimal separator.
% Percentage placeholder
The percent character (%) is inserted in the position where it appears in the format string. The expression is multiplied
by 100.
, Thousand separator
The thousand separator separates thousands from hundreds within a number that has four or more places to the left of the decimal
separator.
Use of this separator as specified in the format statement contains a comma surrounded by digit placeholders (0 or #). Two
adjacent commas or a comma immediately to the left of the decimal separator (whether or not a decimal is specified) means
“scale the number by dividing it by 1000, rounding as needed.”
E-E+e-e+ Scientific format
If the format expression contains at least one digit placeholder (0 or #) to the right of E-,E+,e- or e+, the number is displayed
in scientific formatted E or e inserted between the number and its exponent. The number of digit placeholders to the right
determines the number of digits in the exponent. Use E- or e- to place a minus sign next to negative exponents. Use E+ or
e+ to place a plus sign next to positive exponents.
: Time separator
The actual character used as the time separator depends on the Time Format specified in the International section of the Control
Panel.
/ Date separator
The actual character used as the date separator in the formatted out depends on Date Format specified in the International
section of the Control Panel.
- + $ ( ) space Display a literal character
To display a character other than one of those listed, precede it with a backslash (\).
\ Display the next character in the format string
The backslash itself isn’t displayed. To display a backslash, use two backslashes (\\).
Examples of characters that can’t be displayed as literal characters are the date- and time- formatting characters (a,c,d,h,m,n,p,q,s,t,w,y,
and /:), the numeric -formatting characters (#,0,%,E,e,comma, and period), and the string- formatting characters (@,&,<,>,
and !).
“String” Display the string inside the double quotation marks
To include a string in fmt from within BlueZone Basic, you must use the ANSI code for a double quotation mark Chr(34) to enclose
the text.
* Display the next character as the fill character
Any empty space in a field is filled with the character following the asterisk.
Unless the
fmt argument contains one of the predefined formats, a format expression for numbers can have from one to four sections separated
by semicolons.
| If you use |
The result is |
| One section only |
The format expression applies to all values. |
| Two |
The first section applies to positive values, the second to negative sections values. |
| Three |
The first section applies to positive values, the second to negative sections values, and the third to zeros. |
| Four |
The first section applies to positive values, the second to negative section values, the third to zeros, and the fourth to
Null values.
|
The following example has two sections: the first defines the format for positive values and zeros; the second section defines
the format for negative values.
“$#,##0; ($#,##0)”
If you include semicolons with nothing between them. the missing section is printed using the format of the positive value.
For example, the following format displays positive and negative values using the format in the first section and displays
“Zero” if the value is zero.
“$#,##0;;\Z\e\r\o”
Some sample format expressions for numbers are shown below. (These examples all assume the Country is set to United States
in the International section of the Control Panel.) The first column contains the format strings. The other columns contain
the output the results if the formatted data has the value given in the column headings.
| Format (fmt) |
Positive 3 |
Negative 3 |
Decimal .3 |
Null |
| Null string |
3 |
-3 |
0.3 |
|
| 0 |
3 |
-3 |
1 |
|
| 0.00 |
3.0 |
-3.00 |
0.30 |
|
| #,##0 |
3 |
-3 |
1 |
|
| #,##0.00;;;Nil |
3.0 |
-3.00 |
0.30 |
Nil |
| $#,##0;($#,##0) |
$3 |
($3) |
$1 |
|
| $#,##0.00;($#,##0.00) |
$3.0 |
($3.00) |
$0.30 |
|
| 0% |
300% |
-300% |
30% |
|
| 0.00% |
300.00% |
-300.00% |
30.00% |
|
| 0.00E+00 |
3.00E+00 |
-3.00E+00 |
3.00E-01 |
|
| 0.00E-00 |
3.00E00 |
-3.00E00 |
3.00E-01 |
|
Numbers can also be used to represent date and time information. You can format date and time serial numbers using date and
time formats or number formats because date/time serial numbers are stored as floating-point values.
To format dates and times, you can use either the commonly used format that have been predefined or create user-defined time
formats using standard meaning of each:
The following table shows the predefined data format names you can use and the meaning of each.
| Format name |
Description |
| General |
Display a date and/or time. For real numbers, display a date and time (for example, 4/3/93 03:34 p.m.); if there is no fractional
part, display only a date (for example, 4/3/93); if there is no integer part, display time only (for example, 03:34 p.m.).
|
| Long Date |
Display a Long Date, as defined in the International section of the Control Panel. |
| Medium |
Display a date in the same form as the Short Date, as defined in the international section of the Control Panel, except spell
out the month abbreviation.
|
| Short Date |
Display a Short Date, as defined in the International section of the Control Panel. |
| Long Time |
Display a Long Time, as defined in the International section of the Control panel. Long Time includes hours, minutes, seconds.
|
| Medium Time |
Display time in 12-hour format using hours and minuets and the Time AM/PM designator. |
| Short Time |
Display a time using the 24-hour format (for example, 17:45) |
This table shows the characters you can use to create user-defined date/time formats.
| Character |
Meaning |
| c |
Display the date as dddd and display the time as ttttt. in the order. |
| d |
Display the day as a number without a leading zero (1-31). |
| dd |
Display the day as a number with a leading zero (01-31). |
| ddd |
Display the day as an abbreviation (Sun-Sat). |
| ddddd |
Display a date serial number as a complete date (including day , month, and year). |
| w |
Display the day of the week as a number (1- 7 ). |
| ww |
Display the week of the year as a number (1-53). |
| m |
Display the month as a number without a leading zero (1-12). If m immediately follows h or hh, the minute rather than the
month is displayed.
|
| mm |
Display the month as a number with a leading zero (01-12). If mm immediately follows h or hh, the minute rather than the month
is displayed.
|
| mmm |
Display the month as an abbreviation (Jan-Dec). |
| mmmm |
Display the month as a full month name (January-December). |
| q |
Display the quarter of the year as a number (1-4). |
| y |
Display the day of the year as a number (1-366). |
| yy |
Display the day of the year as a two-digit number (00-99) |
| yyyy |
Display the day of the year as a four-digit number (100-9999). |
| h |
Display the hour as a number without leading zeros (0-23). |
| hh |
Display the hour as a number with leading zeros (00-23). |
| n |
Display the minute as a number without leading zeros (0-59). |
| nn |
Display the minute as a number with leading zeros (00-59). |
| s |
Display the second as a number without leading zeros (0-59). |
| ss |
Display the second as a number with leading zeros (00-59). |
| ttttt |
Display a time serial number as a complete time (including hour, minute, and second) formatted using the time separator defined
by the Time Format in the International section of the Control Panel. A leading zero is displayed if the Leading Zero option
is selected and the time is before 10:00 A.M. or P.M. The default time format is h:mm:ss.
|
| AM/PM |
Use the 12-hour clock and display an uppercase AM/PM |
| am/pm |
Use the 12-hour clock display a lowercase am/pm |
| A/P |
Use the 12-hour clock display a uppercase A/P |
| a/p |
Use the 12-hour clock display a lowercase a/p |
| AMPM |
Use the 12-hour clock and display the contents of the 11:59 string (s1159) in the WIN.INI file with any hour before noon;
display the contents of the 2359 string (s2359) with any hour between noon and 11:59 PM. AMPM can be either uppercase or
lowercase, but the case of the string displayed matches the string as it exists in the WIN.INI file. The default format is
AM/PM.
|
The following are examples of user-defined date and time formats:
| Format |
Display |
| m/d/yy |
2/26/65 |
| d-mmmm-yy |
26-February-65 |
| d-mmmm |
26 February |
| mmmm-yy |
February 65 |
| hh:nn |
AM/PM 06:45 PM |
| h:nn:ss a/p |
6:45:15 p |
| h:nn:ss |
18:45:15 |
| m/d/yy/h:nn |
2/26/65 18:45 |
Strings can also be formatted with Format[$]. A format expression for strings can have one section or two sections separated
by a semicolon.
| If you use |
The result is |
| One section only |
The format applies to all string data. |
| Two sections |
The first section applies to string data, the second to Null values and zero-length strings. |
The following characters can be used to create a format expression for strings:
| Character |
Meaning |
| @ |
Character placeholder. |
| |
Displays a character or a space. Placeholders are filled from right to left unless there is an ! character in the format string.
|
| & |
Character placeholder. Display a character or nothing. |
| < |
Force lowercase. |
| > |
Force uppercase. |
| ! |
Force placeholders to fill from left to right instead of right to left. |
Example
' Format Function Example
' This example shows various uses of the Format function to format values
' using both named and user-defined formats. For the date separator (/),
' time separator (:), and AM/ PM literal, the actual formatted output
' displayed by your system depends on the locale settings on which the code
' is running. When times and dates are displayed in the development
' environment, the short time and short date formats of the code locale
' are used. When displayed by running code, the short time and short date
' formats of the system locale are used, which may differ from the code
' locale. For this example, English/United States is assumed.
' MyTime and MyDate are displayed in the development environment using
' current system short time and short date settings.
Sub Main
MyTime = "08:04:23 PM"
MyDate = "03/03/07"
MyDate = "January 27, 2007"
MsgBox Now
MsgBox MyTime
MsgBox Second( MyTime ) & " Seconds"
MsgBox Minute( MyTime ) & " Minutes"
MsgBox Hour( MyTime ) & " Hours"
MsgBox Day( MyDate ) & " Days"
MsgBox Month( MyDate ) & " Months"
MsgBox Year( MyDate ) & " Years"
' Returns current system time in the system-defined long time format.
MsgBox Format(Time, "Short Time")
MyStr = Format(Time, "Long Time")
' Returns current system date in the system-defined long date format.
MsgBox Format(Date, "Short Date")
MsgBox Format(Date, "Long Date")
MyStr Format(MyTime, "h:n:s") ' Returns "17:4:23".
MyStr Format(MyTime, "hh:nn:ss") ' Returns "20:04:22 ".
MyStr Format(MyDate, "dddd, mmm d yyyy") ' Returns "Wednesday,
' Jan 27 2007".
' If format is not supplied, a string is returned.
MsgBox Format(23) ' Returns "23".
' User-defined formats.
MsgBox Format(5459.4, "##,##0.00") ' Returns "5,459.40".
MsgBox Format(334.9, "###0.00") ' Returns "334.90".
MsgBox Format(5, "0.00%") ' Returns "500.00%".
MsgBox Format("HELLO", "<") ' Returns "hello".
MsgBox Format("This is it", ">") ' Returns "THIS IS IT".
End Sub