5.19.2 Formatted numeric output

Forth traditionally uses a technique called pictured numeric
output for formatted printing of integers. In this technique, digits
are extracted from the number (using the current output radix defined by
base), converted to ASCII codes and appended to a string that is
built in a scratch-pad area of memory (see Implementation-defined options). Arbitrary characters can be appended to the string during the
extraction process. The completed string is specified by an address
and length and can be manipulated (TYPEed, copied, modified)
under program control.

All of the integer output words described in the previous section
(see Simple numeric output) are implemented in Gforth using pictured
numeric output.

Three important things to remember about pictured numeric output:

It always operates on double-precision numbers; to display a
single-precision number, convert it first (for ways of doing this
see Double precision).

It always treats the double-precision number as though it were
unsigned. The examples below show ways of printing signed numbers.

The string is built up from right to left; least significant digit first.

<#– core “less-number-sign”

Initialise/clear the pictured numeric output string.

<<#– gforth “less-less-number-sign”

Start a hold area that ends with #>>. Can be nested in
each other and in <#. Note: if you do not match up the
<<#s with #>>s, you will eventually run out of
hold area; you can reset the hold area to empty with <#.

#ud1 – ud2 core “number-sign”

Used within <# and #>. Add the next
least-significant digit to the pictured numeric output
string. This is achieved by dividing ud1 by the number in
base to leave quotient ud2 and remainder n;
n is converted to the appropriate display code (eg ASCII
code) and appended to the string. If the number has been fully
converted, ud1 will be 0 and # will append a “0”
to the string.

#sud – 0 0 core “number-sign-s”

Used within <# and #>. Convert all remaining digits
using the same algorithm as for #. #s will convert
at least one digit. Therefore, if ud is 0, #s will append
a “0” to the pictured numeric output string.

holdchar – core “hold”

Used within <# and #>. Append the character
char to the pictured numeric output string.

signn – core “sign”

Used within <# and #>. If n (a single
number) is negative, append the display code for a minus sign
to the pictured numeric output string. Since the string is
built up “backwards” this is usually used immediately prior
to #>, as shown in the examples below.

#>xd – addr u core “number-sign-greater”

Complete the pictured numeric output string by discarding
xd and returning addr u; the address and length of
the formatted string. A Standard program may modify characters
within the string.

#>>– gforth “number-sign-greater-greater”

Release the hold area started with <<#.

representr c-addr u – n f1 f2 float “represent”

f>str-rdprf +nr +nd +np – c-addr nr gforth “f>str-rdp”

Convert rf into a string at c-addr nr. The conversion
rules and the meanings of nr +nd np are the same as for
f.rdp. The result in in the pictured numeric output buffer
and will be destroyed by anything destroying that buffer.

f>buf-rdprf c-addr +nr +nd +np – gforth “f>buf-rdp”

Convert rf into a string at c-addr nr. The conversion
rules and the meanings of nr nd np are the same as for
f.rdp.