⍺ (Picture format) and
⍕ (Format by specification and Format by example) for other formatting functions.)
⎕FMT is a FORTRAN-like formatter. The
⎕FMT function takes the form:
A ⎕FMT B
and converts the elements of an object B which may be a scalar, vector or matrix
(2≥⍴⍴B) to a character representation of B based on the specifications of A, which consist of phrase types, qualifiers and decorators, as summarised below. If B is a vector it is treated as a 1 column matrix, if it is a scalar it is treated as if it were a 1 by 1 matrix. B must be a simple array.
The left argument, A, is a character vector consisting of one or more phrases, each phrase separated from the previous phrase by a comma. Spacing within the phrase does not matter unless it is within two text delimiters.
The phrases are processed from left to right, with each phrase determining the format of a field in the result. A phrase may be enclosed by a single pair of parentheses, but nested parentheses or parentheses which enclose more than one phrase, are not allowed. If 'xxxx' represents a phrase, then 'xxxx,(xxxx)' is valid but '(xxxx,xxxx)' is not. Each phrase, possibly preceded by a repetition factor, consists of 2 basic parts in the following order:
i qualifiers and decorators
ii phrase identifier with associated parameters
The repetition factor is optional and if omitted defaults to 1. If specified, the repetition factor must be first and may not be enclosed in parentheses. It is used to indicate how often a phrase is to be repeated before the system uses the next one. 3xxxx,yyy means 'repeat phrase 'xxxx' 3 times, then use phrase 'yyy'. A repetition of 0 is not allowed.
⎕FMT will also repeat phrases, wrapping around to the first phrase again if necessary, until all columns in the right argument have been processed.
Delimiters are used to insert text, or a pattern into the result of
⎕FMT. Delimiters may be used by themselves, in conjunction with picture formatting (G) or with decorators (R,M,N,P,Q,S). The following pairs of delimiters are used to delimit literal strings, picture patterns and decorators:
Left delimiter Right delimiter
For readability, you are recommended to reserve the
⎕' delimiters for decorators and the
>' delimiters for strings and pictures.
'⎕ THIS IS A <LITERAL> ⎕,I5' ⎕FMT 10
THIS IS A <LITERAL> 10
A - character format
E - exponential format
F - fixed point format
G - picture format
I - integer format
T - place the result of subsequent phrases following rightmost column
Tn - place the result of subsequent phrases starting in absolute column
Xn - offset the result of subsequent phrases by n columns from current
- character format
Syntax: An n is the total field width in the result
Place a character from the current column of the right argument in a right- justified field of width n. The width specification is usually 1 and it almost always appears with a replication factor equal to the column dimension of the character matrix being formatted. If the right argument is not character, then an overflow condition exists (the
* in overflow
'4A1,A3'⎕FMT 2 5⍴'ABCDEFGHIJ
'A4'⎕FMT 4 6 (A vector is treated as a 1 column
**** matrix, and overflow occurs with a
**** numeric argument.)
- exponential format
Syntax: En.m n is the total field width in the result, m is the number of significant digits to be displayed.
Format a number from the current column in the right argument using the exponential form. If the field width is 0, then the field is empty. Following the last digit of the mantissa, 5 positions are reserved for the letter E and the exponent. The exponent is left justified and consists of a minus sign (if required) and up to 3 digits which represent the magnitude of the exponent. If the m value is 1 then the . is omitted, and if m is 0 then the mantissa is omitted.
Qualifiers: B,C,K,L,Z Decorators: M,N,P,Q,R,S Substitutable Characters: E in the exponent, . leading zeros, the
¯ in the exponent and the
* for overflow.
'E11.4'⎕FMT 100 7.6978E23 ¯.004
'E8.1,E8.0'⎕FMT 1 2⍴16 .02
- fixed point format
Syntax: FN.m n is the total field width in the result, m is the number of digits to be displayed after the decimal point.
Format a number from the current column of the right argument using the fixed point form. If the field width is 0, then the field is empty. If m is 0, then the decimal point is not suppressed.
Qualifiers: B,C,K,L,Z Decorators: M,N,P,Q,R,S Substitutable Characters: The . leading 0s, commas and the
* for overflow.
'CF10.2'⎕FMT 98.672 ¯12796.497
'S<,..,>CF10.2'⎕FMT 98.672 ¯12796.497
- Picture format
Syntax: Gtext text is a COBOL-like 'picture' format statement within a pair of delimiters.
The text consists of Zs, 9s, and any other characters. A Z will become a digit only if that digit is significant, otherwise it is replaced in the result by a blank. A 9 is replaced with a digit only if that digit is significant, otherwise it appears as a 0. A text string with Zs and 9s on both sides which has a Z on either side is displayed only if the Z becomes a significant digit in the result. Periods are treated like any other character. Numbers are rounded to the nearest integer before formatting. Fractional digits can be formatted by using the K qualifier and putting the appropriate number of Z's and 9's after the decimal point in the picture.
Qualifiers: K,B (Z,C,L will cause a DOMAIN ERROR) Decorators: M,N,P,Q,R,S Substitutable characters: Leading 0's, the overflow
*, and the Z's and 9's used in the picture
'G<DATE IS 99/99/9999>'⎕FMT 08031985
DATE IS 08/03/1985
'G<TEL: (999) 999-9999>' ⎕FMT 0719228866
TEL: (071) 922-8866
'B K2 G< ZZZ POUNDS AND ZZ PENCE>' ⎕FMT 8.23 12.86 0 2.52
8 POUNDS AND 23 PENCE
12 POUNDS AND 86 PENCE
2 POUNDS AND 52 PENCE
- integer format
Syntax: In n is the total field width in the result.
Format a number from the current column in the right argument as an integer after rounding. A field width of 0 will cause the field to be empty.
Substitutable characters: Leading 0s, commas
'I4' ⎕FMT ⍳4
'I6,I3,CI6' ⎕FMT 1 3⍴12 7896 48723.4
- move to absolute position
Syntax: Tn n is the absolute position, reckoned from the left margin. or T
Move to print position n. If T alone is used the cursor or print-element is moved to the 'first free' position to the right. The latter form is used only in very complicated formatting exercises involving backspacing.
NB: This operation does not require a column of data in the right argument.
Substitutable characters: None
'I3,T3,I2' ⎕FMT 1 2⍴678 92
'I10,T1,I3,T,I2'⎕FMT 1 3⍴789 672 12
- move to relative position
Syntax: Xn n is the number of positions the cursor or print-head is to be moved relative to the current position. n may be positive (right move) or negative (left move).
If m is current print position: move to print position
NB: This operation does not require a column of data in the left margin.
Substitutable characters: None
'I3,X2,I2' ⎕FMT 1 2 ⍴ 789 67
'I3,X¯1,I2' ⎕FMT 1 2 ⍴789 67
Qualifiers and Decorators
Qualifiers and decorators are used with the format codes to provide further tailoring to specific needs. All qualifiers and decorators come before the format codes and after the replication factor (if supplied).
B - blank all zero results. Allow background text to show through.
C - put commas after each third digit to the left of the decimal
Kn - multiply the right argument by 10 to the power n before
L - left justify the result field using blanks to fill in positions
to the right of the right-most formatted digit. This does not
allow background text to show through unless the B qualifier
is used and the value being formatted is 0.
Z - put in leading zeros. If the C qualifier is used, however,
commas will not be inserted between any of the leading
M⎕TEXT⎕ - put TEXT immediately in front of negative numbers. If the Z
qualifier is being used, the text will begin at the left of the
field and overlay as many leading zeros as there are characters
N⎕TEXT⎕ - put TEXT immediately after negative numbers.
P⎕TEXT⎕ - put TEXT before non-negative numbers (otherwise as M)
Q⎕TEXT⎕ - put TEXT after non-negative numbers (otherwise as N)
R⎕TEXT⎕ - put in background TEXT to fill any unused positions in the
field (eg. In cheque protection).
S⎕TEXT⎕ - substitute standard characters. TEXT must consist of pairs of
characters, where the second of each pair is to replace all
occurrences of the first.
B K2 G< ZZ9 DOLLARS AND 99 CENTS>
A ⎕FMT 8.23 12.86 0 2.52
8 DOLLARS AND 23 CENTS
12 DOLLARS AND 86 CENTS
2 DOLLARS AND 52 CENTS
<TOTAL >,C M⎕(⎕ N⎕)⎕ Q⎕ ⎕ I8,X2,CF 12.2,X2,ZE12.3
100 1321321.2 ¯12332.7
¯19232.563 ¯232 212.219
B ⎕FMT C
TOTAL 100 1,321,321.20 ¯001.23E4
TOTAL ( 19,233) ¯232.00 0002.12E2
In the last example, the literal string 'TOTAL ' was placed between
> delimiters to insert characters into the result. Note that no corresponding column was required in the right argument. When
⎕FMT scans its left argument it moves from left to right. If a left delimiter is found, all text up to the first corresponding right delimiter, including commas and other delimiters, is treated as a literal:
'⎕THIS IS AN <INTEGER>:⎕, I5' ⎕FMT 47
THIS IS AN <INTEGER>: 47