spurious underflow signals.  The other option is provided for compatibility
with some systems.  Like most systems, SoftFloat always detects loss of
accuracy for underflow as an inexact result.


----------------------------------------------------------------------------
Function Details

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Conversion Functions

All conversions among the floating-point formats are supported, as are all
conversions between a floating-point format and 32-bit and 64-bit signed
integers.  The complete set of conversion functions is:

   int32_to_float32      int64_to_float32
   int32_to_float64      int64_to_float32
   int32_to_floatx80     int64_to_floatx80
   int32_to_float128     int64_to_float128

   float32_to_int32      float32_to_int64
   float32_to_int32      float64_to_int64
   floatx80_to_int32     floatx80_to_int64
   float128_to_int32     float128_to_int64

   float32_to_float64    float32_to_floatx80   float32_to_float128
   float64_to_float32    float64_to_floatx80   float64_to_float128
   floatx80_to_float32   floatx80_to_float64   floatx80_to_float128
   float128_to_float32   float128_to_float64   float128_to_floatx80

Each conversion function takes one operand of the appropriate type and
returns one result.  Conversions from a smaller to a larger floating-point
format are always exact and so require no rounding.  Conversions from 32-bit
integers to double precision and larger formats are also exact, and likewise
for conversions from 64-bit integers to extended double and quadruple
precisions.

Conversions from floating-point to integer raise the invalid exception if
the source value cannot be rounded to a representable integer of the desired
size (32 or 64 bits).  If the floating-point operand is a NaN, the largest
positive integer is returned.  Otherwise, if the conversion overflows, the
largest integer with the same sign as the operand is returned.

On conversions to integer, if the floating-point operand is not already
an integer value, the operand is rounded according to the current rounding
mode as specified by `float_rounding_mode'.  Because C (and perhaps other
languages) require that conversions to integers be rounded toward zero, the
following functions are provided for improved speed and convenience:

   float32_to_int32_round_to_zero    float32_to_int64_round_to_zero
   float64_to_int32_round_to_zero    float64_to_int64_round_to_zero
   floatx80_to_int32_round_to_zero   floatx80_to_int64_round_to_zero
   float128_to_int32_round_to_zero   float128_to_int64_round_to_zero

These variant functions ignore `float_rounding_mode' and always round toward
zero.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Standard Arithmetic Functions

The following standard arithmetic functions are provided:

   float32_add    float32_sub    float32_mul    float32_div    float32_sqrt
   float64_add    float64_sub    float64_mul    float64_div    float64_sqrt
   floatx80_add   floatx80_sub   floatx80_mul   floatx80_div   floatx80_sqrt
   float128_add   float128_sub   float128_mul   float128_div   float128_sqrt

Each function takes two operands, except for `sqrt' which takes only one.
The operands and result are all of the same type.

Rounding of the extended double-precision (`floatx80') functions is affected
by the `floatx80_rounding_precision' variable, as explained above in the
section _Extended Double-Precision Rounding Precision_.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Remainder Functions

For each format, SoftFloat implements the remainder function according to
the IEC/IEEE Standard.  The remainder functions are:

   float32_rem
   float64_rem
   floatx80_rem
   float128_rem

Each remainder function takes two operands.  The operands and result are all
of the same type.  Given operands x and y, the remainder functions return
the value x - n*y, where n is the integer closest to x/y.  If x/y is exactly
halfway between two integers, n is the even integer closest to x/y.  The
remainder functions are always exact and so require no rounding.

Depending on the relative magnitudes of the operands, the remainder
functions can take considerably longer to execute than the other SoftFloat
functions.  This is inherent in the remainder operation itself and is not a
flaw in the SoftFloat implementation.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Round-to-Integer Functions

For each format, SoftFloat implements the round-to-integer function
specified by the IEC/IEEE Standard.  The functions are:

   float32_round_to_int
   float64_round_to_int
   floatx80_round_to_int
   float128_round_to_int

Each function takes a single floating-point operand and returns a result of
the same type.  (Note that the result is not an integer type.)  The operand
is rounded to an exact integer according to the current rounding mode, and
the resulting integer value is returned in the same floating-point format.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Comparison Functions

The following floating-point comparison functions are provided:

   float32_eq    float32_le    float32_lt
   float64_eq    float64_le    float64_lt
   floatx80_eq   floatx80_le   floatx80_lt
   float128_eq   float128_le   float128_lt

Each function takes two operands of the same type and returns a 1 or 0
representing either _true_ or _false_.  The abbreviation `eq' stands for
``equal'' (=); `le' stands for ``less than or equal'' (<=); and `lt' stands
for ``less than'' (<).

The standard greater-than (>), greater-than-or-equal (>=), and not-equal
(!=) functions are easily obtained using the functions provided.  The
not-equal function is just the logical complement of the equal function.
The greater-than-or-equal function is identical to the less-than-or-equal
function with the operands reversed, and the greater-than function is
identical to the less-than function with the operands reversed.

The IEC/IEEE Standard specifies that the less-than-or-equal and less-than
functions raise the invalid exception if either input is any kind of NaN.
The equal functions, on the other hand, are defined not to raise the invalid
exception on quiet NaNs.  For completeness, SoftFloat provides the following
additional functions:

   float32_eq_signaling    float32_le_quiet    float32_lt_quiet
   float64_eq_signaling    float64_le_quiet    float64_lt_quiet
   floatx80_eq_signaling   floatx80_le_quiet   floatx80_lt_quiet
   float128_eq_signaling   float128_le_quiet   float128_lt_quiet

The `signaling' equal functions are identical to the standard functions
except that the invalid exception is raised for any NaN input.  Likewise,
the `quiet' comparison functions are identical to their counterparts except
that the invalid exception is not raised for quiet NaNs.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Signaling NaN Test Functions

The following functions test whether a floating-point value is a signaling
NaN:

   float32_is_signaling_nan
   float64_is_signaling_nan
   floatx80_is_signaling_nan
   float128_is_signaling_nan

The functions take one operand and return 1 if the operand is a signaling
NaN and 0 otherwise.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Raise-Exception Function

SoftFloat provides a function for raising floating-point exceptions:

    float_raise

The function takes a mask indicating the set of exceptions to raise.  No
result is returned.  In addition to setting the specified exception flags,
this function may cause a trap or abort appropriate for the current system.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


----------------------------------------------------------------------------
Contact Information

At the time of this writing, the most up-to-date information about
SoftFloat and the latest release can be found at the Web page `http://
www.cs.berkeley.edu/~jhauser/arithmetic/SoftFloat.html'.