Win32Forth

Number Conversion

Introduction

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 number conversions

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).

Extended numbers

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

Base modifiers % & $

Binary % modifier (in any base)

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 & modifier (in any base)

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 $ modifier (in any base)

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 (in any base)

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

Dotted IP notation (a.b.c.d)

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 &).

Adding your own conversion words

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 $