Table of Contents

12. The optional Floating-Point word set

See: A.12 The optional Floating-Point word set

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.

• Each component of a floating-point number is defined with a rule consisting of the name of the component (italicized in angle-brackets, e.g.,<sign> characters := and a concatenation of tokens and metacharacters;
• Tokens may be literal characters (in bold face, e.g.,E) or rule names in angle brackets (e.g.,<digit>);
• The metacharacter * is used to specify zero or more occurrences of the preceding token (e.g.,<digit>*);
• Tokens enclosed with [ and ] are optional (e.g.,[<sign>]);
• Vertical bars separate choices from a list of tokens enclosed with braces (e.g.,{ + | - }).

( F: before -- after )

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

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.

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

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.

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.

See: 3.2.6 Environmental queries

Table 12.2 - Environmental query strings

String          Value data type  Constant?  Meaning
------          ---------------  ---------  -------
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

See: 3.3.3.1 Address alignment, A.12.3.5 Address alignment, 12.3.1.1 Addresses.

See: 3.3.3.3 Variables

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, A.12.3.7 Text interpreter input number conversion, 12.6.1.0558 >FLOAT

• format and range of floating-point numbers (12.3.1 Data types, 12.6.1.2143 REPRESENT);
• results of 12.6.1.2143 REPRESENT when float is out of range;
• rounding or truncation of floating-point numbers (12.3.1.2 Floating-point numbers);
• size of floating-point stack (12.3.3 Floating-point stack);
• width of floating-point stack (12.3.3 Floating-point stack).

• DF@ or DF! is used with an address that is not double-float aligned;
• F@ or F! is used with an address that is not float aligned;
• FLOATing point result out of range (e.g., in 12.6.1.1430 F/);
• SF@ or SF! is used with an address that is not single-float aligned;
• BASE is not decimal (12.6.1.2143 REPRESENT, 12.6.2.1427 F., 12.6.2.1513 FE., 12.6.2.1613 FS.);
• both arguments equal zero (12.6.2.1489 FATAN2);
• cosine of argument is zero for 12.6.2.1625 FTAN;
• d can't be precisely represented as float in 12.6.1.1130 D>F;
• dividing by zero (12.6.1.1430 F/);
• exponent too big for conversion (12.6.2.1203 DF!, 12.6.2.1204 DF@, 12.6.2.2202 SF!, 12.6.2.2203 SF@);
• FLOAT less than one (12.6.2.1477 FACOSH);
• FLOAT less than or equal to minus-one (12.6.2.1554 FLNP1);
• FLOAT less than or equal to zero (12.6.2.1553 FLN, 12.6.2.1557 FLOG);
• FLOAT less than zero (12.6.2.1487 FASINH, 12.6.2.1618 FSQRT);
• FLOAT magnitude greater than one (12.6.2.1476 FACOS, 12.6.2.1486 FASIN, 12.6.2.1491 FATANH);
• Integer part of float can't be represented by d in 12.6.1.1470 F>D;
• string larger than pictured-numeric output area (12.6.2.1427 F., 12.6.2.1513 FE., 12.6.2.1613 FS.).

• no additional requirements.

• requiring the floating-point stack to be larger than six items (12.3.3 Floating-point stack).

• no additional requirements.

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.

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.

	( 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 }

See: A.12.6.1.0558 >FLOAT

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

	( f-addr -- ) ( F: r -- ) 
        or ( r f-addr -- )

Store r at f-addr.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

Multiply r1 by r2 giving r3.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

Add r1 to r2 giving the sum r3.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

Subtract r2 from r1, giving r3.

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

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

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

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

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

	( -- flag ) ( F: r1 r2 -- ) 
	or ( r1 r2 -- flag )

flag is true

if and only if r1 is less than

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

	( f-addr -- ) ( F: -- r )  
	or  ( f-addr -- r )

r is the value stored at f-addr.

	( -- )

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

	( addr -- f-addr )

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

	( "<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: A.12.6.1.1492 FCONSTANT , 3.4.1 Parsing.

	( -- +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.

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

Remove r from the floating-point stack.

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

Duplicate r.

	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.

See: A.12.6.1.1552 FLITERAL

	( f-addr1 -- f-addr2 )

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

	( n1 -- n2 )

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

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

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

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

r3 is the greater of r1 and r2.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

r3 is the lesser of r1 and r2.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the negation of r1.

	( F: r1 r2 -- r1 r2 r1 ) 
	or ( r1 r2 -- r1 r2 r1 )

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

	( F: r1 r2 r3 -- r2 r3 r1 ) 
	or ( r1 r2 r3 -- r2 r3 r1 )

Rotate the top three floating-point stack entries.

	( 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

	( F: r1 r2 -- r2 r1 ) 
	or ( r1 r2 -- r2 r1 )

Exchange the top two floating-point stack items.

	( "<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: A.12.6.1.1630 FVARIABLE , 3.4.1 Parsing.

	( 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, 12.3.2 Floating-point operations, A.12.6.1.2143 REPRESENT

	( df-addr -- ) ( F: r -- ) 
	or ( r df-addr -- )

Store the floating-point number r as a 64-bit IEEE double-precision number at df-addr. If the significand of the internal representation of r has more precision than the IEEE double-precision format, it will be rounded using the round to nearest rule. An ambiguous condition exists if the exponent of r is too large to be accommodated in IEEE double-precision format.

See: 12.3.1.1 Addresses, 12.3.2 Floating-point operations.

	( df-addr -- ) ( F: -- r ) 
	or ( df-addr -- r )

Fetch the 64-bit IEEE double-precision number stored at df-addr to the floating-point stack as r in the internal representation. If the IEEE double-precision significand has more precision than the internal representation it will be rounded to the internal representation using the round to nearest rule. An ambiguous condition exists if the exponent of the IEEE double-precision representation is too large to be accommodated by the internal representation.

See: 12.3.1.1 Addresses, 12.3.2 Floating-point operations.

	( -- )

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

See: 12.3.1.1 Addresses

	( addr -- df-addr )

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

See: 12.3.1.1 Addresses

	( df-addr1 -- df-addr2 )

Add the size in address units of a 64-bit IEEE double-precision number to df-addr1, giving df-addr2.

See: 12.3.1.1 Addresses

	( n1 -- n2 )

n2 is the size in address units of n1 64-bit IEEE double-precision numbers.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

Raise r1 to the power r2, giving the product r3.

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

Display, with a trailing space, the top number on the floating-point stack using fixed-point notation:

	[-] <digits>.<digits0>

An ambiguous condition exists if the value of BASE is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer.

See: 12.6.1.0558 >FLOAT , A.12.6.1.1427 F.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the absolute value of r1.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the principal radian angle whose cosine is r1. An ambiguous condition exists if |r1| is greater than one.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the floating-point value whose hyperbolic cosine is r1. An ambiguous condition exists if r1 is less than one.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

Raise ten to the power r1, giving r2.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the principal radian angle whose sine is r1. An ambiguous condition exists if |r1| is greater than one.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the floating-point value whose hyperbolic sine is r1. An ambiguous condition exists if r1 is less than zero.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the principal radian angle whose tangent is r1.

	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )

r3 is the radian angle whose tangent is r1/r2. An ambiguous condition exists if r1 and r2 are zero.

See: A.12.6.2.1489 FATAN2

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the floating-point value whose hyperbolic tangent is r1. An ambiguous condition exists if r1 is outside the range of -1E0 to 1E0.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the cosine of the radian angle r1.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the hyperbolic cosine of r1.

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

Display, with a trailing space, the top number on the floating-point stack using engineering notation, where the significand is greater than or equal to 1.0 and less than 1000.0 and the decimal exponent is a multiple of three.

An ambiguous condition exists if the value of BASE is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer.

See: 12.3.2 Floating-point operations, 12.6.1.2143 REPRESENT

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

Raise e to the power r1, giving r2.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

Raise e to the power r1 and subtract one, giving r2.

See: A.12.6.2.1516 FEXPM1

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the natural logarithm of r1. An ambiguous condition exists if r1 is less than or equal to zero.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the natural logarithm of the quantity r1 plus one. An ambiguous condition exists if r1 is less than or equal to negative one.

See: A.12.6.2.1554 FLNP1

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the base-ten logarithm of r1. An ambiguous condition exists if r1 is less than or equal to zero.

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

Display, with a trailing space, the top number on the floating-point stack in scientific notation:

	<significand><exponent>

where:

	<significand>  :=  [-]<digit>.<digits0>
	<exponent>     :=  E[-]<digits>

An ambiguous condition exists if the value of BASE is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer.

See: 12.3.2 Floating-point operations, 12.6.1.2143 REPRESENT

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the sine of the radian angle r1.

	( F: r1 -- r2 r3 ) 
	or ( r1 -- r2 r3 )

r2 is the sine of the radian angle r1. r3 is the cosine of the radian angle r1.

See: A.12.6.2.1489 FATAN2

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the hyperbolic sine of r1.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the square root of r1. An ambiguous condition exists if r1 is less than zero.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the tangent of the radian angle r1. An ambiguous condition exists if cos(r1) is zero.

	( F: r1 -- r2 ) 
	or ( r1 -- r2 )

r2 is the hyperbolic tangent of r1.

	( -- flag ) ( F: r1 r2 r3 -- ) 
	or ( r1 r2 r3 -- flag )

If r3 is positive, flag is true if the absolute value of (r1 minus r2) is less than r3.

If r3 is zero, flag is true if the implementation-dependent encoding of r1 and r2 are exactly identical (positive and negative zero are unequal if they have distinct encodings).

If r3 is negative, flag is true if the absolute value of (r1 minus r2) is less than the absolute value of r3 times the sum of the absolute values of r1 and r2.

See: A.12.6.2.1640 F~

	( -- u )

Return the number of significant digits currently used by F., FE., or FS. as u.

	( u -- )

Set the number of significant digits currently used by F., FE., or FS. to u.

	( sf-addr -- ) ( F: r -- ) 
	or ( r sf-addr -- )

Store the floating-point number r as a 32-bit IEEE single-precision number at sf-addr. If the significand of the internal representation of r has more precision than the IEEE single-precision format, it will be rounded using the round to nearest rule. An ambiguous condition exists if the exponent of r is too large to be accommodated by the IEEE single-precision format.

See: 12.3.1.1 Addresses, 12.3.2 Floating-point operations.

	( sf-addr -- ) ( F: -- r ) 
	or ( sf-addr -- r )

Fetch the 32-bit IEEE single-precision number stored at sf-addr to the floating-point stack as r in the internal representation. If the IEEE single-precision significand has more precision than the internal representation, it will be rounded to the internal representation using the round to nearest rule. An ambiguous condition exists if the exponent of the IEEE single-precision representation is too large to be accommodated by the internal representation.

See: 12.3.1.1 Addresses, 12.3.2 Floating-point operations.

	( -- )

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

See: 12.3.1.1 Addresses

	( addr -- sf-addr )

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

See: 12.3.1.1 Addresses

	( sf-addr1 -- sf-addr2 )

Add the size in address units of a 32-bit IEEE single-precision number to sf-addr1, giving sf-addr2.

See: 12.3.1.1 Addresses

	( n1 -- n2 )

n2 is the size in address units of n1 32-bit IEEE single-precision numbers.

See: 12.3.1.1 Addresses