# System Function FMT

Jump to navigationJump to search

## 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 Rabenhorst1.

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

APL code for Magic Function #BoxFMT(July 2015):

```   2 ⎕CR '#BoxFMT'
Z←Z #BoxFMT R;RD;LD;D
LD←⍕(0≠⍴⍴R)/¯1↑⍴R
RD←⍕⍪¯1↓⍴R
RD←(+/RD=' ')⌽RD
D←¯2+⍴⍴Z
:if D>0
:while 2<⍴⍴Z
Z←,[¯3 ¯2] Z,[¯2]' '
:endwhile
Z←(-D)↓[0]Z
:endif
Z←(¯2↑1,⍴Z)⍴Z ⋄ Z←((⍴Z)⌈(¯1↑⍴RD),⍴LD)↑Z
:if 1≥⍴⍴R
RD←((1↑⍴Z),1)⍴'│'
:else
RD←⍉(1↑⍴Z)↑[1] RD ⋄ RD[(,RD=' ')/,⍳⍴RD]←'│'
:endif
RD←'┬'⍪RD⍪'┴' ⋄ RD[0 ¯1;0]←'┌└'
Z←Z,'│'
D←≡R
:if 1<D
D←⍕D
Z[⍳-⍴D;¯1]←⌽D
:endif
Z←'─'⍪Z⍪'─'
Z[0 ¯1;¯1]←'┐┘'
Z[0;⍳⍴LD]←LD
Z[¯1;0]←Type
Z←RD,Z
```

For a list of all magic functions implemented in NARS, see ⎕NL 23 24

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

Quad FMT sample dyadic usage:

```      'CI 14' ⎕FMT ⎕WA  ⍝ C=use commas(",") modifier; I=Integer format; 14=reserve 14 spaces.  ⎕WA=free workspace area.
50,825,084,928           ⍝ Result shown by APL, commas inserted. Easily readable, over 50 gigabytes of free work area.
'CI 13' ⎕FMT ⎕WA  ⍝ Same as 1st example, but too FEW spaces allowed for(only 13); hence, APL returns all asterisks(*).
*************
'CF 14.2' ⎕FMT 44888.769  ⍝ C=Commas modifier, F=Floating point number format; 14 reserved spaces; 2 decimals. .769 to .77
44,888.77

'G<99/99/9999>' ⎕FMT 03042015  ⍝ G<...>=General picture formatting(like Cobol Gen picture fmt), in this case formatting for a date!
03/04/2015
⍴('G<99/99/9999>' ⎕FMT 03042015) ⍝ Note that OUTPUT from ⎕FMT is a Char/string MATRIX (NOT a vector), in this case a ONE ROW matrix.
1 10

'G<(999) 999-9999>' ⎕FMT 8005126200 8004443300  ⍝ Formatting for telephone numbers.  Output = 2-row character matrix.
(800) 512-6200
(800) 444-3300
```

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 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 Negative left decoration N Negative right decoration O Zero substitution On Specific value substitution where n may be negative as in O¯2 or O-2 P Positive and zero left decoration Q Positive and zero right decoration R Background fill S 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.

Note: ⎕FMT is available as both a monadic and dyadic form system function, you cannot assign a value to it.

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

 See Also System Commands System Variables and Functions Operators

 Keyboard A+S ⍪ ≡ ≢ ⍒ ⍋ ⌽ ⍉ ⊖ ⍟ ⍱ ⍲ ⍠ ⌹ Alt ⋄ ¨ ¯ < ≤ ∅ ≥ > ≠ ∨ ∧ × ÷ Sh ~ ! @ # \$ % ^ & * ( ) _ + Key ` 1 2 3 4 5 6 7 8 9 0 - = A+S ⍷ √ ⍨ ⍸ ⍥ ⍣ ⍞ ⍬ ⊣ Alt ? ⍵ ∊ ⍴ § ↑ ↓ ⍳ ○ π ← → ⊢ Sh Q W E R T Y U I O P { } | Key q w e r t y u i o p [ ] \ A+S ∫ ∂ ⌻ ⍢ ⍙ ⍤ ⍫ ⌷ Alt ⍺ ⌈ ⌊ ∞ ∇ ∆ ∘ ‼ ⎕ ⍎ ⍕ Sh A S D F G H J K L : " Key a s d f g h j k l ; ' A+S ⊆ ⊇ ⍡ ⍭ ⊙ Alt ⊂ ⊃ ∩ ∪ ⊥ ⊤ ⍦ ⍝ ⍀ ⌿ Sh Z X C V B N M < > ? Key z x c v b n m , . /
 NARS 2000 LangToolBar ← → + - × ÷ * ⍟ ⌹ ○ ! ? √ | ⌈ ⌊ ⊥ ⊤ ⊣ ⊢ ≡ ≢ < ≤ = ≥ > ≠ ∨ ∧ ⍱ ⍲ ↑ ↓ ⊂ ⊃ ⌷ ⍋ ⍒ ⍳ ∊ ⍸ ⍷ ∪ ∩ ⊆ ⊇ ~ § π .. , ⍪ ⍴ ⌽ ⊖ ⍉ / \ ⌿ ⍀ ⊙ ¨ ⍨ ⍤ ⍣ ⍡ ⍥ ⍦ ⍥ . ∘ ⍠ ‼ ⌻ ∂ ⍞ ⎕ ⍎ ⍕ ⋄ ⍝ ∇ ∆ ⍙ _ ⍺ ⍵ ¯ ⍬ ∞ ∅ Second Row i j k i j k l g p r v x

 See Also System Commands System Variables and Functions Operators

 Keyboard A+S ⍪ ≡ ≢ ⍒ ⍋ ⌽ ⍉ ⊖ ⍟ ⍱ ⍲ ⍠ ⌹ Alt ⋄ ¨ ¯ < ≤ ∅ ≥ > ≠ ∨ ∧ × ÷ Sh ~ ! @ # \$ % ^ & * ( ) _ + Key ` 1 2 3 4 5 6 7 8 9 0 - = A+S ⍷ √ ⍨ ⍸ ⍥ ⍣ ⍞ ⍬ ⊣ Alt ? ⍵ ∊ ⍴ § ↑ ↓ ⍳ ○ π ← → ⊢ Sh Q W E R T Y U I O P { } | Key q w e r t y u i o p [ ] \ A+S ∫ ∂ ⌻ ⍢ ⍙ ⍤ ⍫ ⌷ Alt ⍺ ⌈ ⌊ ∞ ∇ ∆ ∘ ‼ ⎕ ⍎ ⍕ Sh A S D F G H J K L : " Key a s d f g h j k l ; ' A+S ⊆ ⊇ ⍡ ⍭ ⊙ Alt ⊂ ⊃ ∩ ∪ ⊥ ⊤ ⍦ ⍝ ⍀ ⌿ Sh Z X C V B N M < > ? Key z x c v b n m , . /
 NARS 2000 LangToolBar ← → + - × ÷ * ⍟ ⌹ ○ ! ? √ | ⌈ ⌊ ⊥ ⊤ ⊣ ⊢ ≡ ≢ < ≤ = ≥ > ≠ ∨ ∧ ⍱ ⍲ ↑ ↓ ⊂ ⊃ ⌷ ⍋ ⍒ ⍳ ∊ ⍸ ⍷ ∪ ∩ ⊆ ⊇ ~ § π .. , ⍪ ⍴ ⌽ ⊖ ⍉ / \ ⌿ ⍀ ⊙ ¨ ⍨ ⍤ ⍣ ⍡ ⍥ ⍦ ⍥ . ∘ ⍠ ‼ ⌻ ∂ ⍞ ⎕ ⍎ ⍕ ⋄ ⍝ ∇ ∆ ⍙ _ ⍺ ⍵ ¯ ⍬ ∞ ∅ Second Row i j k i j k l g p r v x