12. The optional Floating-Point word set

12.1 Introduction

12.2 Additional terms and notation

12.2.1 Definition of terms

float-aligned address:
The address of a memory location at which a floating-point number can be accessed.
double-float-aligned address:
The address of a memory location at which a 64-bit IEEE double-precision floating-point number can be accessed.
single-float-aligned address:
The address of a memory location at which a 32-bit IEEE single-precision floating-point number can be accessed.
IEEE floating-point number:
A single- or double-precision floating-point number as defined in ANSI/IEEE 754-1985.

12.2.2 Notation

12.2.2.1 Numeric notation

The following notation is used to define the syntax of the external representation of floating-point numbers:

12.2.2.2 Stack notation

Floating-point stack notation when the floating-point stack is separate from the data stack is:

( F: before -- after )

12.3 Additional usage requirements

12.3.1 Data types

Append table 12.1 to table 3.1.

Table 12.1 - Data Types

Symbol    Data type                       Size on stack
------    ---------                       -------------
r         floating-point number           implementation-defined
f-addr    float-aligned address           1 cell
sf-addr   single-float-aligned address    1 cell
df-addr   double-float-aligned address    1 cell

12.3.1.1 Addresses

The set of float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a floating-point number to a float-aligned address shall produce a float-aligned address.

The set of double-float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a 64-bit IEEE double-precision floating-point number to a double-float-aligned address shall produce a double-float-aligned address.

The set of single-float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a 32-bit IEEE single-precision floating-point number to a single-float-aligned address shall produce a single-float-aligned address.

12.3.1.2 Floating-point numbers

The internal representation of a floating-point number, including the format and precision of the significand and the format and range of the exponent, is implementation defined.

Any rounding or truncation of floating-point numbers is implementation defined.

12.3.2 Floating-point operations

Round to nearest means round the result of a floating-point operation to the representable value nearest the result. If the two nearest representable values are equally near the result, the one having zero as its least significant bit shall be delivered.

Round toward negative infinity means round the result of a floating-point operation to the representable value nearest to and no greater than the result.

12.3.3 Floating-point stack

A last in, first out list that shall be used by all floating-point operators.

The width of the floating-point stack is implementation-defined. By default the floating-point stack shall be separate from the data and return stacks. A program may determine whether floating-point numbers are kept on the data stack by passing the string FLOATING-STACK to ENVIRONMENT?.

The size of a floating-point stack shall be at least 6 items.

A program that depends on the floating-point stack being larger than six items has an environmental dependency.

12.3.4 Environmental queries

Append table 12.2 to table 3.5.

See: 3.2.6 Environmental queries.

Table 12.2 - Environmental query strings

String          Value   Constant?  Meaning
------        Data type ---------  -------
FLOATING        flag    no         floating-point word set
                                   present
FLOATING-EXT    flag    no         floating-point extensions
                                   word set present
FLOATING-STACK  n       yes        If n = zero, floating-point
                                   numbers are kept on the
                                   data stack; otherwise n
                                   is the maximum depth of
                                   the separate
                                   floating-point stack.
MAX-FLOAT       r       yes        largest usable
                                   floating-point number

12.3.5 Address alignment

Since the address returned by a CREATEd word is not necessarily aligned for any particular class of floating-point data, a program shall align the address (to be float aligned, single-float aligned, or double-float aligned) before accessing floating-point data at the address.

See: 3.3.3.1 Address Alignment, 12.3.1.1 Addresses.

12.3.6 Variables

A program may address memory in data space regions made available by FVARIABLE. These regions may be non-contiguous with regions subsequently allocated with , (comma) or ALLOT.

See: 3.3.3.3 Variables.

12.3.7 Text interpreter input number conversion

If the Floating-Point word set is present in the dictionary and the current base is DECIMAL, the input number-conversion algorithm shall be extended to recognize floating-point numbers in this form:

Convertible string := <significand><exponent>

<significand> := [<sign>]<digits>[.<digits0>]
<exponent>    := E[<sign>]<digits0>
<sign>        := { + | - }
<digits>      := <digit><digits0>
<digits0>     := <digit>*
<digit>       := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }

These are examples of valid representations of floating-point numbers in program source:

	1E   1.E   1.E0   +1.23E-1   -1.23E+1

See: 3.4.1.3 Text interpreter input number conversion, 12.6.1.0558 >FLOAT.

12.4 Additional documentation requirements

12.4.1 System documentation

12.4.1.1 Implementation-defined options

12.4.1.2 Ambiguous conditions

12.4.1.3 Other system documentation

12.4.2 Program documentation

12.4.2.1 Environmental dependencies

12.4.2.2 Other program documentation

12.5 Compliance and labeling

12.5.1 ANS Forth systems

The phrase Providing the Floating-Point word set shall be appended to the label of any Standard System that provides all of the Floating-Point word set.

The phrase Providing name(s) from the Floating-Point Extensions word set shall be appended to the label of any Standard System that provides portions of the Floating-Point Extensions word set.

The phrase Providing the Floating-Point Extensions word set shall be appended to the label of any Standard System that provides all of the Floating-Point and Floating-Point Extensions word sets.

12.5.2 ANS Forth programs

The phrase Requiring the Floating-Point word set shall be appended to the label of Standard Programs that require the system to provide the Floating-Point word set.

The phrase Requiring name(s) from the Floating-Point Extensions word set shall be appended to the label of Standard Programs that require the system to provide portions of the Floating-Point Extensions word set.

The phrase Requiring the Floating-Point Extensions word set shall be appended to the label of Standard Programs that require the system to provide all of the Floating-Point and Floating-Point Extensions word sets.

12.6 Glossary

12.6.1 Floating-Point words

12.6.1.0558 >FLOAT
to-float FLOATING
( c-addr u -- true | false ) ( F: -- r | ) or ( c-addr u -- r true | false)

An attempt is made to convert the string specified by c-addr and u to internal floating-point representation. If the string represents a valid floating-point number in the syntax below, its value r and true are returned. If the string does not represent a valid floating-point number only false is returned.

A string of blanks should be treated as a special case representing zero.

The syntax of a convertible string := <significand>[<exponent>]

<significand> := [<sign>]{<digits>[.<digits0>] |
.<digits> }
<exponent>    := <marker><digits0>
<marker>      := {<e-form> | <sign-form>}
<e-form>      := <e-char>[<sign-form>]
<sign-form>   := { + | - }
<e-char>      := { D | d | E | e }

12.6.1.1130 D>F
d-to-f FLOATING
( d -- ) ( F: -- r ) or ( d -- r )

r is the floating-point equivalent of d. An ambiguous condition exists if d cannot be precisely represented as a floating-point value.

12.6.1.1400 F!
f-store FLOATING
( f-addr -- ) ( F: r -- ) or ( r f-addr -- )

Store r at f-addr.

12.6.1.1410 F*
f-star FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

Multiply r1 by r2 giving r3.

12.6.1.1420 F+
f-plus FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

Add r1 to r2 giving the sum r3.

12.6.1.1425 F-
f-minus FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

Subtract r2 from r1, giving r3.

12.6.1.1430 F/
f-slash FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

Divide r1 by r2, giving the quotient r3. An ambiguous condition exists if r2 is zero, or the quotient lies outside of the range of a floating-point number.

12.6.1.1440 F0<
f-zero-less-than FLOATING
( -- flag ) ( F: r -- ) or ( r -- flag )

flag is true if and only if r is less than zero.

12.6.1.1450 F0=
f-zero-equals FLOATING
( -- flag ) ( F: r -- ) or ( r -- flag )

flag is true if and only if r is equal to zero.

12.6.1.1460 F<
f-less-than FLOATING
( -- flag ) ( F: r1 r2 -- ) or ( r1 r2 -- flag )

flag is true

if and only if r1 is less than

f-to-d FLOATING
( -- d ) ( F: r -- ) or ( r -- d )

d is the double-cell signed-integer equivalent of the integer portion of r. The fractional portion of r is discarded. An ambiguous condition exists if the integer portion of r cannot be precisely represented as a double-cell signed integer.

12.6.1.1472 F@
f-fetch FLOATING
( f-addr -- ) ( F: -- r ) or ( f-addr -- r )

r is the value stored at f-addr.

12.6.1.1479 FALIGN
f-align FLOATING
( -- )

If the data-space pointer is not float aligned, reserve enough data space to make it so.

12.6.1.1483 FALIGNED
f-aligned FLOATING
( addr -- f-addr )

f-addr is the first float-aligned address greater than or equal to addr.

12.6.1.1492 FCONSTANT
f-constant FLOATING
( <spaces>name -- ) ( F: r -- ) or ( r <spaces>name -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name with the execution semantics defined below.

name is referred to as an f-constant.

        name Execution: ( -- ) ( F: -- r ) or ( -- r )

Place r on the floating-point stack.

See: 3.4.1 Parsing.

12.6.1.1497 FDEPTH
f-depth FLOATING
( -- +n )

+n is the number of values contained on the default separate floating-point stack. If floating-point numbers are kept on the data stack, +n is the current number of possible floating-point values contained on the data stack.

12.6.1.1500 FDROP
f-drop
FLOATING

( F: r -- ) or ( r -- )

Remove r from the floating-point stack.

12.6.1.1510 FDUP
f-dupe FLOATING
( F: r -- r r ) or ( r -- r r )

Duplicate r.

12.6.1.1552 FLITERAL
f-literal FLOATING
Interpretation: Interpretation semantics for this word are undefined.

        Compilation:    ( F: r -- ) or ( r -- )

Append the run-time semantics given below to the current definition.

        Run-time:       ( F: -- r ) or ( -- r )

Place r on the floating-point stack.

12.6.1.1555 FLOAT+
FLOAT-plus FLOATING
( f-addr1 -- f-addr2 )

Add the size in address units of a floating-point number to f-addr1, giving f-addr2.

12.6.1.1556 FLOATS
FLOATING
( n1 -- n2 )

n2 is the size in address units of n1 floating-point numbers.

12.6.1.1558 FLOOR
FLOATING
( F: r1 -- r2 ) or ( r1 -- r2 )

Round r1 to an integral value using the round toward negative infinity rule, giving r2.

12.6.1.1562 FMAX
f-max FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

r3 is the greater of r1 and r2.

12.6.1.1565 FMIN
f-min FLOATING
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

r3 is the lesser of r1 and r2.

12.6.1.1567 FNEGATE
f-negate FLOATING
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the negation of r1.

12.6.1.1600 FOVER
f-over FLOATING
( F: r1 r2 -- r1 r2 r1 ) or ( r1 r2 -- r1 r2 r1 )

Place a copy of r1 on top of the floating-point stack.

12.6.1.1610 FROT
f-rote FLOATING
( F: r1 r2 r3 -- r2 r3 r1 ) or ( r1 r2 r3 -- r2 r3 r1 )

Rotate the top three floating-point stack entries.

12.6.1.1612 FROUND
f-round FLOATING
( F: r1 -- r2 ) or ( r1 -- r2 )

Round r1 to an integral value using the round to nearest rule, giving r2.

See: 12.3.2 Floating-point operations.

12.6.1.1620 FSWAP
f-swap FLOATING
( F: r1 r2 -- r2 r1 ) or ( r1 r2 -- r2 r1 )

Exchange the top two floating-point stack items.

12.6.1.1630 FVARIABLE
f-variable FLOATING
( <spaces>name -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name with the execution semantics defined below. Reserve 1 FLOATS address units of data space at a float-aligned address.

name is referred to as an f-variable.

        name Execution: ( --f-addr )

f-addr is the address of the data space reserved by FVARIABLE when it created name. A program is responsible for initializing the contents of the reserved space.

See: 3.4.1 Parsing.

12.6.1.2143 REPRESENT
FLOATING
( c-addr u -- n flag1 flag2 ) (F: r -- ) or ( r c-addr u -- n flag1 flag2 )

At c-addr, place the character-string external representation of the significand of the floating-point number r. Return the decimal-base exponent as n, the sign as flag1 and valid result as flag2. The character string shall consist of the u most significant digits of the significand represented as a decimal fraction with the implied decimal point to the left of the first digit, and the first digit zero only if all digits are zero. The significand is rounded to u digits following the round to nearest rule; n is adjusted, if necessary, to correspond to the rounded magnitude of the significand. If flag2 is true then r was in the implementation-defined range of floating-point numbers. If flag1 is true then r is negative.

An ambiguous condition exists if the value of BASE is not decimal ten.

When flag2 is false, n and flag1 are implementation defined, as are the contents of c-addr. Under these circumstances, the string at c-addr shall consist of graphic characters.

See: 3.2.1.2 Digit conversion, 6.1.0750 BASE, 12.3.2 Floating-point operations.

Table of Contents
Next Section