A-Shell Consolidated Reference

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.

 

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).

See Also:

History

2015 Mayl, A-Shell 6.1.1410:  Add additional N Character Handling.

2015 April, A-Shell 6.1.1407:  Add specifiers !, N, n, re-write first section above.