|
Syntax |
Format[$](expression [,Userformat$]) |
|
|
Description |
Returns a String formatted to user specification. |
|
|
Comments |
Format$ returns a String, whereas Format returns a String variant. The Format$/Format functions take the following parameters: |
|
|
|
Parameter |
Description |
|
|
expression |
String or numeric expression to be formatted. |
|
|
Userformat$ |
Format expression that can be either one of the built-in Basic Control Engine formats or a user-defined format consisting of characters that specify how the expression should be displayed. String, numeric, and date/time formats cannot be mixed in a single Userformat$ expression. |
|
|
If Userformat$ is omitted and the expression is numeric, then these functions perform the same function as the Str$ or Str statements, except that they do not preserve a leading space for positive values. If expression is Null, then a zero-length string is returned. |
|
|
|
Built-In Formats To format numeric expressions, you can specify one of the built-in formats. There are two categories of built-in formats: one deals with numeric expressions and the other with date/time values. The following tables list the built-in numeric and date/time format strings, followed by an explanation of what each does. |
|
|
|
Numeric Formats |
|
|
|
Format |
Description |
|
|
General number |
Display the numeric expression as is, with no additional formatting. |
|
|
Currency |
Displays the numeric expression as currency, with thousands separator if necessary. |
|
|
Fixed |
Displays at least one digit to the left of the decimal separator and two digits to the right. |
|
|
Standard |
Displays the numeric expression with thousands separator if necessary. Displays at least one digit to the left of the decimal separator and two digits to the right. |
|
|
Percent |
Displays the numeric expression multiplied by 100. A percent sign (%) will appear at the right of the formatted output. Two digits are displayed to the right of the decimal separator. |
|
|
Scientific |
Displays the number using scientific notation. One digit appears before the decimal separator and two after. |
|
|
Yes/No |
Displays No if the numeric expression is 0. Displays Yes for all other values. |
|
|
True/False |
Displays False if the numeric expression is 0. Displays True for all other values. |
|
|
On/Off |
Displays Off if the numeric expression is 0. Displays On for all other values. |
|
|
Date/Time Formats |
|
|
|
Format |
Description |
|
|
General date |
Displays the date and time. If there is no fractional part in the numeric expression, then only the date is displayed. If there is no integral part in the numeric expression, then only the time is displayed. Output is in the following form: 1/1/95 01:00:00 AM. |
|
|
Long date |
Displays a long date. |
|
|
Medium date |
Displays a medium date—prints out only the abbreviated name of the month. |
|
|
Short date |
Displays a short date. |
|
|
Long time |
Displays the long time. The default is: h:mm:ss. |
|
|
Medium time |
Displays the time using a 12-hour clock. Hours and minutes are displayed, and the AM/PM designator is at the end. |
|
|
Short time |
Displays the time using a 24-hour clock. Hours and minutes are displayed. |
|
|
User-Defined Formats In addition to the built-in formats, you can specify a user-defined format by using characters that have special meaning when used in a format expression. The following tables list the characters you can use for numeric, string, and date/time formats and explain their functions. |
|
|
|
Numeric Formats |
|
|
|
Character |
Meaning |
|
|
Empty string |
Displays the numeric expression as is, with no additional formatting. |
|
|
0 |
This is a digit placeholder. |
|
|
|
Displays a number or a 0. If a number exists in the numeric expression in the position where the 0 appears, the number will be displayed. Otherwise, a 0 will be displayed. If there are more 0s in the format string than there are digits, the leading and trailing 0s are displayed without modification. |
|
|
# |
This is a digit placeholder. |
|
|
|
Displays a number or nothing. If a number exists in the numeric expression in the position where the number sign appears, the number will be displayed. Otherwise, nothing will be displayed. Leading and trailing 0s are not displayed. |
|
|
. |
This is the decimal placeholder. |
|
|
|
Designates the number of digits to the left of the decimal and the number of digits to the right. The character used in the formatted string depends on the decimal placeholder, as specified by your locale. |
|
|
% |
This is the percentage operator. |
|
|
|
The numeric expression is multiplied by 100, and the percent character is inserted in the same position as it appears in the user-defined format string. |
|
|
, |
This is the thousand separator. |
|
|
|
The common use for the thousands separator is to separate thousands from hundreds. To specify this use, the thousands separator must be surrounded by digit placeholders. Commas appearing before any digit placeholders are specified are just displayed. Adjacent commas with no digit placeholders specified between them and the decimal mean that the number should be divided by 1,000 for each adjacent comma in the format string. A comma immediately to the left of the decimal has the same function. The actual thousands separator character used depends on the character specified by your locale. |
|
|
:E- E+ e- e+ |
These are the scientific notation operators, which display the number in scientific notation. At least one digit placeholder must exist to the left of E-, E+, e-, or e+. Any digit placeholders displayed to the left of E-, E+, e-, or e+ determine the number of digits displayed in the exponent. Using E+ or e+ places a + in front of positive exponents and a – in front of negative exponents. Using E- or e- places a – in front of negative exponents and nothing in front of positive exponents. |
|
|
: |
This is the time separator. |
|
|
|
Separates hours, minutes, and seconds when time values are being formatted. The actual character used depends on the character specified by your locale. |
|
|
/ |
This is the date separator. |
|
|
|
Separates months, days, and years when date values are being formatted. The actual character used depends on the character specified by your locale. |
|
|
:- + $ ( ) space |
These are the literal characters you can display. To display any other character, you should precede it with a backslash or enclose it in quotes. |
|
|
\ |
This designates the next character as a displayed character. |
|
|
|
To display characters, precede them with a backslash. To display a backslash, use two backslashes. Double quotation marks can also be used to display characters. Numeric formatting characters, date/time formatting characters, and string formatting characters cannot be displayed without a preceding backslash. |
|
|
:"ABC" |
Displays the text between the quotation marks, but not the quotation marks. To designate a double quotation mark within a format string, use two adjacent double quotation marks. |
|
|
* |
This will display the next character as the fill character. |
|
|
|
Any empty space in a field will be filled with the specified fill character. |
|
|
Numeric formats can contain one to three parts. Each part is separated by a semicolon. If you specify one format, it applies to all values. If you specify two formats, the first applies to positive values and the second to negative values. If you specify three formats, the first applies to positive values, the second to negative values, and the third to 0s. If you include semicolons with no format between them, the format for positive values is used. |
|
|
|
String Formats |
|
|
|
Character |
Meaning |
|
|
@ |
This is a character placeholder. Displays a character if one exists in the expression in the same position; otherwise, displays a space. Placeholders are filled from right to left unless the format string specifies left to right. |
|
|
& |
This is a character placeholder. Displays a character if one exists in the expression in the same position; otherwise, displays nothing. Placeholders are filled from right to left unless the format string specifies left to right. |
|
|
< |
This character forces lowercase. Displays all characters in the expression in lowercase. |
|
|
> |
This character forces uppercase. Displays all characters in the expression in uppercase. |
|
|
! |
This character forces placeholders to be filled from left to right. The default is right to left. |
|
|
Date/Time Formats |
|
|
|
Character |
Meaning |
|
|
c |
Displays the date as ddddd and the time as ttttt. Only the date is displayed if no fractional part exists in the numeric expression. Only the time is displayed if no integral portion exists in the numeric expression. |
|
|
d |
Displays the day without a leading 0 (1–31). |
|
|
dd |
Displays the day with a leading 0 (01–31). |
|
|
ddd |
Displays the day of the week abbreviated (Sun–Sat). |
|
|
dddd |
Displays the day of the week (Sunday–Saturday). |
|
|
ddddd |
Displays the date as a short date. |
|
|
dddddd |
Displays the date as a long date. |
|
|
w |
Displays the number of the day of the week (1–7). Sunday is 1; Saturday is 7. |
|
|
ww |
Displays the week of the year (1–53). |
|
|
m |
Displays the month without a leading 0 (1–12). If m immediately follows h or hh, m is treated as minutes (0–59). |
|
|
mm |
Displays the month with a leading 0 (01–12). If mm immediately follows h or hh, mm is treated as minutes with a leading 0 (00–59). |
|
|
mmm |
Displays the month abbreviated (Jan–Dec). |
|
|
mmmm |
Displays the month (January–December). |
|
|
q |
Displays the quarter of the year (1–4). |
|
|
y |
Displays the day of the year (1–366). |
|
|
yy |
Displays the year, not the century (00–99). |
|
|
yyyy |
Displays the year (1000–9999). |
|
|
h |
Displays the hour without a leading 0 (0–24). |
|
|
hh |
Displays the hour with a leading 0 (00–24). |
|
|
n |
Displays the minute without a leading 0 (0–59). |
|
|
nn |
Displays the minute with a leading 0 (00–59). |
|
|
s |
Displays the second without a leading 0 (0–59). |
|
|
ss |
Displays the second with a leading 0 (00–59). |
|
|
ttttt |
Displays the time. A leading 0 is displayed if specified by your locale. |
|
|
AM/PM |
Displays the time using a 12-hour clock. Displays an uppercase AM for time values before 12 noon. Displays an uppercase PM for time values after 12 noon and before 12 midnight. |
|
|
am/pm |
Displays the time using a 12-hour clock. Displays a lowercase am or pm at the end. |
|
|
A/P |
Displays the time using a 12-hour clock. Displays an uppercase A or P at the end. |
|
|
a/p |
Displays the time using a 12-hour clock. Displays a lowercase a or p at the end. |
|
|
AMPM |
Displays the time using a 12-hour clock. Displays the string s1159 for values before 12 noon and s2359 for values after 12 noon and before 12 midnight. |
|
Example |
Const crlf = Chr$(13) + Chr$(10) Sub Main() da$ = Date$ ti$ = Time$ |
|
|
See Also |
||
|
Note |
The default date/time formats are read from the [Intl] section of the win.ini file. |
|
|
|
F |
