< The optional File-Access word set
The optional Locals word set >

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.2 Stack notation

Floating-point stack notation is:
( F: before -- after )

A unified stack notation is provided for systems with the environmental restriction that the floating-point numbers are kept on the data stack.

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
df-addr double-float-aligned address 1 cell
f-addr float-aligned address 1 cell
r floating-point number implementation-defined
sf-addr single-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.

"Round toward zero" means round the result of a floating-point operation to the representable value nearest to zero, frequently referred to as "truncation".

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. The floating-point stack shall be separate from the data and return stacks.

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

See: 3.2.6 Environmental queries.

Table 12.2: Environmental Query Strings
String Value data type Constant? Meaning
FLOATING-STACK n yes the maximum depth of the separate floating-point stack. On systems with the environmental restriction of keeping floating-point items on the data stack, n = 0.
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.1.4 Environmental restrictions

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 Forth-2012 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 Forth-2012 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

2ex
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 }

See
A.12.6.1.0558 >FLOAT.

Rationale
>FLOAT enables programs to read floating-point data in legible ASCII format. It accepts a much broader syntax than does the text interpreter since the latter defines rules for composing source programs whereas >FLOAT defines rules for accepting data. >FLOAT is defined as broadly as is feasible to permit input of data from Forth-2012 systems as well as other widely used standard programming environments.

This is a synthesis of common FORTRAN practice. Embedded spaces are explicitly forbidden in much scientific usage, as are other field separators such as comma or slash.

While >FLOAT is not required to treat a string of blanks as zero, this behavior is strongly encouraged, since a future version of this standard may include such a requirement.

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

12.6.1.1470
F>D
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 represented as a double-cell signed integer.

Note
Rounding the floating-point value prior to calling F>D is advised, because F>D rounds towards zero.

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, A.12.6.1.1492 FCONSTANT.

Rationale
Typical use: r FCONSTANT name

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

+n is the number of values contained on the floating-point stack. If the system has an environmental restriction of keeping the floating-point numbers 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.

See
A.12.6.1.1552 FLITERAL.

Rationale
Typical use: : X ... [ ... ( r ) ] FLITERAL ... ;

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.

See
12.3.2 Floating-point operations, 12.6.1.1612 FROUND, 12.6.2.1627 FTRUNC.

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.1558 FLOOR, 12.6.2.1627 FTRUNC.

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, A.12.6.1.1630 FVARIABLE.

Rationale
Typical use: FVARIABLE name

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,
A.12.6.1.2143 REPRESENT.

Rationale
This word provides a primitive for floating-point display. Some floating-point formats, including those specified by IEEE-754, allow representations of numbers outside of an implementation-defined range. These include plus and minus infinities, denormalized numbers, and others. In these cases we expect that REPRESENT will usually be implemented to return appropriate character strings, such as "+infinity" or "nan", possibly truncated.

12.6.2 Floating-Point extension words

12.6.2.1203
DF!
d-f-store
FLOATING EXT
 
( 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.

12.6.2.1204
DF@
d-f-fetch
FLOATING EXT
 
( 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.

12.6.2.1205
DFALIGN
d-f-align
FLOATING EXT
 
( -- )

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

See
12.3.1.1 Addresses.

12.6.2.1207
DFALIGNED
d-f-aligned
FLOATING EXT
 
( addr -- df-addr )

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

See
12.3.1.1 Addresses.

12.6.2.1207.40
DFFIELD:
d-f-field-colon
FLOATING EXT
X:structures
 
( n1 "<spaces>name" -- n2 )

Skip leading space delimiters. Parse name delimited by a space. Offset is the first double-float aligned value greater than or equal to n1. n2 = offset + 1 double-float.

Create a definition for name with the execution semantics given below.

name Execution
( addr1 -- addr2 )

Add the offset calculated during the compile-time action to addr1 giving the address addr2.

See
10.6.2.0135 +FIELD, 10.6.2.0763 BEGIN-STRUCTURE,
10.6.2.1336 END-STRUCTURE, A.10.6.2.1518 FIELD:.

12.6.2.1208
DFLOAT+
d-float-plus
FLOATING EXT
 
( 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.

12.6.2.1209
DFLOATS
d-floats
FLOATING EXT
 
( n1 -- n2 )

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

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

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

12.6.2.1427
F.
f-dot
FLOATING EXT
 
( -- ) ( 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.2.1427 F.

Rationale
For example, 1E3 F. displays 1000.

12.6.2.1471
F>S
F to S
FLOATING EXT
X:stoftos
 
( -- n ) ( F: r -- ) or ( r -- n )

n is the single-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 represented as a single-cell signed integer.

Note
Rounding the floating-point value prior to calling F>S is advised, because F>S rounds towards zero.

See
12.6.2.2175 S>F.

Implementation
: F>S ( r -- n )
   F>D D>S
;

12.6.2.1474
FABS
f-abs
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the absolute value of r1.

12.6.2.1476
FACOS
f-a-cos
FLOATING EXT
 
( 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.

12.6.2.1477
FACOSH
f-a-cosh
FLOATING EXT
 
( 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.

12.6.2.1484
FALOG
f-a-log
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

Raise ten to the power r1, giving r2.

12.6.2.1486
FASIN
f-a-sine
FLOATING EXT
 
( 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.

12.6.2.1487
FASINH
f-a-cinch
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the floating-point value whose hyperbolic sine is r1.

12.6.2.1488
FATAN
f-a-tan
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the principal radian angle whose tangent is r1.

12.6.2.1489
FATAN2
f-a-tan-two
FLOATING EXT
 
( F: r1 r2 -- r3 ) or ( r1 r2 -- r3 )

r3 is the principal radian angle (between -π and π) whose tangent is r1/r2. A system that returns false for "-0E 0E 0E F~" shall return a value (approximating) -π when r1 = 0E and r2 is negative. An ambiguous condition exists if r1 and r2 are zero.

See
A.12.6.2.1489 FATAN2.

Rationale
FSINCOS and FATAN2 are a complementary pair of operators which convert angles to 2-vectors and vice-versa. They are essential to most geometric and physical applications since they correctly and unambiguously handle this conversion in all cases except null vectors, even when the tangent of the angle would be infinite.

FSINCOS returns a Cartesian unit vector in the direction of the given angle, measured counter-clockwise from the positive X-axis. The order of results on the stack, namely y underneath x, permits the 2-vector data type to be additionally viewed and used as a ratio approximating the tangent of the angle. Thus the phrase FSINCOS F/ is functionally equivalent to FTAN, but is useful over only a limited and discontinuous range of angles, whereas FSINCOS and FATAN2 are useful for all angles.

The argument order for FATAN2 is the same, converting a vector in the conventional representation to a scalar angle. Thus, for all angles, FSINCOS FATAN2 is an identity within the accuracy of the arithmetic and the argument range of FSINCOS. Note that while FSINCOS always returns a valid unit vector, FATAN2 will accept any non-null vector. An ambiguous condition exists if the vector argument to FATAN2 has zero magnitude.

Testing
[UNDEFINED] NaN [IF] 0e 0e F/ FCONSTANT NaN [THEN]
[UNDEFINED] +Inf [IF] 1e 0e F/ FCONSTANT +Inf [THEN]
[UNDEFINED] -Inf [IF] -1e 0e F/ FCONSTANT -Inf [THEN]

TRUE verbose !
DECIMAL

The test harness default for EXACT? is TRUE. Uncomment the following line if your system needs it to be FALSE
\ SET-NEAR

VARIABLE #errors 0 #errors !

:NONAME ( c-addr u -- )
   ( Display an error message followed by the line that had the error@. )
   1 #errors +! error1 ; error-xt !

[UNDEFINED] pi [IF]
   0.3141592653589793238463E1 FCONSTANT pi
[THEN]

[UNDEFINED] -pi [IF]
   pi FNEGATE FCONSTANT -pi
[THEN]

FALSE [IF]
   0.7853981633974483096157E0 FCONSTANT pi/4
   -0.7853981633974483096157E0 FCONSTANT -pi/4
   0.1570796326794896619231E1 FCONSTANT pi/2
   -0.1570796326794896619231E1 FCONSTANT -pi/2
   0.4712388980384689857694E1 FCONSTANT 3pi/2
   0.2356194490192344928847E1 FCONSTANT 3pi/4
   -0.2356194490192344928847E1 FCONSTANT -3pi/4
[ELSE]
   pi 4e F/ FCONSTANT pi/4
   -pi 4e F/ FCONSTANT -pi/4
   pi 2e F/ FCONSTANT pi/2
   -pi 2e F/ FCONSTANT -pi/2
   pi/2 3e F* FCONSTANT 3pi/2
   pi/4 3e F* FCONSTANT 3pi/4
   -pi/4 3e F* FCONSTANT -3pi/4
[THEN]

verbose @ [IF]
   :NONAME ( -- fp.separate? )
     DEPTH >R 1e DEPTH R> FDROP 2R> = ; EXECUTE
   CR .( floating-point and data stacks )
   [IF] .( *separate* ) [ELSE] .( *not separate* ) [THEN]
   CR
[THEN]

TESTING normal values

\ y x rad deg
T{  0e  1e FATAN2 ->   0e   R}T   \ 0
T{  1e  1e FATAN2 ->   pi/4 R}T   \ 45
T{  1e  0e FATAN2 ->   pi/2 R}T   \ 90
T{ -1e -1e FATAN2 -> -3pi/4 R}T   \ 135
T{  0e -1e FATAN2 ->   pi   R}T   \ 180
T{ -1e  1e FATAN2 ->  -pi/4 R}T   \ 225
T{ -1e  0e FATAN2 ->  -pi/2 R}T   \ 270
T{ -1e  1e FATAN2 ->  -pi/4 R}T   \ 315

TESTING Single UNIX 3 special values spec

\ ISO C / Single UNIX Specification Version 3:
\    http://www.unix.org/single_unix_specification/
\ Select "Topic", then "Math Interfaces", then "atan2()":
\    http://www.opengroup.org/onlinepubs/009695399/
\    functions/atan2f.html

\ If y is +/-0 and x is < 0, +/-pi shall be returned.
T{  0e -1e FATAN2 ->  pi R}T
T{ -0e -1e FATAN2 -> -pi R}T

\ If y is +/-0 and x is > 0, +/-0 shall be returned.
T{  0e  1e FATAN2 ->  0e R}T
T{ -0e  1e FATAN2 -> -0e R}T
\ If y is < 0 and x is +/-0, -pi/2 shall be returned.
T{ -1e  0e FATAN2 -> -pi/2 R}T
T{ -1e -0e FATAN2 -> -pi/2 R}T
\ If y is > 0 and x is +/-0, pi/2 shall be returned.
T{  1e  0e FATAN2 -> pi/2 R}T
T{  1e -0e FATAN2 -> pi/2 R}T
TESTING Single UNIX 3 special values optional spec

\ Optional ISO C / single UNIX specs:

\ If either x or y is NaN, a NaN shall be returned.
T{ NaN  1e FATAN2 -> NaN R}T
T{  1e NaN FATAN2 -> NaN R}T
T{ NaN NaN FATAN2 -> NaN R}T

\ If y is +/-0 and x is -0, +/-pi shall be returned.
T{  0e -0e FATAN2 ->  pi R}T
T{ -0e -0e FATAN2 -> -pi R}T

\ If y is +/-0 and x is +0, +/-0 shall be returned.
T{  0e  0e FATAN2 -> +0e R}T
T{ -0e  0e FATAN2 -> -0e R}T

\ For finite values of +/-y > 0, if x is -Inf, +/-pi shall be returned.
T{  1e -Inf FATAN2 ->  pi R}T
T{ -1e -Inf FATAN2 -> -pi R}T

\ For finite values of +/-y > 0, if x is +Inf, +/-0 shall be returned.
T{  1e +Inf FATAN2 -> +0e R}T
T{ -1e +Inf FATAN2 -> -0e R}T

\ For finite values of x, if y is +/-Inf, +/-pi/2 shall be returned.
T{ +Inf  1e FATAN2 ->  pi/2 R}T
T{ +Inf -1e FATAN2 ->  pi/2 R}T
T{ +Inf  0e FATAN2 ->  pi/2 R}T
T{ +Inf -0e FATAN2 ->  pi/2 R}T
T{ -Inf  1e FATAN2 -> -pi/2 R}T
T{ -Inf -1e FATAN2 -> -pi/2 R}T
T{ -Inf  0e FATAN2 -> -pi/2 R}T
T{ -Inf -0e FATAN2 -> -pi/2 R}T

\ If y is +/-Inf and x is -Inf, +/-3pi/4 shall be returned.
T{ +Inf -Inf FATAN2 ->  3pi/4 R}T
T{ -Inf -Inf FATAN2 -> -3pi/4 R}T

\ If y is +/-Inf and x is +Inf, +/-pi/4 shall be returned.
T{ +Inf +Inf FATAN2 ->  pi/4 R}T
T{ -Inf +Inf FATAN2 -> -pi/4 R}T

verbose @ [IF]
   CR .( #ERRORS: ) #errors @ . CR
[THEN]

12.6.2.1491
FATANH
f-a-tan-h
FLOATING EXT
 
( 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.

12.6.2.1493
FCOS
f-cos
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the cosine of the radian angle r1.

12.6.2.1494
FCOSH
f-cosh
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the hyperbolic cosine of r1.

12.6.2.1513
FE.
f-e-dot
FLOATING EXT
 
( -- ) ( 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
6.1.0750 BASE, 12.3.2 Floating-point operations, 12.6.1.2143 REPRESENT.

12.6.2.1515
FEXP
f-e-x-p
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

Raise e to the power r1, giving r2.

12.6.2.1516
FEXPM1
f-e-x-p-m-one
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

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

See
A.12.6.2.1516 FEXPM1.

Rationale
This function allows accurate computation when its arguments are close to zero, and provides a useful base for the standard exponential functions. Hyperbolic functions such as sinh(x) can be efficiently and accurately implemented by using FEXPM1; accuracy is lost in this function for small values of x if the word FEXP is used.

An important application of this word is in finance; say a loan is repaid at 15% per year; what is the daily rate? On a computer with single-precision (six decimal digit) accuracy:

1.
Using FLN and FEXP: FLN of 1.15 = 0.139762,
divide by 365 = 3.82910E-4,
form the exponent using FEXP = 1.00038, and
subtract one (1) and convert to percentage = 0.038%.

Thus we only have two-digit accuracy.
2.
Using FLNP1 and FEXPM1: FLNP1 of 0.15 = 0.139762, (this is the same value as in the first example, although with the argument closer to zero it may not be so)
divide by 365 = 3.82910E-4,
form the exponent and subtract one (1) using FEXPM1 = 3.82983E-4, and
convert to percentage = 0.0382983%.

This calculation method allows the hyperbolic functions to be computed with six-digit accuracy. For example, sinh can be defined as:

: FSINH ( r1 -- r2 )
   FEXPM1 FDUP FDUP 1.0E0 F+ F/ F+ 2.0E0 F/ ;

12.6.2.1517
FFIELD:
f-field-colon
FLOATING EXT
X:structures
 
( n1 "<spaces>name" -- n2 )

Skip leading space delimiters. Parse name delimited by a space. Offset is the first float aligned value greater than or equal to n1. n2 = offset + 1 float.

Create a definition for name with the execution semantics given below.

name Execution
( addr1 -- addr2 )

Add the offset calculated during the compile-time action to addr1 giving the address addr2.

See
10.6.2.0135 +FIELD, 10.6.2.0763 BEGIN-STRUCTURE,
10.6.2.1336 END-STRUCTURE, A.10.6.2.1518 FIELD:.

12.6.2.1553
FLN
f-l-n
FLOATING EXT
 
( 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.

12.6.2.1554
FLNP1
f-l-n-p-one
FLOATING EXT
 
( 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.

Rationale
This function allows accurate compilation when its arguments are close to zero, and provides a useful base for the standard logarithmic functions. For example, FLN can be implemented as:

: FLN 1.0E0 F- FLNP1 ;
See
A.12.6.2.1516 FEXPM1.

12.6.2.1557
FLOG
f-log
FLOATING EXT
 
( 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.

12.6.2.1613
FS.
f-s-dot
FLOATING EXT
 
( -- ) ( 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
6.1.0750 BASE, 12.3.2 Floating-point operations, 12.6.1.2143 REPRESENT.

12.6.2.1614
FSIN
f-sine
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the sine of the radian angle r1.

12.6.2.1616
FSINCOS
f-sine-cos
FLOATING EXT
 
( 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.

12.6.2.1617
FSINH
f-cinch
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the hyperbolic sine of r1.

12.6.2.1618
FSQRT
f-square-root
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

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

12.6.2.1625
FTAN
f-tan
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

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

12.6.2.1626
FTANH
f-tan-h
FLOATING EXT
 
( F: r1 -- r2 ) or ( r1 -- r2 )

r2 is the hyperbolic tangent of r1.

12.6.2.1627
FTRUNC
f-trunc
FLOATING EXT
X:ftrunc
 
( F: r1 -- r2 ) or ( r1 -- r2 )

Round r1 to an integral value using the "round towards zero" rule, giving r2.

See
12.3.2 Floating-point operations, 12.6.1.1612 FROUND, 12.6.1.1558 FLOOR.

Implementation
: FTRUNC ( r1 -- r2 )
         FDUP F0= 0=
   IF    FDUP F0<
   IF    FNEGATE FLOOR FNEGATE
   ELSE   FLOOR
   THEN
   THEN   ;
Testing
SET-EXACT

T{ -0E          FTRUNC F0= -> <TRUE> }T
T{ -1E-9        FTRUNC F0= -> <TRUE> }T
T{ -0.9E        FTRUNC F0= -> <TRUE> }T
T{ -1E  1E-5 F+ FTRUNC F0= -> <TRUE> }T
T{ 0E           FTRUNC     ->  0E   R}T
T{ 1E-9         FTRUNC     ->  0E   R}T
T{ -1E -1E-5 F+ FTRUNC     -> -1E   R}T
T{ 3.14E        FTRUNC     ->  3E   R}T
T{ 3.99E        FTRUNC     ->  3E   R}T
T{ 4E           FTRUNC     ->  4E   R}T
T{ -4E          FTRUNC     -> -4E   R}T
T{ -4.1E        FTRUNC     -> -4E   R}T

6ex

12.6.2.1628
FVALUE
f-value
FLOATING EXT
X:fvalue
 
( F: r -- ) ( "<spaces>name" -- ) 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, with an initial value equal to r.

name is referred to as a "f-value".

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

Place r on the floating point stack. The value of r is that given when name was created, until the phrase "r TO name" is executed, causing a new value of r to be assigned to name.

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

Assign the value r to name.

See
3.4.1 Parsing, 6.2.2295 TO

Implementation
The implementation of FVALUE requires detailed knowledge of the host implementation of VALUE and TO.

VARIABLE %var
: TO 1 %var ! ;

: FVALUE ( F: r -- ) ( "<spaces>name" -- )
   CREATE F,
   DOES> %var @ IF F! ELSE F@ THEN
         0 %var ! ;

: VALUE ( x "<spaces>name" -- )
   CREATE ,
   DOES> %var @ IF ! ELSE @ THEN
         0 %var ! ;

Testing
T{ 0e0 FVALUE Tval -> }T
T{ Tval -> 0e0 R}T
T{ 1e0 TO Tval -> }T
T{ Tval -> 1e0 R}T
: setTval Tval FSWAP TO Tval ;
T{ 2e0 setTval Tval -> 1e0 2e0 RR}T
T{ 5e0 TO Tval -> }T
: [execute] EXECUTE ; IMMEDIATE
T{ ' Tval ] [execute] [ -> 2e0 R}T

12.6.2.1640
F~
f-proximate
FLOATING EXT
 
( -- 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~.

Rationale
This provides the three types of "floating point equality" in common use — "close" in absolute terms, exact equality as represented, and "relatively close".

12.6.2.2035
PRECISION
 
FLOATING EXT
 
( -- u )

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

12.6.2.2175
S>F
S to F
FLOATING EXT
X:stoftos
 
( n -- ) ( F: -- r ) or ( n -- r )

r is the floating-point equivalent of the single-cell value n. An ambiguous condition exists if n can not be precisely represented as a floating-point value.

See
12.6.2.1471 F>S.

Implementation
: S>F ( n -- r )
   S>D D>F
;

12.6.2.2200
SET-PRECISION
 
FLOATING EXT
 
( u -- )

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

12.6.2.2202
SF!
s-f-store
FLOATING EXT
 
( 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.

12.6.2.2203
SF@
s-f-fetch
FLOATING EXT
 
( 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.

12.6.2.2204
SFALIGN
s-f-align
FLOATING EXT
 
( -- )

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

See
12.3.1.1 Addresses.

12.6.2.2206
SFALIGNED
s-f-aligned
FLOATING EXT
 
( addr -- sf-addr )

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

See
12.3.1.1 Addresses.

12.6.2.2206.40
SFFIELD:
s-f-field-colon
FLOATING EXT
X:structures
 
( n1 "<spaces>name" -- n2 )

Skip leading space delimiters. Parse name delimited by a space. Offset is the first single-float aligned value greater than or equal to n1. n2 = offset + 1 single-float.

Create a definition for name with the execution semantics given below.

name Execution
( addr1 -- addr2 )

Add the offset calculated during the compile-time action to addr1 giving the address addr2.

See
10.6.2.0135 +FIELD, 10.6.2.0763 BEGIN-STRUCTURE,
10.6.2.1336 END-STRUCTURE, A.10.6.2.1518 FIELD:.

12.6.2.2207
SFLOAT+
s-float-plus
FLOATING EXT
 
( 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.

12.6.2.2208
SFLOATS
s-floats
FLOATING EXT
 
( n1 -- n2 )

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

See
12.3.1.1 Addresses.

< The optional File-Access word set
The optional Locals word set >