⍺ Picture format

Displays the numbers in the right argument according to the instructions in the left argument.

Numeric left argument

⍺ can be used in a similar way to the two-argument form of ⍕. (See ⍕ for more information and examples.) The main differences are:

(a) If a number is too big for the field specified, '*'s are displayed.

(b) If the left argument is a single number, it specifies the number of characters in the field and no decimals are displayed.

(c) If the left argument consists of the numbers 1 or 2, only the absolute value of the data will be displayed.

(d) If any field width is specified to be 0, the result will not contain that column.

Character left argument

With ⍺ you can also define the way the data is to look by using editing symbols to build up the pattern you require. This 'picture' is enclosed in single quotes and forms the left-hand argument. Each number in the right-hand argument is displayed in the way defined by the picture. If the right argument is an array, each field in the specification is taken to apply to all of the relevant columns.

You can have one picture for all the numbers on the right, or several pictures, one for each number. If several pictures are defined, each one must be separated by a semicolon (;). If there is nothing between two semicolons, the previous picture repeats. Any valid APL character except ; may appear in the left argument.

Numeric Field Specification (9 Z)

The main editing symbols are Z and 9. If a 9 is used in the picture, a digit is displayed at that position; if the position is blank, a zero is displayed. Z causes a digit, if present, to be displayed, but it does not display leading zeros. If no 9 is found in a picture, full zero suppression is assumed, but a single leading 9, or a 9 with Z on either side of it has the special effect of forcing a display only if there is any significance to the right of the 9. More than one leading or embedded 9 causes a DOMAIN ERROR. A space in the picture causes a corresponding space in the number and a point . in the picture inserts a decimal point if required by the format specification. Absence of a decimal point means that none will be printed.

             '9999' ⍺ 101 15
       01010015                      (Each number fills 4 positions - no
                                      space between numbers was allowed for)
             ' 9999' ⍺ 101 15
        0101 0015                    (The space in the picture is put at the
                                      beginning of each number. So if we
                                      represent spaces by dots, we have:
                                      .0101.0015)

             'ZZZZ' ⍺ 101 15 0 10
       101  15      10               (Z suppresses non-significant zeros)

             'ZZZ9.99 ' ⍺ 11  12.1  13  .2
       11.00   12.10   13.00    0.20 (Three leading zeros are suppressed,
                                      but a zero in the digits position is
                                      displayed. The point is inserted)

             'ZZZ9.ZZ' ⍺ 10 .3 .03 0 .009 .003
       10.00   0.30   0.03          0.01  (The 4th and 6th numbers do not print)

A single or embedded residue symbol (|) behaves exactly like a leading or embedded 9 except that it forces significance in the field immediately to the right. Only one | may be used, and no 9s.

                  'ZZZ|.ZZ' ⍺10 .3 .03 0 .009 .003
       10.00    .30    .03           .01  (Note that there are no zeros
                                           before the '.' this time)

The floor symbol (⌊) used in a field specification behaves like the decimal point (.) except that it specifies where the point will print, rather than where it actually is. If a ⌊ symbol is used in a specification, the decimal point of the right argument is assumed to be at the right of the field, and the fractional part of the right argument is never displayed.

             'ZZZZZ9⌊99'⍺123456.78
       1234.57                       (The number is treated as 123456 and the
                                      . inserted before the last 2 digits)

Commas and other text characters will print where indicated if significance has started before they are reached. Text following the last Z or 9 will only print if the value of the field is negative. If the picture is too small for the formatted value, *s are used to fill the field.

             'ZZZ,ZZ9.99;ZZ9.99 CR;ZZZ,ZZZ.ZZ' ⍺ 101789.356 ¯22 7777777
       101,789.36 22.00 CR**********

             'Z9/99/99'⍺011086
       1/10/86                       (A date formatter)

Text may be placed between columns of the specification, and will repeat on every output line. The text must be placed within quotes (') and any number of such fields may be specified.

             'ZZ9;''  VERSUS  '';ZZ9' ⍺ 2 2⍴1 2 3 4
         1  VERSUS    2
         3  VERSUS    4

Negative numbers, floating characters, fill characters

The minus sign is not displayed unless specified in the picture (nor indeed is the plus sign). A +, ¯, or - put at the beginning of the picture will cause the specified sign to be displayed where applicable. Negative numbers can alternatively be displayed in brackets, if brackets are placed round the picture. The symbols [], (), ∆⍪ and ⊢⊣ are treated as alternative ways of displaying the minus sign.

The + sign or the various negative signs are shown at the very beginning of the relevant field. If you want the sign to appear immediately before the first displayed digit, use two of the signs at the beginning of the picture. This is known as 'floating' the character. Any character may be floated by placing it twice at the beginning of the picture. The second declaration is converted to a Z internally after the 'float' is noted.

             '-ZZ9.99 ' ⍺ 17 ¯2.3
       17.00 -  2.30

             '((ZZ.99) ' ⍺ 17 ¯2.3
       17.00 (2.30)

             '$$ZZ9.99 ;$ZZ9.99 '⍺ 35.45 33.75
       $35.45 $ 33.75                (Floating versus fixed character)

If a character is put at the beginning of a picture and followed by the | symbol, it will be used as the fill character instead of the normal blank. Any character except . and | may be used as a filler, and the declaration does not affect the resultant field length.

             '*|$$ZZ,ZZ9.99 O/D ' ⍺ ¯1174.57 303.75
       **$1,174.57 O/D ****≤303.75*****