System Function FMT

Monadic Function

Z←⎕FMT R returns a representation of R formatted within boxes.

R is an arbitrary array.

Z is a character matrix which reveals the array structure and types of the elements of R.

For example,

      ⎕fmt ⍳3
┌3────┐
│1 2 3│
└~────┘
      ⎕fmt ⍳¨⍳3
┌3──────────────────┐
│ ┌1┐ ┌2──┐ ┌3────┐ │
│ │1│ │1 2│ │1 2 3│ │
│ └~┘ └~──┘ └~────┘ 2
└∊──────────────────┘
      ⎕fmt 1 1 4⍴23 'abc' '*' (2 3⍴⍳6)
┌┬4────────────────────┐
11    ┌3──┐   ┌3─────┐ │
││ 23 │abc│ * 2 1 2 3│ │
││ ~~ └───┘ ¯ │ 4 5 6│ │
││            └~─────┘ 2
└┴∊────────────────────┘

This function is implemented via the Magic Functions #MonFMT and #Box. The design is based upon ideas from Rabenhorst¹.

¹ "The Compact Display of Arbitrary Nested Arrays" D. A. Rabenhorst (IBM), APL88 Conference Proceedings, pp 272-277, ACM.

Dyadic Function

Z←L ⎕FMT R returns the formatted representation of R as controlled by L.

R is a simple array or a nested vector of simple arrays — this is the array to be formatted.

L is a character scalar or vector — this is the format specification.

Based upon the original STSC implementation in the early 1970s, this function performs a wide variety of formatting tasks such as Integer, Decimal, Exponential, Alphabetic, and Picture formatting.

The left argument consists of zero or more format phrases each separated by a comma and zero or more spaces. A format phrase consists of an optional Repetition factor, zero or more Qualifiers, zero or more Decorators, a Phrase Type, and possibly width or other numeric information depending upon the Phrase Type.

The list of Phrase Types consists of

Aw	Character format
Ew.s	Exponential format
Fw.d	Decimal format
G<picture>	Picture format
Iw	Integer format
Rw.d	Rational format
T	Rightmost positioning
Tp	Absolute positioning
Xw	Relative positioning where w may be negative as in X¯3 or X-3

The list of Qualifiers consists of

B	Blank if zero
C	Comma (thousands separator) insertion
Kn	Scaling by 10n where n may be negative as in K¯3 or K-3
L	Left justification
Z	Zero fill

The list of Decorators consists of a Decorator Type followed by text, where the text is surrounded by delimiters which come in pairs such as

'...'
"..."
⎕...⎕
⍞...⍞
¨...¨
<...>
⊂...⊃

The list of Decorators consists of

M<text>	Negative left decoration
N<text>	Negative right decoration
O<text>	Zero substitution
On<text>	Specific value substitution where n may be negative as in O¯2<text> or O-2<text>
P<text>	Positive and zero left decoration
Q<text>	Positive and zero right decoration
R<text>	Background fill
S<text>	Symbol substitution

Within a Format Phrase, Qualifiers and Decorators may appear in any order, and may be separated from each other and the Phrase Type by zero or more spaces.

Character Format Phrase

Form: rqdAw

where r is an optional repetition factor, q is an optional qualifier (L only is allowed), d is an optional decorator (R and S are allowed), and w is the field width in which each character is placed, right- or left-justified as per the absence/presence of the L qualifier.

Exponential Format Phrase

Form: rqdEw.s

where r is an optional repetition factor, q is an optional qualifier (B, K, L, and Z are allowed), d is an optional decorator (M, N, O, P, Q, R, and S are allowed), w is the field width, and s is the number of significant digits displayed.

Decimal Format Phrase

Form: rqdFw.d

where r is an optional repetition factor, q is an optional qualifier (B, C, K, L, and Z are allowed), d is an optional decorator (M, N, O, P, Q, R, and S are allowed), w is the field width, and d is the number of decimal digits displayed.

Picture Format Phrase

Form: rqdG<text>

where r is an optional repetition factor, q is an optional qualifier (B and K are allowed), d is an optional decorator (M, O, P, R, and S are allowed), and text is the pattern for the picture format.

Integer Format Phrase

Form: rqdIw

where r is an optional repetition factor, q is an optional qualifier (B, C, K, L, and Z are allowed), d is an optional decorator (M, N, O, P, Q, R, and S are allowed), and w is the field width.

Rational Format Phrase

Form: rqdRw.d

where r is an optional repetition factor, q is an optional qualifier (B, C, K, L, and Z are allowed), d is an optional decorator (M, N, O, P, Q, R, and S are allowed), w is the field width, and d is the number of digits displayed in the denominator.

Absolute Positioning Phrase

Form: T or Tp

where p is the absolute (origin-1) position in the line. If p is zero or is omitted, the next character is inserted at the rightmost position of the line.

Relative Positioning Phrase

Form: rXw

where r is an optional repetition factor, w is the (signed) field width, that is the number of spaces to move to the left (w < 0) or right (w > 0).

Symbol Substitution

All but the Positioning Phrases allow alternate symbols to be used in place of certain standard symbols. For example, the thousands separator used by the C qualifier may be substituted with a dot using S<,.>, the decimal point used in numeric format phrases may be substituted with a comma using S<.,>, and both may be substituted at the same time using S<,..,> or S<.,,.>.

In general, the text portion of Symbol Substitution consists of pairs of characters. The first character in each pair consists of a standard symbol which identifies the substitution class and is its default value. The second character in each pair is the (new) symbol to be used when the corresponding standard symbol is called for. Each standard symbol may appear as the first character in a pair at most once in each S Decorator. The order of the pairs is unimportant.

The list of substitution classes along with their (standard symbols) and the Format Phrases/Qualifiers in which they are allowed is as follows:

Overflow (*)	Format Phrases: A, E, F, G, and I
Decimal Separator (.)	Format Phrases: E, F, and I
Thousands Separator (,)	Qualifier: C
Exponent Separator (E)	Format Phrase: E
Zero Fill (0)	Qualifier: Z
Precision Loss Fill (_)	Format Phrases: E, F, and I
Z Character (Z)	Format Phrase: G
9 Character (9)	Format Phrase: G
Rational Separator (r)	Format Phrase: R

Specific Value Substitution

The O decorator may be used to substitute arbitrary text for any given value. Originally, it was designed as a generalization of the B Qualifier to allow arbitrary text to appear in place of a zero, as in O<Zilch>I8. Later, it was generalized even farther to substitute values other than zero, as in O2<Twice>I6 or O3.141592653589793<π>F10.2.

The comparison of incoming data with the specific values is done using Comparison Tolerance.

Unlike all other Decorators, this one may appear multiple times within a single Format Phrase.

System Variables (A value may be assigned to these except for ⎕DM)
⎕ALX	⎕CT	⎕DM	⎕DT	⎕ELX	⎕FC	⎕FEATURE	⎕FPC	⎕IC	⎕IO
⎕LR	⎕LX	⎕PP	⎕PR	⎕PW	⎕RL	⎕SA	⎕WSID
Niladic System Functions (a value cannot be assigned to these)
⎕A	⎕AV	⎕EM	⎕ET	⎕LC	⎕NNAMES	⎕NNUMS	⎕SI	⎕SYSID	⎕SYSVER
⎕T	⎕TC	⎕TCBEL	⎕TCBS	⎕TCESC	⎕TCFF	⎕TCHT	⎕TCLF	⎕TCNL	⎕TCNUL
⎕TS	⎕WA
Monadic or dyadic system functions (a value cannot be assigned to these)
⎕AT	⎕CR	⎕DC	⎕DFT	⎕DL	⎕DR	⎕EA	⎕EC	⎕ERROR	⎕ES
⎕EX	⎕FMT	⎕FX	⎕MF	⎕NAPPEND	⎕NC	⎕NCREATE	⎕NERASE	⎕NINFO	⎕NL
⎕NLOCK	⎕NREAD	⎕NRENAME	⎕NREPLACE	⎕NRESIZE	⎕NSIZE	⎕NTIE	⎕NUNTIE	⎕STOP	⎕TF
⎕TRACE	⎕UCS	⎕VR
Note that quad functions and variables (except for the ⎕A family of functions) are case insensitive