Masking

Masking is the process of formatting expressions using numeric masks and format masks.

Syntax

str.exp mask.exp

Parameter(s)

{r|l|d{n}{s}{z}{,}{c}{$}({{{f},l}...})

r\|l\|d	Specifies right-(r) or left-(l) aligned. The default is left. The d specifier functions identically to the r and is provided for compatibility reasons only.
n	Number of digits after a decimal point—this is a single numeric digit that specifies the number of digits to print following the decimal point. If n = 0, the decimal point is not output. If the number of digits following the decimal point is greater than the number specified by n, the output is rounded.
s	Scaling factor—this is a single numeric digit that specifies to descale the value by the precision power of 10. For example, an s value of 2 changes 1000 to 10.
z	Suppresses leading zeros.
,	Inserts commas between every thousands position of the value.
c	Signcode:
	c	Outputs CR after negative values. Two spaces follow positive or zero values.
	d	Outputs DB after positive values. Two spaces follow negative or zero values.
	e	Encloses negative values within angle brackets (<>). A space follows positive or zero values.
	m	Places a - to the right of negative values. A space follows positive or zero values. Ordinarily, the minus sign displays to the left of negative numbers.
	n	Suppresses the - on negative values.
$	Appends a dollar sign to beginning of value.
f	Fill character. The fill characters below are available, where n specifies the length up to 32,767 characters:
	%n	Fills with n zeros.
	#n	Fills with n spaces.
	*n	Fills with n asterisks.
l	Length.

Any other character, including parentheses, can be included in the fill mask. The characters are output exactly as they appear in the mask. If a dollar sign is placed outside of the format mask, it is output just prior to the value, regardless of the filled field. If a dollar sign is used within the format mask, it is output in the furthest position to the left regardless of the filled field. Parentheses are ignored if they are the first character of a mask.

The numeric mask code controls justification, precision, scaling, and credit indication.

The format mask code controls field length and fill characters. The entire format string is enclosed in quotation marks. If a format mask is used, it should be enclosed in parentheses within the quotation marks.

The entire format string can be used as a literal, or it can be assigned to a variable. A format string literal can immediately follow the string it is to format. A format string variable must be separated by at least one space from the string it is to format. The format string can also be used directly in conjunction with the print statement.

These mask codes must be entered in the order they are listed:

d{ }	If specified before any other mask, this specifies standard date conversions, and any other mask code is ignored. See Processing Codes for more information,
c	If specified before any other mask, the various character masks can be specified (for example, cu or cl), just like the oconv(string,"mcu").

Example(s)

This value in x is left-aligned, in a field of 12 characters. If the value of x is the word test, the output prints as follows (spaces are represented by lowercase b):

x = test

print x "l(#12)"

testbbbbbbbb

y is printed right-aligned, fill space, in a field of 15 characters. If the value of y is the word hello, the output is as follows (spaces are represented by lowercase b):

y = hello

print y "r(#15)"

bbbbbbbbbbhello

Unlike the mr2 conversion used in an oconv() or iconv() function, this masks the value of z based on the current value of precision in BASIC run time. If the value of z is 78657767 and the current precision is 4, then the amount of scaling is the requested scaling factor minus the precision. Because the scaling factor is equal to the precision, no scaling takes place. After evaluating the scaling, the mask adds two zeros after the decimal point, and justifies the result in a field of asterisks. Because the mask is not specified with a sufficient amount of asterisks to contain the result, only the 12 characters that are furthest to the right are displayed.

z = 78657767

print z "r24z,e$(*12)"

,657,767.00

This example outputs the external format of the current system date, right-aligned, fill space, in a field of 10 characters.

print oconv(date(),"d2/") "r(#10)"

bbmm/dd/yy