System Function FMT
Monadic Function
|
||||
| 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 Rabenhorst1.
1 "The Compact Display of Arbitrary Nested Arrays" D. A. Rabenhorst (IBM), APL88 Conference Proceedings, pp 272-277, ACM.
Dyadic Function
|
||||
| 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 | |||||||||
