Q(uick)BASIC Function: FormatX$

Quick View

FormatX$

These functions provide a wide range of formats for numeric and date/time data

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

FormatI$ (expression# , fmt$)
FormatL$ (expression# , fmt$)
FormatS$ (expression# , fmt$)
FormatD$ (expression# , fmt$)
FormatC$ (expression# , fmt$)

Description/Parameter(s)

expression#	A numeric expression to be formatted.
fmt$	A string expression that consists of BASIC display-format characters detailing how the expression is to be displayed.
Returns	A string that contains the formatted expression.

If the argument fmt$ is not specified for a null string, the general format - that which would give output identical to output with no formatting - is used.

Usage Notes

To use any of the FormatX$ functions, you must first start BASIC with the correct Quick library, link your program with FORMAT.LIB, or use the FORMAT.QLB Quick library.
The following symbols are used to create formats:

This symbol	Means this
Null string	Display the number in general format.
0	Digit place holder:
0	If the number has fewer digits on either side of the decimal point than there are zeros on either side of the decimal point in the format, then the extra zeros are displayed. If the number has more digits to the right of the decimal point than there are zeros to the right in the format, the number is rounded to as many decimal places as there are zeros to the right. If the number has more digits to the left of the decimal point than there are zeros to the left in the format, the extra digits are displayed.
#	Digit place holder:
#	Follows the same rules as for the 0 digit placeholder, except that extra zeros are not displayed if the number has fewer digits on either side of the decimal point than there are #'s on either side of the format.
.	Decimal point:
.	This symbol determines how many digits (0's or #'s) BASIC displays to the right and left of the decimal point. Depending on the country code set using the SetFormattCC routine, BASIC may use the comma as the decimal point. If the format contains only #'s to the left of this symbol, then numbers smaller than 1 are begun with a decimal point. To avoid this, you should use 0 as the first digit placeholder to the left of a decimal point instead of #.
%	Percentage
%	The expression is multiplied by 100 and the % character is inserted.
,	Thousands separator:
,	BASIC separates thousands by commas (or by periods if the country code has been set to a country other than the United States) if the format contains a comma surrounded by #'s or 0's. Two adjacent commas, or a comma immediately to the left of the decimal point location (whether there is a decimal specified or not) means "Omit the three digits that fall between these commas, or between the comma and the decimal point, rounding as needed."
E- E+ e- e+	Scientific format:
E- E+ e- e+	If a format contains one digit placeholder (0 or #) to the right of an E-, E+, e-, or e+, BASIC displays the number in scientific format and inserts an E or e. The number of 0's or #'s 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 minus sign next to negative exponents and a plus sign next to positive exponents.
: - + $ () space	Display that literal character:
	To display a character other than one of these, precede the character with a backslash (\) or enclose the character(s) in double quotation marks ("").
	Display the next character in the format string:
	Many characters in the format string have a special meaning and cannot be displayed as literal characters unless they are preceded by a backslash. The backslash is not displayed. This is the same as enclosing the next character in double quotation marks. Examples of such characters are the date- and time-formatting characters (y, m, d, h, s, a, and p) and the numeric-formatting characters (#, 0, %, E, e, comma, and period).
"abc"	Display whatever text is inside the double quotes:
"abc"	To include a text string in fmt$, you must use CHR$(34) to enclose the text (34 is the ASCII code for double quotation mark).

Some sample numeric formats are shown below (these examples all assume the country code is set to 1, the United States).

	Result for:
Format (fmt$)	5	-5	.5
Null string	5	-5	0.5
0	5	-5	1
0.00	5.00	-5.00	0.50
#,##0	5	-5	1
#,##0.00	5.00	-5.00	0.50
$#,##0;($#,##0)	$5	($5)	$1
$#,##0.00;($#,##0.00)	$5.00	($5.00)	$0.50
0%	500%	-500%	50%
0.00%	500.00%	-500.00%	50.00%
0.00E+00	5.00E+00	-5.00E+00	5.00E-01
0.00E-00	5.00E00	-5.00E00	5.00E-01

A number format can have three sections separated by semicolons. The first section formats positive values; the second section formats negative values, and the third section formats zeros. The following example has two sections: the first section defines the format for numbers greater than 0; the second section defines the format for numbers less than 0:

$#,##0;($#,##0)

You can use from one to three sections:

If you use	The result is
One section only	The format applies to all numbers.
Two sections	The first section applies to positive numbers and zeros; the second to negative numbers.
Three sections	The first section applies to positive numbers, the second to negative numbers numbers, and the third to zeros.

If you have semicolons with nothing between them, the missing section prevents that type of number from being displayed. For example, the following format will print positive numbers and zeros, but it will not print negative numbers.

$#,##0;;"Zero"

Date/Time Formats

Date/time serial numbers can be formatted with date/time or with numeric formats (since date/time serial numbers are stored as floating-point values). Date/time formats are:

This symbol	Means this
d dd ddd dddd	Display the day as a number without leading zeros (1-12), as a number with leading zeros (01-12), as an abbreviation (Sun-Sat), or as a full name (Sunday-Saturday).
m mm mmm mmmm	Display the month as a number without leading zeros (1-12), as a number with leading zeros (01-12), as an abbreviation (Jan-Dec), or as a full month name (January-December). If you use m or mm immediately after the h or hh symbol, the minute rather than the month is displayed.
yy yyyy	Display the year as a two-digit number (00-99), or as a four-digit number (1900-2040).
h hh	Display the hour as a number without leading zeros (0-23), or as a number with leading zeros (00-23). If the format contains an AM or PM, the hour is based on the 12-hour clock. Otherwise, the hour is based on the 24-hour clock.
m mm	Display the minute as a number without leading zeros (0-59), or as a number with leading zeros (00-59). The m or mm must appear after an h or hh, or the month is displayed rather than the minute.
s ss	Display the second as a number without leading zeros (0-59), or as a number with leading zeros (00-59).
AM/PM am/pm A/P a/p	Display the hour using a 12-hour clock. AM, am, A, or a are displayed for times up until noon; PM, pm, P, or p are displayed for times between noon and midnight.

The following are examples of date and time formats:

Format	Display
m/d/yy	12/7/58
d-mmmm-yy	7-December-58
d-mmmm	7-December
mmmm-yy	December-58
h:mm AM/PM	8:50 PM
h:mm:ss AM/PM	8:50:35 PM
h:mm	20:50
h:mm:ss	20:50:35
m/d/yy h:mm	12/7/58 20:50

Example

This example uses the FormatD$ function to format date and time information. The current date and time are returned as a serial number by the Now# function.
Note: To run this example you must use a Quick library that includes the procedures contained in the date/time/format library files. The following include files must also be present.

'$INCLUDE: 'DATIM.BI'
'$INCLUDE: 'FORMAT.BI'
 
CLS
PRINT "Today's date is "; FormatD$(Now#, "dd-mmm-yy"); "."
PRINT "The correct time is "; FormatD$(Now#, "hh:mm:ss AM/PM"); "."

Sample Output:

Today's date is 02-May-1989. The correct time is 2:22:14 PM.