⎕FMT Formatting Function

(See also ⍺ (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

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

Phrase types

     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
             n
     Xn  -   offset the result of subsequent phrases by n columns from current
             location

A - 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 * character).

Qualifiers: None
Decorators: R
Substitutable Characters: * in overflow

             '4A1,A3'⎕FMT 2 5⍴'ABCDEFGHIJ
       ABCD  E
       FGHI  J
             'A4'⎕FMT 4 6            (A vector is treated as a 1 column
       ****                           matrix, and overflow occurs with a
       ****                           numeric argument.)

E - 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
        1.000E2
        7.698E23
       ¯4.000E¯3

             'E8.1,E8.0'⎕FMT 1 2⍴16 .02
       2E1     E¯2

F - 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
            98.67
       ¯12,796.50
             'S<,..,>CF10.2'⎕FMT 98.672 ¯12796.497
            98,67
       ¯12.796,50
             'F4.0'⎕FMT 6
       6.

G - 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

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

Qualifiers: B,C,K,L,Z
Decorators: M,N,P,Q,R,S
Substitutable characters: Leading 0s, commas

             'I4' ⎕FMT ⍳4
           1
           2
           3
           4
             'I6,I3,CI6' ⎕FMT 1 3⍴12 7896 48723.4
           12***48,723
             'I3'⎕FMT 2.6792
       3

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

Qualifiers: None
Decorators: None
Substitutable characters: None

             'I3,T3,I2' ⎕FMT 1 2⍴678 92
       6792
             'I10,T1,I3,T,I2'⎕FMT  1 3⍴789 672 12
       672    78912

X - 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 m+n.


NB: This operation does not require a column of data in the left margin.

Qualifiers: None
Decorators: None
Substitutable characters: None

             'I3,X2,I2' ⎕FMT 1 2 ⍴ 789 67
       789  67
          'I3,X¯1,I2' ⎕FMT 1 2 ⍴789 67
       7867

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

    Qualifiers:

     B   -        blank all zero results.  Allow background text to show through.

     C   -        put  commas  after each third digit to the left of the  decimal
                  point
     Kn  -        multiply  the  right  argument  by 10 to  the  power  n  before
                  formatting.
     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
                  zeros.

     Decorators:

     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
                  in TEXT.
     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.

             A
       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
             B
       <TOTAL >,C M⎕(⎕ N⎕)⎕ Q⎕ ⎕ I8,X2,CF 12.2,X2,ZE12.3
             C
          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

Literals

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