Part of the job of the interpreter in Forth is to look up words in the dictionary. When a word is not found, the interpreter attempts to convert the word to a number and put it on the stack. Win32Forth has a simple but effective number conversion system that allows pluggable words to process numbers. Several number conversions are provided with the installed system.

Standard numbers and double numbers (base 2 through 36) are supported, and the maximum values for each is specified in ENVIRON.F (environment word set). Optionally, numbers may be prefixed with a negative sign (-). Floating point numbers are supported in base 10 (DECIMAL).

Win32Forth supports a set of extended numbers, commonly supported by Forths such as gforth.

Binary numbers can be entered in any base by prefixing the number with a % sign, and an optional negative sign (-) either before or after the %. The following are valid binary numbers with their equivalent in decimal;

%0 (0)

%10101 (21)

-%01 (-1)

%-101 (-5)

Decimal numbers can be entered in any base by prefixing the number with an & sign, and an optional negative sign (-) either before or after the &. The following are valid decimal numbers;

&193

&-22

-&35

Hex numbers can be entered in any base by prefixing the number with a $ sign, and an optional negative sign (-) either before or after the $. The following are valid hex numbers with their equivalent in decimal;

$123 (291)

$FFFFFFFF (-1)

$-245 (-581)

-$34 (-52)

Additionally, any hex string followed with an h or H, or the string 0x followed by a hex string are interpreted as hex numbers. The hex string can be prefixed with an optional negative sign (-). The following are valid hex numbers with their equivalent in decimal;

0x123 (291)

FFFFFFFFh (-1)

-245h (-581)

-0x34 (-52)

0x-34 (-52)

Floating point numbers can be entered in any base by prefixing the number with the F# word (not a leading string, but a separate word). For example; F# 1.0e-2

IP addresses of the form a.b.c.d can be entered in any base. However, they must not be signed, and they must not have a leading base modifier (as in %, $ or &).

The chain number conversion technique allow number conversion to be easily extended to support additional forms of number conversion.

Win32Forth uses chains to provide a pluggable
number conversion system. The number conversion chain is called
number?-chain. Each number conversion routine on
the chain is sent a string ( addr len ) and can
attempt to convert the number. If the conversion fails the word performs a
-1 THROW to indicate that it can't convert the
string; the next word is then tried until success or the chain is exhausted. If
the chain is exhausted, then a -13 THROW
(undefined) is executed.

If conversion succeeds, then a double number **must** be returned. If the
number is truly a double, then set the DOUBLE?
flag to true, otherwise the number will be considered a single, and the high
order cell will be discarded. For numbers with a decimal point, the value
DP-LOCATION can be set to indicate where it's
located in the input string. If desired, the flag -VE-NUM?
can be set to true; the number will be negated before it is used. This is to
avoid keeping flags to indicate that the sign has been detected in each routine
separately.

Floating point numbers are returned in the floating point stack; there is no
return value, and the variable FLOAT? is set. See
FLOAT.F for details. **NOTE** - even floating
point routines must return a double value; it's ignored and dropped if
FLOAT? is set.

The stack effects of any number conversion word must be
( addr len -- d ) where addr len is the
input string, and d is the double number output.
If you can't convert your form of string input, then execute a
-1 THROW. To install your routine, you will need
to specify

number?-chain chain-add <your-number-conversion-word>

to add your word to the end of the chain. Your word will be called after all the built-in number conversions have been executed; to be executed before any of the standard words, specify

number?-chain chain-add-before <your-number-conversion-word>

Document $Id: p-numconv.htm,v 1.1 2005/05/16 20:56:24 alex_mcdonald Exp $