Forth Programmer’s Handbook

that would be output by . is used to determine the number of leading blanks. No trailing blanks are printed. If the magnitude of the number to be printed prevents printing within the number of spaces specified, all digits are displayed with no leading spaces in a field as wide as necessary. “dot-R”

Similar to .R, but unsigned. Display the unsigned single-precision integer u with leading spaces to fill a field of width +n, right-justified. “U-dot-R”

2.4.2 Pictured Number Conversion

Forth contains words that allow numeric quantities to be displayed through use of a pictured format control. These words allow specification of field sizes, embedded punctuation, etc.

In Forth, the description of the desired output format starts with the rightmost character and continues to the left. Although this is the reverse of the method apparently used in other languages, it is the actual conversion process in all languages.

These words are used to convert numbers on the stack into ASCII character strings formatted according to the picture specifications. These strings are

54 Forth Fundamentals

Forth Programmer’s Handbook

built in a temporary area in memory, which is large enough to accommodate at least 66 characters of output (32-bit CPUs) or 34 characters (16-bit CPUs). After the picture conversion, the address of the beginning of the string, and the count of the number of characters in it, are passed to the user. At this point, the converted string can be printed at the terminal with TYPE or can be used in some other way.

The standard numeric output words (see previous section) also use this temporary region in the user’s partition. As a result, these words may not be executed while a pictured output conversion is in process (e.g., during debugging). Furthermore, the user may not make new definitions during the pictured conversion process, since this may move the area in which the string is being generated.

References Standard numeric output, Section 2.4.1

TYPE, Section 3.3.3

2.4.2.1 Using Pictured Numeric Output Words

These words provide control over the conversion of binary numbers into digits. This section describes only pictured words which result in numeric output (digits); the following sections describe output of non-numeric punctuation, such as periods and commas. Throughout the number-conversion process, the number being operated on remains on the stack, where it is repeatedly divided by BASE as digits are converted; it is finally discarded by #> at the end of the process.

As an example of the use of these words, consider a definition of the standard Forth word . (“dot”):

: . ( n -- ) DUP ABS 0 <# #S ROT SIGN #> TYPE SPACE ;

DUP ABS leaves two numbers on the stack: the absolute value of the number is on top of the original number, which is now useful only for its sign. 0 adds a cell on top of the stack, so that the 0 cell and the ABS cell form the required double-precision integer to be used by the <# … #> conversion routines. <# initializes the conversion process; then #S and SIGN assemble the string. #> completes the conversion and leaves the address and count of the ASCII string on the stack, suitable as input to TYPE.

Forth Fundamentals 55

Forth Programmer’s Handbook

To print a signed double-precision integer with the low-order three digits always appearing, regardless of the value, you could use the following definition:

The SWAP OVER DABS phrase establishes the signed value beneath the absolute value of the number to be printed, for the word SIGN. The sequence # # converts the low-order two digits, regardless of value. The word #S converts the remaining digits and always results in at least one character of output, even if the value is zero.

From the time when the initialization word <# executes until the terminating word #> executes, the number being converted remains on the stack. It is possible to use the stack for intermediate results during pictured processing but any item placed on the stack must be removed before any subsequent picture editing or fill characters may be processed.

Convert digits from ud1 repetitively until all significant digits in the source item have been converted, at which point conversion is completed, leaving ud2 (which is zero). Must be used after <# and before #>. #S always results in at least one output character, even if the number to be converted is zero.

“number-sign-S”

56 Forth Fundamentals

Complete the conversion process after all digits have been converted. Discard the (presumably) exhausted double-precision number, and push onto the stack the address of the output string, with the count of bytes in this string above it.

“number-bracket”

References TYPE, Section 3.3.3

2.4.2.2 Using Pictured Fill Characters

In addition to pictured numeric output, it is possible to introduce arbitrary fill characters (or punctuation) into the output string at any point through the use of HOLD. HOLD requires as a parameter the numeric value of the ASCII character to be inserted. Thus,

2F HOLD

(value given in hex) or

[CHAR] / HOLD

(value computed by [CHAR] from the ASCII character following)

inserts the character / into the output string at the point where HOLD is executed. The phrase <value> HOLD may be executed as many times as desired in a given output conversion sequence.

If fill characters are likely to be used in several definitions, you may wish to add specific commands for them. The following format may be used for such

adefinition:

:'<name>' <char-value> HOLD ;

where char-value is the ASCII value of the character in the current radix and

Forth Fundamentals 57