FORMAT$ function

Purpose | Format string data according to instructions contained in a format expression.
Syntax | x$ = FORMAT$(num_expression [, [digits& | fmt$]])
Remarks | FORMAT$ has the following parts:
num_expression | The numeric expression, variable, or literal value to be formatted. This argument is converted to full ( Extended) precision before formatting commences.
digits& | The maximum number of significant digits, in the range of 1 to 18. If not included, PowerBASIC supplies a default value of 7 for single precision values, or 16 for more precise values. This form of the function is very similar to the STR$() function, except that it never supplies any leading or trailing spaces. Use care that digits& is large enough to contain the whole part of a number, or scientific notation must be used to estimate it. For example, FORMAT$(123.456, 2) returns the string "1.2E+2", while FORMAT$(123.456, 5) returns the string "123.45".

fmt$

Format characters that will determine how the numeric expression should be formatted. This expression is termed the mask. There may be up to 18 digit-formatting digits on either side of the decimal point. The mask may not contain literal characters unless each character is preceded with a backslash (\) escape character, or the literal characters are enclosed in quotes.

fmt$ may contain one, two or three formatting masks, separated by semicolon (;) characters:

One mask | If fmt$ contains just one format mask, the mask is used to format all possible values of num_expression. For example:
| x$ = FORMAT$(z!, "000.00")
Two masks | If fmt$ contains two format masks, the first mask is used for positive values (=> 0), and the second mask is used for negative values (< 0). For example:
| x$ = FORMAT$(-100, "+00000.00;-000")
Three masks | If fmt$ contains three masks, the first mask is used for positive values (> 0), the second mask for negative values (< 0), and the third mask is used if num_expression is zero (0). For example:
| FOR y! = -0.5! TO 0.5! STEP 0.5! x$ = FORMAT$(y!, "+.0;-.0; .0") NEXT y!

Digit placeholders in a mask do not have to be contiguous. This allows you to format a single number into multiple displayed parts. For example:

A$ = FORMAT$(123456, "00\:00\:00") ' 12:34:56

The following table shows the characters you can use to create the user-defined format strings (masks) and the definition of each formatting character:

Character | Definition

Empty string

[null string] No formatting takes place. The number is converted to Extended-precision and formatted similarly to STR$, but without the leading space that STR$ applies to non-negative numbers.

A$=FORMAT$(0.2) ' .200000002980232

A$=FORMAT$(0.2!, "") ' .200000002980232

A$=FORMAT$(0.2#) ' .2

A$=FORMAT$(0.2#, "") ' .2

0

[zero] Digit placeholder. PowerBASIC will insert a digit or 0 in that position.

If there is a digit in num_expression in the position where the 0 appears in the format string, return that digit. Otherwise, return "0". If the number being formatted has fewer digits than there are zeros (on either side of the decimal point) in the format expression, leading or trailing zeros are added. If the number has more digits to the right of the decimal point than there are zeros to the right of the decimal point in the format expression, the number is rounded to as many decimal places as there are zeros in the mask.

If the number has more digits to the left of the decimal point than there are zeros to the left of the decimal point in the format expression, the extra digits are displayed without truncation. If the numeric value is negative, the negation symbol will be treated as a decimal digit. Therefore, care should be exercised when displaying negative values with this placeholder style. In such cases, it is recommended that multiple masks be used.

' Numeric padded with leading zero characters

A$ = FORMAT$(999%, "00000000") ' 00000999

# | [Number symbol] Digit placeholder. If there is a digit for this position, PowerBASIC replaces this placeholder with a digit, nothing, or a user-specified character.

Unlike the 0 digit placeholder, if the numeric value has the fewer digits than there are # characters on either side of the decimal placeholder, PowerBASIC will either:

a) Omit this character position from the final formatted string; or

Substitute a user-specified replacement character if one has been defined (see the asterisk (*) character for more information). To specify leading spaces, prefix the mask with "* " (asterisk and a space character).

For example:

' No leading spaces and trailing spaces

A$ = FORMAT$(0.75!, "####.###") ' 0.75

' Up to 3 Leading spaces before decimal

A$ = FORMAT$(0.75!, "* ##.###") ' 0.75

' Using asterisks for padding characters

A$ = FORMAT$(0.75!, "*=##.###") ' ===0.75=

FORMAT$ may also return a string that is larger than the number of characters in the mask:

A$ = FORMAT$(999999.9, "#.#") ' 999999.9

. | [period] Decimal placeholder. Determines the position of the decimal point in the resultant formatted string. If any numeric field is specified to the left of the decimal point, at least one digit will always result, even if only a zero. The zero is not considered to be a "leading" zero if it is the only digit to the left of the decimal. Placing more than one period character in the fmt$ string will produce undefined results.
% | [percent] Percentage placeholder. PowerBASIC multiplies num_expression by 100, and adds a trailing percent symbol. For example: x$ = FORMAT$(1 / 5!, "0.0%") ' 20.0%

,

[comma] Thousand separator. Used to separate thousands from hundreds within a number that has four or more digits to the left of the decimal point. In order to be recognized as a format character, the comma must be placed immediately after a digit placeholder character (also see Restrictions below).

A$ = FORMAT$(1234567@, "#,") ' 1,234,567

A$ = FORMAT$(12345@, "#,.00") ' 12,345.00

A$ = FORMAT$(12345@, "#.00,") ' 12,345.00

A$ = FORMAT$(1212.46, "$00,000.00") ' $01,212.46

A$ = FORMAT$(1000%, """#""#,") ' #1,000

A$ = FORMAT$(1234567@, "0,") ' 1,234,567

*x

[asterisk] Digit placeholder and fill-character. Instructs PowerBASIC to insert a digit or character "x" in that position. If there is a digit in num_expression at the position where the * appears in the format string, that digit is used; otherwise, the "x" character is used (where "x" represents your own choice of character). The *x specifier acts as two digit (#) fields.

A$ = FORMAT$(9999.9@,"$**####,.00")' $**9,999.90

A$ = FORMAT$(0@,"$*=###0,.00#") ' $=====0.00=

A$ = FORMAT$(0@,"$* ####0,.00") ' $ 0.00

E- e- E+ e+

[e] Scientific format. PowerBASIC will use scientific notation in the formatted output. Use E- or e- to place a minus sign in front of negative exponents. Use E+ or e+ to place a minus sign in front of negative exponents and a plus sign in front of non-negative exponents.

In order to be recognized as a format sequence, the E-, e-, E+, or e+ must be placed between two digit placeholder characters. For example:

A$ = FORMAT$( 99.999, "0.0E-##") ' 1.0E2

A$ = FORMAT$(-99.999, "0.0E-##") ' -1.0E2

A$ = FORMAT$( 99.999, "0.0E+##") ' 1.0E+2

A$ = FORMAT$(-99.999, "0.0E+##") ' -1.0E+2

A$ = FORMAT$(0.1!, "0.0e+##") ' 1.0e-1

"

[double-quote] Quoted string. PowerBASIC treats all characters up to the next quotation mark as-is, without interpreting them as digit placeholders or format characters. Also see backslash. For example:

A$ = FORMAT$(12, $DQ+"##"+$DQ+"##") ' ##12

A$ = FORMAT$(5.55, """XYZ=""#.##\#") ' XYZ=5.55#

A$ = FORMAT$(25, """x=""#") ' x=25

A$ = FORMAT$(999, """Total ""#") ' Total 999

A$ = FORMAT$(5, $DQ+"x="+$DQ+"#") ' x=5

\x

[backslash] Escaped character prefix. PowerBASIC treats the character "x" immediately following the backslash (\) as a literal character rather than a digit placeholder or a formatting character. Many characters in a mask have a special meaning and cannot be used as literal characters unless they are preceded by a backslash.

The backslash itself is not copied. To display a backslash, use two backslashes (\\). To display a literal double-quote, use two double-quote characters.

To simplify the mask string for common numeric formats, FORMAT$ permits the dollar symbol, the left and right parenthesis symbols, the plus and minus symbols, and the space character ("$()+- ") to pass through from the mask string into the formatted output string, without requiring an escape (\) prefix character.

A$ = FORMAT$(23, "(* 0\%)") ' ( 23%)

A$ = FORMAT$(99999, "#\#") ' 99999#

A$ = FORMAT$(5, "\"+$DQ+$DQ+"x="+$DQ+ _

"#\"+$DQ) ' "x=5"

A$ = FORMAT$(5, "\""""x=""#\""") ' "x=5"

A$ = FORMAT$(1000%, """#####,""") ' "#####,"

Restrictions

You cannot pass a string expression or string variable in num_expression. Do not place more than one decimal point in the mask.

FORMAT$ can return the maximum possible number of digits (up to 4932 for Extended-precision); however, the resulting digits will be meaningless beyond the actual precision of num_expression. Consequently, the value of num_expression may produce formatted strings that are wider than the length of fmt$, for example:

A$ = FORMAT$(3e30!, "#,###") ' returns 41 characters

Rounding, if necessary, is implemented by the "banker's rounding" principle: if the fractional digit being rounded off is exactly five, with no trailing digits, the number is rounded to the nearest even number. This provides better results, on average, and follows the IEEE standard. For example:

A$ = FORMAT$(0.5##, "0") ' 0

A$ = FORMAT$(1.5##, "0") ' 2

A$ = FORMAT$(2.5##, "0") ' 2

A$ = FORMAT$(2.51##, "0") ' 3

Semicolon characters, being mask delimiters, should not be used for other purposes in mask strings unless prefixed with an escaped character symbol (\).

FORMAT$, when used with some formatting characters such as the thousands separator (comma), may not produce a "right-justified" formatted string. The simple solution is to apply separate justification with the RSET statement or the RSET$ function. For example:

A$ = SPACE$(12)

RSET A$ = FORMAT$(1,"#,###.00") ' 1.00

RSET A$ = FORMAT$(1000, "#,.00") ' 1,000.00

RSET A$ = FORMAT$(1000000,"#,###.00")' 1,000,000.00

B$ = RSET$(FORMAT$(1e6, "#,"),10) ' " 1,000,000"

One further enhancement would be to combine this into a MACRO function, for example:

MACRO mMoney1(d,l) = "$"+RSET$(FORMAT$(d,"#,"),l-1)

MACRO mMoney2(d,l) = RSET$(FORMAT$(d,"$#,"),l)

' code here

A$ = mMoney1(1000,10) ' "$ 1,000"

B$ = mMoney2(1000,10) ' " $1,000"

See also | BIN$, GRAPHIC PRINT, GUID$, HEX$, OCT$, REPEAT$, SPACE$, STR$, STRING$, USING$, VAL, XPRINT