PROPOSAL FOR AN OPTIONAL IEEE 754, BINARY
FLOATING-POINT WORD SET
version 0.5.0
dnw 29-May-09
TABLE of CONTENTS
1 INTRODUCTION
2 TERMINOLOGY AND NOTATION
3 DATA TYPES AND ALIGNMENT
4 ENVIRONMENTAL QUERIES
5 IMPLEMENTATION
6 GLOSSARY
6.1 Parameters
6.2 Floating-point stack manipulation
6.3 Conversion
6.4 Storage
6.5 Input
6.6 Output
6.7 Comparison
6.8 Arithmetic
6.9 Nearest integer functions
6.10 Math functions
6.11 Number classification
6.12 Number manipulation
6.13 Floating-point environment
6.13.1 Exceptions
6.13.2 Rounding modes
7 REFERENCES AND FOOTNOTES
1 INTRODUCTION
This is a proposal for an optional Forth 200x word set that
supports the IEC 60559 floating-point standard for binary
floating-point arithmetic, second edition (IEC 60559:1989),
previously designated IEC 559:1989 and as IEEE Standard for
Binary Floating-Point Arithmetic (ANSI/IEEE Std 754:1985).
This document is modeled on the ISO/IEC 9899:1999 C language
specification [1] for IEEE 754 floating point, which is
contained in the WG14/N1124 draft standard [2], plus Technical
Corrigendum 3 [3], and is mostly expressed in Sections 5.2.4.2
of the Environment chaper, Sections 7.6, 7.7, and 7.12 of the
Library chapter, and Annex F, "IEC 60559 floating-point
arithmetic". The Single UNIX 3 specification [4] is a useful
resource for ISO/IEC 9899:1999
The advantages of following the C99 specification include the
following:
* It seems to be a comprehensive expression of IEEE 754:1985 and
William Kahan's approach to accurate floating-point
computation, which underlies it.
* It is pretty clearly written with freely available versions.
* It is straightforward to implement for Forth systems that can
call C libraries.
* Its combination of implementation abstractions and dependences
seems about as well suited to the spectrum of cpu capabilities
as can be expected. It complicates the specification, but
that is probably unavoidable.
This specification requires that ISO Forth [5,6] floating-point
and floating-point extension words in the optional
Floating-Point word set, when present, satisfy the IEEE 754
requirements. Words in that word set, and this, that correspond
to arithmetic operations, functions, or macros specified in
ISO/IEC 9899 adopt, as far as possible, the specified behavior
by reference.
[**Bracketed statements like this are for editorial questions
and comments, eventually to be removed.]
2 TERMINOLOGY AND NOTATION
"IEEE 754" or "IEEE": IEC 60559:1989.
"C99": ISO/IEC 9899:1999 C [1].
"Annex F": Annex in WG14/N1124 [2] or ISO/IEC 9899:1999.
"DPANS94": American National Standard for Forth, ANSI
X3.215-1994, final draft [5]. The final draft is believed to
be the same as the published version, which is now ISO/IEC
15145:1997 [6]. This document adopts the official terminology
of DPANS94 unless otherwise stated.
"fp" or "bfp": Short for "floating point", respectively,
"binary flaoting point". The Forth floating-point stack is
called the "fpstack".
"special number": Signed zero, a quiet or signaling signed nan,
or signed infinity.
"full set of numbers": For an IEEE 754 bfp format, the set of
normal, subnormal, and special numbers.
"IEEE number": Any member of a full set of numbers.
"IEEE arithmetic": Arithmetic defined by IEEE 754 for IEEE
numbers.
"nan load": The value of the IEEE 754 fractional bits of a nan,
excluding the quiet bit, considered as a positive integer.
The smallest signaling load is unity, and the smallest quiet
load is zero. [**True for all IEEE binary formats?]
"qnan", resp., "snan": Any quiet or signaling nan,
respectively, of any sign or load.
"single": In the context of Forth fp, the IEEE 754 32-bit
single-precision format.
"double": In the context of Forth fp, the IEEE 754 64-bit
double-precision format.
"default": In the context of Forth fp, the default float
format.
Each IEEE bfp format has three fixed parameters, p > 0
(precision), emax > 0 (maximim exponent), and emin < 0 (minimum
exponent), and represents all real numbers of the form
r = (-1)^s * 2^e * b_0.b_1 ... b_{p-1}
where
s = 0 or 1, emin <= e <= emax,
b_i = 0 or 1, p = #signifcand bits.
IEEE numbers are typically encoded with exponent fields
equivalent to emin-1 for zero and subnormals, and emax+1 for
infinity and nans.
3 DATA TYPES AND ALIGNMENT
If part or all of the floating-point stack is implemented in
memory, the alignment of stack items in memory shall be the
maximum of the alignments of the implemented formats. The width
of the floating-point stack shall be at least that of the widest
implemented format. [**Does DPANS94 already imply this?]
The DPANS94 r, sr, and dr types are expanded to include the
special numbers.
For the purposes of this word set, DPANS94 Table 12.1 is
replaced by Table 1.
Table 1
-------------------------------------------------------------
Symbol Data type Size on stack
-------------------------------------------------------------
r default float implementation-defined
sr single float implementation-defined
dr double float 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
enum distinct integer 1 cell
+enum nonnegative enum 1 cell
fenva a-addr 1 cell
fenvr n 1 cell
fxctpa a-addr 1 cell
fxcpts masks 1 cell
-------------------------------------------------------------
4 ENVIRONMENTAL QUERIES
A true result for the IEEE-FP environmental query implies that
at least a default, IEEE bfp format is implemented. As
described in the implemention section, that may or may not be
distinct from the IEEE single or double format.
Value
String Data Type Constant? Meaning
----------------------------------------------------------------
IEEE-FP n no n=1: single-fp format implemented
n-2: double-fp format implemented
n=3: both formats implemented
n=0: neither format implemented
FENV-ACCESS a-addr no default fp environment pointer
----------------------------------------------------------------
The words in the PARAMETERS section, plus 1 FLOATS and FALIGNED,
can be used to determine the default bfp format.
5 IMPLEMENTATION
This document considers three logical IEEE bfp formats: default
(Forth float), double, and single. They are called logical
formats because the default format may actually coincide with
the double or single format.
For each of these there is a corresponding set of words, the
default fp words, the double fp words, and the single fp words,
each of which is self-contained with respect to the
corresponding fp data and address operations.
There are also "generic" fp words, involving only data or fp
stack manipulation, which can be used with any of the three
types because of the model that all three have a single-width
container on the fpstack. (It is up to the user to keep track
of the type for fpstack numbers.) There is something to be said
for an alternate model with separate fpstacks for different
formats, but that is not the approach here.
Finally, there are "conversion" fp words, which convert between
bfp formats on the fpstack, between integers on the data
stack and numbers on the fpstack, and between strings and
numbers on the fpstack.
From now on, "default fp word set" refers both to the default
words already present in DPANS94 plus the default fp words
introduced in this document. "Double fp word set", "single fp
word set", "generic word set", and "conversion word set" have
analogous meanings. The collection is called the "IEEE-FP word
set".
Single and double word definitions are often specified by
substitution of single and double data and address types into
default definitions.
According to DPANS94, Section 3, "Usage requirements":
A system shall provide all of the words defined in 6.1 Core
Words. It may also provide any words defined in the optional
word sets and extension word sets.
The DPANS94 Floating-Point word set is an optional word set,
and so is the IEEE-FP word set.
The word "shall" in the following states a requirement when the
environmenal query for IEEE-FP returns true. "Should" means
"strongly recommended".
1. All words from the DPANS94 Floating-Point and Floating-Point
Extensions word sets are included in the IEEE-FP word set,
subject to additional IEEE 754 requirements.
2. A default, IEEE bfp format shall be implemented.
3. Each implemented IEEE format shall be full.
4. The single bfp format need not be implemented. This is a
departure from the IEEE 754 specification.
5. Neither the single nor the double fp word set need be
implemented. Only conversion words that connect to
implemented logical formats need be implemented.
6. The syntax specification in DPANS94 12.3.7, "Text input number
conversion", shall be replaced by
Convertible string := {|}
[**Allow []. as well?]
:= []{[.]|.}
[**Note the extra . option.]
:= {[]|}
[**Note that a sign with no digits is not allowed.]
:=
:= *
:= {+|-}
:= {E|e}
:= []{|}
:= {Inf|inf|INF}
:= {NaN|nan|NAN}
Interpretation shall convert to the default IEEE format.
The positive special number produced for NaN is the quiet
nan with zero load, and that produced by -NaN is its
negative.
Nan loads should be interpreted.
[**Note the "should". Syntax spec to be filled in.]
C99 syntax with significand in hex and radix 2 exponent in
decimal should be interpreted.
[**Syntax spec to be filled in.]
The rounding mode for number conversion is the IEEE mode,
round to nearest with even tiebreakers.
[**This corresponds to the C99 requirement for translation.
However, DPANS94 12.3.1.2 says
Any rounding or truncation of floating-point numbers is
implementation defined.
I take that to apply to text interpreter input
number conversion, and we may want to keep it.
In any case, the wording of 12.3.1.2 needs fixing, because
it contradicts the DPANS94 definition of FROUNDS, which
requires "round to nearest".]
7. The default format should have precision and range greater
than or equal to those of any other implemented format.
Otherwise the text interpreter cannot correctly interpret
the maximum precision and range.
8. All words that have natural correspondences to macros,
functions, or operations in C99 are expected to have
analogous behavior, when that makes sense. In particular,
the behavior of floating point arithmetic and math functions
for the special numbers and exceptions is specified by Annex
F. Note that C99 leaves many such details as implementation
defined.
6 GLOSSARY
For the default, double, and single fp words, specifications are
usually given only for the default versions, with the names of
the other versions simply listed. Their specifications are
obtained by substitution of the appropriate data and address
types. The double and single names are not even listed for many
of the math function words.
6.1 Parameters
--------------
These words return values for the default fp format. The C99
parameter FRADIX is not implemented because the only radix is
two. The other C99 parameters have versions for each of the C
types float, double, and long double. Single and double
versions are omitted here, because they are required to
correspond exactly to the IEEE 754 32- and 64-bit formats.
FMANT-DIG ( -- p )
FEXP-MAX ( -- emax )
FEXP-MIN ( -- emin )
6.2 Floating-point stack manipulation
-------------------------------------
These generic words are simply listed. They do not have
explicit double or single versions. The new words are defined
by analogy with the corresponding integer words. The fpstack
manipulation words allow any of r, dr, and sr mixed as inputs or
outputs.
FALIGN FALIGNED FDEPTH FDROP FDUP FOVER FROT FSWAP
New:
-FROT FNIP FTUCK
[** 2FDUP 2FOVER 2FSWAP ?]
6.3 Conversion
--------------
F>SF ( f: r -- sr )
SF>F ( f: sr -- r )
F>DF ( f: r -- dr )
DF>F ( f: dr -- r )
SF>DF ( f: sr -- dr )
DF>SF ( f: dr -- sr )
These words are all new. The treatment of precision and
rounding in these conversions is adapted from C99:6.3.1.5.
[**Does that also cover nan loads?]
D>F ( d -- f: r )
F>D ( f: r -- s: d )
S>F ( n -- f: r ) new
F>S ( f: r -- s: n ) new
The DPANS94 specification is extended to include signed zero
for r. When an input r is signed zero, the output integer is
zero. When the input integer is zero, the output r is +0. An
ambiguous condition exists when the input r is infinity or
nan.
D>DF D>SF DF>D SF>D S>DF S>SF DF>S SF>S
>F ( c-addr u -- r: r s: flag )
The DPANS94 specification is that of >FLOAT, extended to
include special numbers, with modified syntax. [**Rounding?]
A string of blanks [**or the empty string?] should be treated
as +0. [**Allow formatting blanks or characters?]
Syntax of a convertible string := {[exponent]
|}
:= []{[.]|.}
:=
:= [|]
:= []
:= {+|-}
:= {D|d|E|e}
:= []{|}
:= {Inf|inf|INF}
:= {NaN|nan|NAN}
>DF >SF
FREPRESENT ( f: r s: c-addr u -- n flag1 flag2 )
The specification is basically that of DPANS94 for REPRESENT,
extended to include signed zero for r. The valid-result flag,
flag2, is false if r is infinity or a nan.
[**The new name is for consistency with the format
nomenclature, but also presents an opportunity to tighten the
specification of REPRESENT.]
DFREPRESENT SFREPRESENT
6.4 Storage
-----------
DPANS94 specifications for the existing words are extended to
include the special numbers. The only new words are the single
and double constant, literal, and variable words, which have the
natural definitions.
F! F@ FALIGN FALIGNED FCONSTANT FLITERAL FVARIABLE
DF! DF@ DFALIGN DFALIGNED DFCONSTANT DFLITERAL DFVARIABLE
SF! SF@ SFALIGN SFALIGNED SFCONSTANT SFLITERAL SFVARIABLE
FLOAT+ FLOATS DFLOAT+ DFLOATS SFLOAT+ SFLOATS
[**Do we want a CREATE-NALIGNED?]
6.5 Input
---------
See Item 6 in Section 5, concerning extension of the text
interpreter.
6.6 Output
----------
PRECISION ( -- u )
SET-PRECISION ( u -- )
These two are generic words. The DPANS94 definition is
extended to apply to the single and double versions of F.,
FE., and FS..
F. ( f: r -- )
FE. ( f: r -- )
FS. ( f: r -- )
The DPANS94 specification is extended to include the special
numbers, with output text of the appropriate form below, up to
implementation-dependent case sensitivity: [**Rounding?]
[**Mixed hex/decimal output words? FH. DFH. SFH.]
[]0{E|e}
[]
[][:]
DF. DFE. DFS. SF. SFE. SFS.
6.7 Comparison
--------------
F0< ( f: r -- s: flag )
F0<> ( f: r -- s: flag ) new
F0= ( f: r -- s: flag )
F0> ( f: r -- s: flag ) new
F< ( f: r1 r2 -- s: flag )
F<= ( f: r1 r2 -- s: flag ) new
F<> ( f: r1 r2 -- s: flag ) new
F= ( f: r1 r2 -- s: flag ) new
F> ( f: r1 r2 -- s: flag ) new
F>= ( f: r1 r2 -- s: flag ) new
The basic definitions of the new words are by analogy with the
corresponding integer words. All definitions are extended to
the special numbers.
IEEE comparison rules:
* If any input is a nan, the result is false.
* The sign of signed zero is ignored.
* The sign of infinity is not ignored, and is treated in the
natural way for comparisons with real numbers or infinity.
Whether the "invalid" exception is raised for nans is
implementation dependent.
DF0< DF0<> DF0= DF0> DF< DF<= DF<> DF= DF> DF>=
SF0< SF0<> SF0= SF0> SF< SF<= SF<> SF= SF> SF>=
(F<) ( f: r1 r2 -- s: flag ) new C99:7.12.14.3
(F<=) ( f: r1 r2 -- s: flag ) new C99:7.12.14.4
(F>) ( f: r1 r2 -- s: flag ) new C99:7.12.14.1
(F>=) ( f: r1 r2 -- s: flag ) new C99:7.12.14.2
(F<|>) ( f: r1 r2 -- s: flag ) new C99:7.12.14.5
(F?) ( f: r1 r2 -- s: flag ) new C99:7.12.14.6
These words correspond to the C99 islessequal, isgreater,
isgreaterequal, islessgreater, and isunodered macros,
respectively. They do not raise an "invalid" fp exception
when one or both of the inputs is a nan.
Otherwise, the first four behave the same as their
unparenthesized counterparts.
(F<|>) returns false if either input is a nan, and otherwise
returns the same as FOVER FOVER F< F> OR (assuming a separate
fpstack), without evaluating its inputs twice.
(F?) returns true iff at least one of the inputs is a nan.
(DF<) (DF<=) (DF>) (DF>=) (DF<|>) (DF?)
(SF<) (SF<=) (SF>) (SF>=) (SF<|>) (SF?)
F~ ( f: r1 r2 r3 -- s: flag )
If the sign of r3 is plus, flag is true iff the absolute value
of r1 minus r2 is less than r3, taking into account IEEE
arithmetic and comparison rules.
If r3 is signed zero, flag is true iff r1 and r2 have
identical formats.
If the sign of r3 is minus, flag is true iff the absolute
value of r1 minus r2 is greater than r3, taking into account
IEEE arithmetic and comparison rules.
[**Double check that the middle case is identical to the other
two when r3 is signed zero.]
DF~ SF~
6.8 Arithmetic
--------------
F* ( f: r1 r2 -- r1*r2 )
F*+ ( f: r1 r2 r3 -- [r2*r3]+r1 ) new
F+ ( f: r1 r2 -- r1+r2 )
F- ( f: r1 r2 -- r1-r2 )
F/ ( f: r1 r2 -- r1/r2 )
FNEGATE ( f: r -- -r )
The DPANS94 specification is extended to IEEE arithmetic. See
Annex F for details on special numbers and exceptions.
[**Errors?]
DF* DF*+ DF+ DF- DF/
SF* SF*+ SF+ SF- SF/
DFNEGATE SFNEGATE
6.9 Nearest integer functions
-----------------------------
The treatment of domain and range errors is implementation
dependent.
Behavior required by C99 for special numbers, exceptions, and
the rounding state is adopted. See especially Annex F.
FCEIL ( f: r1 -- r2 ) new C99:7.12.9.1
FLOOR ( f: r1 -- r2 ) C99:7.12.9.2
FROUND ( f: r1 -- r2 ) C99:7.12.9.6
FNEARBYINT ( f: r1 -- r2 ) new C99:7.12.9.3
FTRUNC ( f: r1 -- r2 ) new C99:7.12.9.8
The behavior of FROUND is different from that of its C99
counterpart when there is a tie. It follows DPANS94, which
uses round to nearest with even tie breakers, instead of using
the ceiling for tie breakers.
FTRUNC has already passed a CfV.
FNEARBYINT depends on the rounding state.
DFCEIL DFLOOR DFROUND DFNEARBYINT DFTRUNC
SFCEIL SFLOOR SFROUND SFNEARBYINT SFTRUNC
6.10 Math functions
-------------------
All words have C99 function counterparts.
All have double and single versions, not listed, whose
names are derived from the default versions by prefixing "D" or
"S" to the default names, all of which begin with "F".
The treatment of domain and range errors is implementation
dependent.
Any special behavior required by C99 for special numbers,
exceptions, and the rounding state is adopted. See especially
Annex F.
FMAX FMIN
F** FABS FACOS FACOSH FALOG FASIN FASINH FATAN FATAN2
FATANH FCOS FCOSH FEXP FEXPM1 FLN FLNP1 FLOG FSIN
FSINCOS FSINH FSQRT FTAN FTANH
New:
FCBRT FDIM FEXP2 FHYPOT FLOG2
FERF FERFC FLGAMMA FTGAMMA
6.11 Number classification
--------------------------
FCLASSIFY ( f: r -- s: enum ) C99:7.12.3.1
Leave the classification enum corresponding to the type of r.
The required enums are listed below. An implementation may
define and produce additional enums corresponding to other
properties, with names prefixed by "FP-".
DFCLASSIFY SFCLASSIFY
FP-INFINITE ( -- enum )
FP-NAN ( -- enum )
FP-NORMAL ( -- enum )
FP-SUBNORMAL ( -- enum )
FP-ZERO ( -- enum )
IS-FINITE ( r: r -- s: [sub]normal? ) C99:7.12.3.2
IS-FINFINITE ( r: r -- s: [+|-]Inf? ) C99:7.12.3.3
IS-FNAN ( r: r -- s: [q|s]nan? ) C99:7.12.3.4
IS-FNORMAL ( r: r -- s: normal? ) C99:7.12.3.5
Leave a true flag iff r belongs to the classification
indicated by the word name.
IS-DFINITE IS-DFINFINITE IS-DFNAN IS-DFNORMAL
IS-SFINITE IS-SFINFINITE IS-SFNAN IS-SFNORMAL
6.12 Number manipulation
------------------------
See Annex F for special behavior.
FSIGNBIT ( f: r -- s: minus? ) C99:7.12.3.6
DFSIGNBIT SFSIGNBIT
FCOPYSIGN ( f: r1 r2 -- r3 ) C99:7.12.11.1
The output r3 is r1 with its sign bit replaced by that of r2.
DFCOPYSIGN SFCOPYSIGN
FNEXTAFTER ( f: r1 r2 -- r3 ) C99:7.12.11.3
FNEXTAFTER returns the next number after r1 in the r2
direction. Words corresponding to the C99 nexttoward
functions are not implemented.
DFNEXTAFTER SFNEXTAFTER
FREXP ( f: r -- frac.r s: n ) C99:7.12.6.4
The result is unspecified if r is neither normal nor
subnormal. Return the normalized fractional part of r as a
default fp number, and the power n such that frac.r*2^n = r.
If r = 0, then n = 0. Otherwise 0.5 <= frac.r < 1.0.
DFREXP SFREXP
FMODF ( f: [int.r+frac.r] -- frac.r int.r ) C99:7.12.6.12
Decompose the input into its fraction and integer parts, both
of which have the sign of the input.
DFMODF SFMODF
FSCAL2N ( f: r s: n -- f: r*2^n.r ) C99:7.12.6.13
FSCAL2D ( f: r s: d -- f: r*2^d.r )
The output is efficiently scaled by 2^n. A range-error may
occur. The C99 scalbn and scalbln family of functions works
with an implementation-defined radix b, which is required here
to be two. The ldexp family is the explicitly radix two
version for C99. It is not implemented here.
[**Should we use the C-like names: FSCALBN FSCALBD ?]
DFSCAL2N DFSCAL2D SFSCAL2N SFSCAL2D
FLOGB ( f: r -- e.r ) C99:7.12.6.11
FILOGB ( f: r -- s: e ) C99:7.12.6.5
Leave the radix two exponent e of the fp representation. If r
is subnormal, the exponent is computed as if r were
normalized, with e < emin. For FILOGB, leave the following
special values:
r e
-----------------
+0 FP_ILOGB0
-0 FP_ILOGB0
+Inf INT_MAX
-Inf INT_MAX
nan FP_ILOGBNAN
INT_MAX is the largest signed, cell-sized integer. Let
INT_MIN be the largest magnitude, negative cell-sized integer.
FP_ILOGB0 is either -INT_MAX or INT_MIN. FP_ILOGBNAN is
either INT_MAX or INT_MIN.
DFLOGB SFLOGB DFILOGB SFILOGB
6.13 Floating-point environment
-------------------------------
[**Needs checking. C99 is especially convoluted here.]
These words are all generic.
When C99 does not require the implementation of macros and
functions corresponding to words here, those words need not be
implemented. See WG14/N1124 7.6 for details [2].
If an environmental query on the string FENV-ACCESS returns
false, none of the words defined here should be available. If
the query returns true, it also returns the address of the
default fp environment data object, which the user may wish to
store in a Forth value. That replaces the C99 FE_DEFL_ENV
macro.
The structure of fp environment objects is unknown to the user.
Their data describes the state of both exception flags and the
rounding control mode, plus other implementation-defined
information.
The next two words shall be present if the FENV-ACCESS query is
true.
FE-ALL-EXCEPT ( -- fxcpts )
The output is the bitwise OR of the exception masks
for all supported fp exceptions.
/FENV ( -- u )
The size in address units of fp environment data objects.
Used to allot data space for them, which must first be
aligned.
On the data stack, "fenva" stands for the address of an fp
environment object; and "fenvr" stands for a nonzero throw code.
All words return zero if successful, else fenvr. [**Need throw
codes.]
FEGETENV ( fenva -- 0|fenvr ) C99:7.6.4.1
Store the current fp environment data at fenva.
FESETENV ( fenva -- 0|fenvr ) C99:7.6.4.2
Set the current fp environment to that of the object stored at
fenva, without raising exceptions.
FEHOLDEXCEPT ( fenva -- 0|fenvr ) C99:7.6.4.2
Store the current fp environment data at fenva for later
restoration, clear the fp exception flags, and install an
environment that turns on a nonstop mode for all fp
exceptions. Whether a nonstop mode can be set for all
exceptions is implementation dependent.
FEUPDATEENV ( fenva -- 0|fenvr ) C99:7.6.4.4
Temporarily save the current fp environment data, set the fp
environment to that of the object stored at fenva, and raise
the exceptions temporarily saved, in that order.
6.13.1 Exceptions
-----------------
If FE-ALL-EXCEPT is zero, none of the exception words in the
following should be available.
The structure of fp exception objects is unknown to the user.
Their data describes the state of the exception flags plus other
implementation-defined information.
/FEXCEPT ( -- u )
The size in address units of fp exception data objects. Used
to allot data space for them, which must first be aligned.
In the following, "fxcpta" on the data stack stands for the
address of an fp exception object, "fxcpts" stands for
exceptions mask, and "fenvr" stands for a nonzero throw code for
failure, as before. [**Need throw codes.]
The fp exceptions correspond to the following distinct, nonzero
flag masks, which correspond to C99 constant macros with "-"
replaced by "_" in the name:
Exception masks: FE-DIVBYZERO FE-INEXACT FE-INVALID
FE-OVERFLOW FE-UNDERFLOW
Masks for any of the above exceptions that are unsupported shall
not be defined. An implementation may define other exceptions,
as long the set of flags fits into one cell. Masks may be OR'd
to form fxcpts.
FEGETEXCEPTFLAG ( fxcpta fxcpts -- 0|fenvr ) C99:7.6.2.2
Store the current state of the fp exception masks in fxcpts
in the data object at fxcpta.
FESETEXCEPTFLAG ( fxcpta fxcpts -- 0|fenvr ) C99:7.6.2.4
Set the current fp exception flags in fxcpts to the values in
the data object at fxcpta.
FETESTEXCEPT ( fxcpts -- flags ) C99:7.6.2.5
Return the bitwise OR of those fp exception masks in fxcpts
that are set in the current fp exception state.
FERAISEEXCEPT ( fxcpts -- 0|fenvr) C99:7.6.2.3
FECLEAREXCEPT ( fxcpts -- 0|fenvr) C99:7.6.2.1
Attempt to raise, respectively, clear the fp exceptions in
fxcpts.
6.13.2 Rounding modes
---------------------
In the following, "fenvr" stands for a nonzero throw code for
failure, just as before, except that the one for FEGETROUND is
[**currently] required to negative. [**Need throw codes.]
The fp rounding modes correspond to the following +enums, which
correspond to C99 constant macros with "-" replaced by "_" in
the name:
Rounding +enums: FE-DOWNWARD FE-UPWARD FE-TONEAREST
FE-TOWARDZERO
An implementation may support other rounding modes, whereupon it
shall define corresponding +enums. Words for unsupported
rounding modes shall be undefined.
[**The C99 macro FLT_ROUNDS is not implemented.]
FEGETROUND ( -- +enum|fenvr ) C99:7.6.3.1
Return the +enum corresponding to the current rounding mode.
On failure, fenvr is negative.
FESETROUND ( +enum -- 0|fenvr ) C99:7.6.3.2
Attempt to set the rounding mode corresponding to +enum iff it
is supported. If the rounding mode is set, return 0, else
fenvr.
7 FOOTNOTES AND REFERENCES
[1] ISO/IEC 9899:1999 (December 1, 1999),
ISO/IEC 9899:1999 Cor. 1:2001(E),
ISO/IEC 9899:1999 Cor. 2:2004(E),
ISO/IEC 9899:1999 Cor. 3:2007(E):
http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899
[2] C99 + TC1 + TC2 is included in WG14/N1124, May 6, 2005:
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf
[3] TC3: http://www.iec.ch/cgi-bin/getcorr.pl/yab/iso/
isoiec9899-cor3{ed1.0}en.pdf?file=iso/isoiec9899-cor3{ed1.0}en.pdf
[4] Single UNIX 3: http://www.unix.org/single_unix_specification/
[5] ANSI X3.215-1994 final draft:
http://www.taygeta.com/forth/dpans.html
[6] ISO/IEC 15145:1997:
http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2fIEC+15145%3a1997
http://www.iso.org/iso/catalogue_detail.htm?csnumber=26479