USING$ function

Purpose

Format one or more string or numeric expressions, based upon the contents of the format mask string.

Syntax

sResult$ = USING$(fmtmask$, expr [, expr [, ...]])

Remarks

The rules of formatting are based upon the PRINT USING statement supported in many DOS versions of BASIC, including PowerBASIC for DOS.

However, since it is implemented as a function, it allows far more versatility in that it is not necessary to output a value to gain the benefit of this unique functionality. Also, USING$ offers a wider range of applications than FORMAT$ because it can format both numeric and string expressions, and can take multiple arguments.

fmtmask$

A string expression, string variable or string literal consisting of format characters that will determine how the complete expression should be formatted. This expression is termed the mask. There may be as many format masks in fmtmask$, arranged in the same order as the expr arguments are specified. See the examples below for more information.

expr

A string or numeric expression, variable, or literal value to be formatted. The mask characters available depend on whether expr is a string or numeric.

Character	Definition
(string expr)	When expr is a string, the following format codes apply within fmtmask$:
!	The first character of the string is returned.
&	The entire string is returned.
\\	The first two characters are returned.
\ \	If backslashes enclose n spaces, n + 2 characters of the string expression are returned.
_	Escape (underscore) character. The following character is interpreted as a literal character instead of a mask format character.
(numeric expr)	When expr is numeric, the following format codes apply within fmtmask$:
#	A numeric digit position, which is space-filled to the left, and zero-filled to the right of the decimal point. If the number is negative, a minus sign occupies a digit position.
.	The decimal point is placed at this position.
,	A numeric digit position, which signifies that whole number digits should be displayed with a comma each three digits.
$$	Two numeric digit positions which cause a dollar sign to be inserted immediately before the number.
*x	Two numeric digit positions which cause leading blank spaces in the field to be replaced with the character in the second position of the pair "x" (where "x" represents your own choice of character). For example, two asterisks "*" will convert leading spaces to asterisks, and "=" converts leading spaces to equals characters, etc. The *x mask characters also act as two digit (#) placeholders. Your mask must contain at least three characters to use this.
+	A plus at the start of the field causes the sign of the value (+ -) to be inserted before the number. A plus at the end of the field causes the sign of the value (+ -) to be added after the number.
-	A minus at the end of the field causes a minus signed to be added after a negative number, or a space to be added after a positive number. A minus at the start of the field is treated as a literal character, which is always inserted.
^	Numbers can be formatted in scientific notation by including three to six carets (^) in the format string. Each caret corresponds to a numeric digit position in the exponent, one for E, one for the exponent sign, and one to four for the actual digits of the exponent value.
_	Escape (underscore) character. The following character is interpreted as a literal character instead of a mask format character. Therefore, to include a literal underscore character in the format mask, use two underscore characters.
	All characters in the format mask string that are not identified above are copied into the output string just as they are encountered. You can override or escape any special format code by preceding it with an underscore character ( _ ) and it will be copied as any other literal character. This provides the flexibility to include literal string text within the formatted return string.

Restrictions

The returned string is limited to an absolute length limit of 1024 bytes.

By specifying a single mask in fmtmask$, all expr arguments are subjected to the single mask. See the examples below.

If there are fewer expr arguments than matching format masks in fmtmask$, parsing of the fmtmask$ halts after the last referenced mask position, and subsequent characters in fmtmask$ are ignored. This is consistent with the behavior of PRINT USING$ in PB/DOS.

If a numeric argument overflows its mask (i.e., there are more digits than digit positions), the resulting string will occupy as many spaces as needed to represent the number. In such cases, PB/DOS includes a leading "%" symbol to indicate the mask overflow; however, PowerBASIC for Windows does not return the additional "%" overflow character.

The semicolon (;) and zero (0) characters are reserved for future use, so it would be prudent to escape such literal characters in USING$ masks to maintain future compatibility.