USING Mask

Updated May 2015

USING creates a formatted string expression based on a coded "picture" of how the value(s) should appear. The mask may be multi-field or single-field. The multi-field case is only used in the PRINT statement, prior to the list of values, e.g.:

num USING mask

PRINT USING mask, v1 {, ..., vn}

Where:

num is a numeric expression.

v1 thru vn are string or numeric expressions.

mask is a string describing how to format the value(s), according to the rules described below.

Note that while similar, the two cases shown above are distinct in important ways.

The first form, num USING mask, is a string expression, made up of a numeric value, the USING operator, and a string mask, which returns a string—i.e. the value formatted as a string. As a string expression, it can be used anywhere a string expression can be used. Note that the expression preceding the USING operator must be numeric, and that the mask should contain format instructions for only a single value, plus optional literal characters. Another name for this would be a Single Valued Numeric USING Expression. Examples:

PRINT #0, "Batting average: ";(HITS / AT'BATS) using "N.###"

TOTAL$ = (QTY * PRICE * (1 - DISCOUNT)) USING "Your total is: $#####.##"

In the second form, USING mask is an optional clause affecting the operation of the PRINT statement. Another name for it would be a PRINT USING Clause. In this case, the mask should contain formatting instructions for the same number of values as will be supplied as arguments to the PRINT statement. This kind of mask can deal with a mixture of numeric and string values, whereas the Single Valued Numeric USING Expression can only deal with numeric formatting. For example:

MASK$ = "Name: \-------------\ Age: ### Sex: ! Score: ###.#%"

PRINT #0 USING MASK$, name$,age,sex$,hits*100/tries

While the masks are intended to be somewhat self-explanatory, the interpretation of the various special characters is described in the following table. Note that for clarity, an underscore character is used to show a space in the Result column.

Specifier	Description	Example--->	Result
#	Marks a position to be filled by a numeric digit or leading minus sign. Masks allowing for more digits than necessary will result in right justification with leading spaces; see Z. Fractional values will be rounded to the nearest integer unless the mask contains a decimal point.	123 using "####" 123.6 using "###"	_123 124
Z	To replace leading spaces with leading zeroes, replace all but the first # with Z.	123 using "#ZZZ"	0123
.	(period) Marks the position of the decimal point. Any # characters to the right of the of the decimal point will be zero-filled.	123 using "###.##"	123.00
,	(comma) Causes thousands separators to be output between each three digits.	123456 using "###,###"	123,456
$	Outputs the currency symbol at the specified position; may be leading or trailing.	123 using "$#####.##"	$ 123.00
$$	Same as $ but when used in the leading position, shifts the currency symbol over to immediately before the first digit with the leading spaces in front of the currency symbol.	123 using "$$#####.##"	_$123.00
*	A format mask starting with two asterisks followed by a dollar sign will act like the $$ case but will replace the leading spaces with asterisks.	123 using "**$#####.##"	****$123.00
^	Outputs exponential format.	12345 using ".####^^^^"	.1236E05
-	(minus sign) When put at the trailing end of a numeric mask, causes negative numbers to print with a trailing minus sign. Otherwise negative values will print with leading minus signs, and the minus sign takes up a position otherwise available to a digit.	-123 using "#####" -123 using "####-" 123 using "####-"	-123 123- 123_
\	(String specifier, PRINT USING clause only) A pair of backslashes marks a string field in the multi-field version of the USING clause. If the string value is too long it will be truncated. Characters between the backslashes each define a position in the output but are not printed, allowing you to use self-documenting descriptions instead of dashes or blanks.	using "Name: \-----\ Age: ##", nam$, Fn'Age(dob)	Name: Jack Age: 99
!	(String specifier, PRINT USING clause only) Defines a single-character field.	using "Sex: ! Age: ##", gender$, age'nearest	Sex: M Age: 25
!	(Single Valued Numeric USING Expression only) Behaves like ".", except that if there are no non-zero digits to the right of the decimal point in the formatted output, it changes the decimal point in the formatted output to a space. Note that "!" is also used to denote a single character field in a PRINT USING MASK statement. The two different uses of the same mask character should be clear to the interpreter from the context.	See "Examples" below
N	Behaves the same as "#", except that when placed after a decimal point, it causes any trailing zeros to be converted to blanks. If placed before the decimal point, and it is not followed by any "#" character prior to the decimal point, then it causes leading zeros to be convered to blanks. This is similar to the normal case with "#", except that for values less than 1, "#" will display a leading zero whereas "N" will not. See N Character Handling.	See "Examples" below
n	Behaves just like "N", except that to the left of the decimal point it causes leading blanks to be stripped, and to the right of the decimal point, trailing blanks to be stripped. See N Character Handling.	See "Examples" below
Any other character	Treated as a literal.	123 using "[A-###]"	[A-123]

Examples (!, N, n)

1234.5 using "$$###,###.###" displays " $1,234.500"

1234.5 using "$$###,###.NNN" displays " $1,234.5 "

1234.5 using "$$###,###.nnn" displays " $1,234.5"

1234.5 using "$$###,###!nnn" displays " $1,234.5"

1234.5 using "$$nnn,nnn!nnn" displays "$1,234.5"

1234.5 using "nnn,nnn.nnn$" displays "1,234.5 $"

1234.0 using "$$###,###!NNN" displays " $1,234 "

1234.0 using "$$###,###!nnn" displays " $1,234"

1234.0 using "$$nnn,nnn!nnn" displays "$1,234"

1234.0 using "$nnnn,nnn!nnn" displays "$ 1,234"

0 using "###.#" displays " 0.0"

0 using "###.N" displays " 0. "

0 using "NNN.n" displays " ."

0 using "NNN!n" displays ""

0 using "nnn.N" displays ". "

0 using "nnn!N" displays ""

0 using "nnn.n" displays "."

0 using "nnn!n" displays ""

1.23 using "n.###" displays "1.230"

0.23 using "n.###" displays ".230"

Comments

For numeric specifiers, the maximum width of the formatted number will be equal to the total number of characters in the specifier, including the special characters. If the number doesn't fit in that space, the result will be a percent sign (%) followed by the number with default numeric formatting. In the case of string specifiers, the string will simply be truncated to fit the specifier.

String specifiers can only be used in the multi-field variation of the USING MASK clause, i.e. PRINT #CH USING MASK$, expr1, expr2,...

Although the decimal point, comma, and dollar sign characters in the mask are invariable, the actual decimal, thousands separator and currency symbols used in the formatted result will be based on the Language Definition.

Although the USING operator is primarily associated with PRINT statements, the single-field version may be used like any other string expression, such as in assignment statements, as parameters to functions, etc. They are often used as a convenient and elegant way to round results in arithmetic operations. For example, in the following statement the formatting mask is being used as a convenient way to round each item total to an even number of cents:

TOTAL = (QTY * PRICE) USING "#######.##"

Note that what really happens in the above assignment statement is that the floating point result (QTY * PRICE) is rounded to the nearest cent and then represented as a string, which is then converted back to a floating point value stored in TOTAL. This technique is a good solution to the problem of making sure the internal values exactly match the printed values so that, for example, column totals add up as expected. Traditional arithmetic approaches to rounding are more syntactically complex and run the risk of deviating from the way the printed results are rounded.) However, when using masks for rounding purposes, make sure there are no non-numeric characters in the mask (dollar signs and commas in particular), and that the mask is big enough to handle any possible value (since the leading % in an overflow will cause the result to evaluate to zero).