Change the size of a contiguous data space previously allocated by ALLOCATE or RESIZE at a-addr1 to u bytes, where u may be either larger or smaller than the current size of the space. The dictionary pointer is unaffected by this operation. If the operation succeeds, a-addr2 is the aligned starting address of the u bytes of allocated memory, and ior is zero. a-addr2 may be, but need not be, the same as a-addr1. In any case, the contents of the area before and after the RESIZE are preserved up to u bytes or to the original size, whichever is smaller. If a-addr2 is not the same as a-addr1, the region of memory at a-addr1 is released to the system as by FREE. If the resize operation fails, a-addr2 equals a- addr1, the contents of the region of memory at a-addr1 is unaffected, and a sys- tem-dependent non-zero ior code is returned.

3.8 FLOATING POINT

Many Forth applications, especially embedded applications, do not require floating-point routines. Arithmetic that, at first glance, would seem to need floating-point calculations, can often be done more simply, taking less memory and executing faster, when coded with integer operators and with intelligent use of scaling words such as */. The key issue is dynamic range in the variables of interest; if that is limited to fewer than 15 bits, say (as it usually will be

System Functions 103

Forth Programmer’s Handbook

if driven by I/O devices), integer math is usually the better choice.

For some applications, however, floating-point mathematics is essential. Forth defines a full set of optional floating-point operators to support such applications. This section describes the general operators available on systems that comply with Standard Forth systems and support this option. Their implementation is very system specific, and may use floating-point hardware (such as a numeric processor). Your implementation-specific documentation should also be consulted for additional features that may be present (such as hard- ware-stack implementation and additional hardware error trapping on the 80387/80486 floating-point processor).

References Multi-stack notation, Section 2.1.1

3.8.1 Floating-Point System Guidelines

Because floating-point packages may exist on systems with widely varying hardware capabilities, and thus may require different implementation strategies, the basic Standard Forth floating-point word set is flexible in many areas. For details of a particular implementation, you will need to consult CPU-spe- cific documentation. The following guidelines apply:

!The internal representation of a floating-point number, including the format and precision of both significand and exponent, is implementation specific, as is the largest usable floating-point number. For portability, supplementary words are defined that fetch and store to standard 32or 64-bit IEEE floatingpoint number format (see ANSI/IEEE Standard 754 -1985).

!Since the length in memory of a floating-point number is implementation specific, the question of alignment arises. A float-aligned address (stack comment f-addr) is an address where a floating-point number can be accessed. Similarly, a single-float aligned address (sf-addr) or double-float-aligned address

(df-addr) is an address where a single-precision (32-bit) or double-precision (64-bit) IEEE standard floating-point number can be accessed.

!There is a logically separate floating-point stack. Both the width and the depth are implementation specific, but the stack must be able to contain at least six items.

!The floating-point stack may be physically separate, or it may be implemented using the data stack. If it uses the data stack, integer data and floating-point

104 System Functions

Forth Programmer’s Handbook

numbers can become mixed on the same stack. An application program intended to be portable across different implementations (with and without separate stacks) must order its operations carefully. For example, it must clear the floating-point stack of all items before trying to access any data stack items that may be underneath (and vice versa). It must also ensure that arguments to operations using both stacks (e.g., F!) are produced in the correct order. A program can determine whether floating-point numbers are kept on the data stack by passing the string FLOATING-STACK to ENVIRONMENT? (see Section 3.2). If the value returned is zero, the data stack is used; otherwise, the nonzero value indicates the maximum depth of the separate floating-point stack.

!For floating-point input and output, the current base must be DECIMAL; if the base is other than decimal, number conversion or display will not take place. Floating-point numbers to be interpreted by a system that complies with Standard Forth must contain an exponent indicator E or e. For example, one legitimate floating-point representation of the number 12300 is 1.23E4, where 1.23 is the significand and 4 is the exponent.

!Floating-point operators may address memory in data space regions declared with FVARIABLE. These regions are not necessarily contiguous with subsequent regions allocated with , (comma) or ALLOT.

3.8.2 Input Number Conversion

A floating-point number in Forth must contain an E or an e (signifying an exponent), and must begin with a digit (optionally preceded by an algebraic sign). For example, -0.5e0 is valid, but .2e0 is not. A number does not need to contain a decimal point or a value for the exponent; if there is no exponent value, it is assumed to be zero (multiplier of one). Punctuation other than a decimal point is not allowed in a floating-point number.

During number conversion, BASE must be DECIMAL so that numbers such as 1E are not interpreted as hexadecimal digits. If BASE is not DECIMAL, floatingpoint number conversion will not take place.

All the following are valid floating-point numbers:

3.14159E+00 -3E-07 1e 1.E 0.005e02

but the following are double-precision integers (under the enhanced rules

System Functions 105

Forth Programmer’s Handbook

described in Section 1.1.6), not floating-point numbers:

3.14159 -1,000,000.12 -0.003

Input conversion of floating numbers is accomplished by adding an additional level to Standard Forth number conversion routines. First, an attempt is made to convert an input string to a floating-point number. If this succeeds, the number is returned on the floating-point stack; otherwise, control passes to the integer number conversion routines. Thus, 20.E would be converted as a floating number and 20. as a double-precision integer.

References Input number conversion, Sections 1.1.6, 4.1.4

3.8.3 Output Formats

Three standard output formats are provided to display floating-point numbers. All of them remove the top item on the floating-point stack. The number of significant digits to display is set globally for all three formats and will remain in use until changed. There is also low-level support for custom output (and input) formatting; see Section 3.8.11.

Glossary

Display the top number on the floating-point stack, followed by a space. Uses scientific notation (significand plus exponent), where the significand is greater than or equal to 1.0 and less than 10.0. The number of significant digits dis-

106 System Functions