⍕ Format by example

Two-argument form  See also one-argument form Format

The right argument must be a simple numeric array.

Like the one-argument form, this version of ⍕ also converts numeric data to characters. The right argument is formatted according to the instructions in the left argument which is a simple character vector. The left argument is used as a pictorial model of the format which should be applied to the left argument.

The left argument can either be one field, in which case that field is used to format each element or column of the right argument, or a series of fields to be applied, one to each column of the right argument. Numbers will be rounded to fit into their formatted layout.

A field is made up of characters drawn from the characters '0123456789' and . (full stop), , (comma) and a special 'print-as-blank' character, usually _ and set by ⎕FC[5]. Fields are separated by either one or more spaces or by a character identified as a field separator by a special indicator in the field. Any other characters used in the left argument are treated as decorator┐ characters. Decorators may appear adjacent to the characters defining a field or within a field.

In common with other formatters, format by example permits decorator characters to:

- Appear always

- Appear if the number being formatted is negative

- Appear if the number being formatted is positive

- Float against the number being formatted, that is appear immediately next to the front or back of the number when it is formatted

The standard character used for format by example fields is 5, which is used to indicate simple formatting with removal of leading zeroes and suppression of trailing blanks. Zero values print as blanks.

             '55.55' ⍕22.234 1.398 11.00
       22.23 1.4 11                  (Trailing blanks in 11 suppressed)
             '55.55 5.555 55.55 55'⍕22.234 1.398 0.00 11.0
       22.23 1.398       11          (0 prints as blank)
             '555,555,555.55'⍕1234567.89
         1,234,567.89                (The , only appears between digits, leading
                                      blanks are suppressed)

The control character 5 does not print positive or negative indicators (+ or -) and indeed will not accept negative numbers.

             '55.55'⍕ ¯10
       DOMAIN ERROR
             '55.55'⍕¯10
             ^

Decorator characters which appear at the beginning or end of a field specification without special control characters will print where they appear in the left argument, they will not float.

             ' SALARY IS : $555,555,555.00' ⍕ 1234567.95
       SALARY IS : $  1,234,567.95   ($ decorator does not float)

Negative numbers and floating decorators

The field control characters 1 and 2 should be used if negative numbers are likely to be found in the right argument of ⍕. They will control any decorators which appear at the beginning or end of a field specification. These control characters will print their associated decorators if the number being formatted is negative (the character 1) or positive (the character 2). In addition the decorator will float against the number being formatted.

             '¯155.55' ⍕10.1 ¯12.346 11.5
         10.1  ¯12.35  11.5          (Negative numbers with high-minus)
             '(155.55)' ⍕10.1 ¯12.346 11.5
         10.1  (12.35) 11.5          (Negative numbers in brackets)
             ⍴'(155.55)'⍕10.1 ¯12.345 11.5
       24                            (Overall field size is the same, floated
                                      characters which do not appear are replaced
                                      by spaces)
             '+255,555,555.55'⍕ ¯101.34 1000234 13.1
                101.34  +1,000,234            +13.1

The control character 3 will purely float a decorator against a number being formatted, and will not accept negative numbers.

             'THE BALANCE IS : $555,555.55' ⍕ 10027.34
       THE BALANCE IS : $ 10,027.34
             'THE BALANCE IS : $555,555.53' ⍕ 10027.34
       THE BALANCE IS :  $10,027.34

In the example above the currency sign is floated against the amount. Note that the overall field length is the same and that decorators which are not next to the field specification do not float .

If the control characters 1, 2 or 3 appear in a field specification on their own they will apply to the decorators on both sides of the field. If two of these characters appear in a field specification, then each will apply to the decorators on its side of the number. In the example below, 1 acts with the minus sign on the left, 2 acts with the characters CR on the right.

             '-155,555.52CR'⍕ 101.34 ¯1000.29 15367.346
            101.34CR  -1,000.29    15,367.35CR

Finally, the control character 4 can be used to switch off the effect of the control characters 1, 2 or 3. In the example below, the 4 switches off the effect of the 1 such that, on the right of the numbers, the characters DEG always appear.

             '-154.5DEG  ' ⍕95.8 32.5 ¯27.2
       95.8DEG    32.5DEG   -27.2DEG

Contrast the effect when the character 4 is omitted

             '-155.5DEG  '⍕95.8 32.5 ¯27.2
         95.8       32.5      -27.2DEG

In this example, the characters DEG print when the number is negative, under the control of the character 1.

Leading and trailing zeroes

The printing of leading and trailing zeroes can be forced by the control characters 0 and 9. One of these control characters placed in a field will indicate that 0s should be used up to that position. The effect of the 0 and 9 only differs in their treatment of the number 0. Control character 0 will print the appropriate number of 0s, control character 9 will use blanks.

             '55.55  '⍕21.1 27.25 33
       21.1   27.25  33              (Trailing zeroes suppressed)
             '55.50  '⍕21.1 27.25 33
       21.10  27.25  33.00           (Always print to two decimal places)
             '55.5055  '⍕21.1 27.12345 33
       21.10    27.1235  33.00       (0 only forces printing of zero up to its
                                      position in the field)
             '55.00  '⍕21.1 0 33
       21.10    .00  33.00           (Control character 0 prints value 0)
             '55.59  '⍕21.1 0 33
       21.10         33.00           (Control character 9 does not)
             '055,555.50' ⍕ 1000.1
       001,000.10                    (Leading zeroes forced)

Cheque protection

Control character 8 fills empty portions of a field with the contents of ⎕FC[3] (by default the * character).

             'TOTAL AMOUNT $385,555,555.00'⍕1000
       TOTAL AMOUNT $******1,000.00

Alternative end of field delimiter and blanks within numbers

It is sometimes useful to format numbers with no spaces between them. This may be achieved by use of control character 6 which can be used to mark the end of a field.

             '5556/06/05 '⍕3↑⎕TS     (Three fields in left argument to ⍕)
       1991/06/14

Contrast the example above with the next example which inserts a decorator within a number being formatted.

             '0555/55/55 '⍕19910614  (Only one field in left argument to ⍕)
       1991/06/14

The 'print-as-blank' character (⎕FC[5] and _ by default) can be used to insert blanks between the digits of a number without ending the field.

             '5.555_555_555_555_555  '⍕ ○1
       3.141 592 653 589 790

Using ⎕FC with format by example

Certain elements in the system variable ⎕FC Format Control can influence the display generated by ⍕ when acting as 'format by example'. In index origin 1:

⎕FC[1] specifies the character used for the decimal point. (. by default).

⎕FC[2] specifies the character used for the thousands indicator. (, by default).

⎕FC[3] specifies the fill character for empty portions of a field when 8 is used in the field specification. (* by default).

⎕FC[4] specifies the overflow character used for numbers too wide for the column width specified. (0 by default, causing a DOMAIN ERROR on overflow).

⎕FC[5] specifies the character to be used in the field specification to indicate that a blank should be inserted between the digits of a number. (The default is _).

             ⎕FC                     (Default setting for ⎕FC)
       .,*0_¯
             '55.55' ⍕1000           (DOMAIN ERROR on field overflow)
       DOMAIN ERROR
             '55.55'⍕1000
             ^
             ⎕FC[4]←'*'              (Overflow character set)
             '55.55' ⍕1000
       *****
             ⎕FC[1 2]←',.'           (Reverse characters used for decimal point,
             '555,555.55  '⍕1170.45   thousands indicator)
         1.170,45
             ⎕FC[3]←'|'              (Fill empty positions with |)
             '$855555  '⍕1002
       $||1002