The Standard ML Basis Library


The REAL signature

The REAL signature specifies structures that implement floating-point numbers. The semantics of floating-point numbers should follow the IEEE standard [CITE]754-1985/ and the ANSI/IEEE standard [CITE]854-1987/. In addition, implementations of the REAL signature are required to use non-trapping semantics. Additional aspects of the design of the REAL and MATH signatures were guided by the Floating-Point C [CITE]Extensions/ developed by the X3J11 ANSI committee and the lecture [CITE]notes/ by W. Kahan on the IEEE standard 754.

The relation between the comparison predicates defined here and those defined by IEEE, ANSI C and FORTRAN is specified in the following table.


SML IEEE C FORTRAN
== = == .EQ.
!= ?<> != .NE.
< < < .LT.
<= <= <= .LE.
> > > .GT.
>= >= >= .GE.
?= ?= !islessgreater .UE.
not o ?= <> islessgreater .LG.
unordered ? isunordered unordered
not o unordered <=> !isunordered .LEG.
not o op < ?>= ! < .UGE.
not o op <= ?> ! <= .UG.
not o op > ?<= ! > .ULE.
not o op >= ?< ! >= .UL.

In the functions below, unless specified otherwise, if any argument is a NaN, the return value is a NaN. In a list of rules specifying the behavior of a function in special cases, the first matching rule defines the semantics.

Rationale:

The specification of the default signature and structure for non-integer arithmetic, particularly concerning exceptional conditions, was the source of much debate, given the desire of allowing implementations to provide efficient floating-point modules. Permitting implementations to differ on whether or not, for example, to raise Div on division by zero meant that the user really did not have a standard to program against. Portable code would require adopting the more conservative position of explicitly handling exceptions. A second alternative was to specify that functions in the Real structure must raise exceptions, but that implementations so desiring could provide additional structures matching REAL with explicit floating-point semantics. This was rejected because it meant that the default real type would not be the same as a defined floating-point real type. This imbued a second-class status on the latter, while providing a default real of lesser performance and involving additional implementation complexity for little benefit.

Deciding if real should be an eqtype, and if so, what should equality mean, was also problematic. IEEE specifies that the sign of zeros be ignored in comparisons, and that equality evaluate to false if either argument is a NaN. These constraints are disturbing to the SML programmer. The former implies that 0 = ~0 is true while r/0 = r/~0 is false. The latter implies such anomalies as r = r is false, or that, for a ref cell rr, we could have rr = rr but not have !rr = !rr. We accepted the unsigned comparison of zeros, but felt that the reflexive property of equality, structural equality, and the desire that <> be equivalent to not o = ought to be preserved. Additional complications led to the decision to not have real be an eqtype. Additional rationale.

The type, signature and structure identifiers real, REAL and Real, although misnomers in light of the floating-point-specific nature of the modules, were retained for historical reasons.


Synopsis

signature REAL
structure Real : REAL
structure LargeReal : REAL
structure Real{N} : REAL

Interface

type real
structure Math : MATH
val radix : int
val precision : int
val maxFinite : real
val minPos : real
val minNormalPos : real
val posInf : real
val negInf : real
val + : (real * real) -> real
val - : (real * real) -> real
val * : (real * real) -> real
val / : (real * real) -> real
val *+ : real * real * real -> real
val *- : real * real * real -> real
val ~ : real -> real
val abs : real -> real
val min : (real * real) -> real
val max : (real * real) -> real
val sign : real -> int
val signBit : real -> bool
val sameSign : (real * real) -> bool
val copySign : (real * real) -> real
val compare : (real * real) -> order
val compareReal : (real * real) -> IEEEReal.real_order
val < : (real * real) -> bool
val <= : (real * real) -> bool
val > : (real * real) -> bool
val >= : (real * real) -> bool
val == : (real * real) -> bool
val != : (real * real) -> bool
val ?= : (real * real) -> bool
val unordered : (real * real) -> bool
val isFinite : real -> bool
val isNan : real -> bool
val isNormal : real -> bool
val class : real -> IEEEReal.float_class
val fmt : StringCvt.realfmt -> real -> string
val toString : real -> string
val fromString : string -> real option
val scan : (char, 'a) StringCvt.reader -> (real, 'a) StringCvt.reader
val toManExp : real -> {man : real, exp : int}
val fromManExp : {man : real, exp : int} -> real
val split : real -> {whole : real, frac : real}
val realMod : real -> real
val rem : (real * real) -> real
val nextAfter : (real * real) -> real
val checkFloat : real ->real
val realFloor : real -> real
val realCeil : real -> real
val realTrunc : real -> real
val floor : real -> Int.int
val ceil : real -> Int.int
val trunc : real -> Int.int
val round : real -> Int.int
val toInt : IEEEReal.rounding_mode -> real -> int
val toLargeInt : IEEEReal.rounding_mode -> real -> LargeInt.int
val fromInt : int -> real
val fromLargeInt : LargeInt.int -> real
val toLarge : real -> LargeReal.real
val fromLarge : IEEEReal.rounding_mode -> LargeReal.real -> real
val toDecimal : real -> IEEEReal.decimal_approx
val fromDecimal : IEEEReal.decimal_approx -> real

Description

type real
Note that, as discussed above real is not an eqtype.

structure Math

radix
is the base of the representation, e.g., 2 or 10 for IEEE floating point.

precision
is the number of digits, each between 0 and radix-1, in the mantissa.

maxFinite
minPos
minNormalPos
are the maximum finite number, the minimum non-zero positive number and the minimum non-zero normalized number, respectively.

val posInf
val negInf
Positive and negative infinity values.

r1 + r2
r1 - r2
the sum and difference of r1 and r2. If one argument is finite and the other infinite, the result is infinite with the correct sign, e.g., 5 - (-infinity) = infinity. We also have infinity + infinity = infinity and (-infinity) + (-infinity) = (-infinity). Any other combination of two infinities produces a NaN.

r1 * r2
the product of r1 and r2. The product of zero and an infinity produces a NaN. Otherwise, if one argument is infinite, the result is infinite with the correct sign, e.g., -5 * (-infinity) = infinity, infinity * (-infinity) = -infinity.

r1 / r2
the quotient of r1 and r2. We have 0 / 0 = NaN and +-infinity / +-infinity = NaN. Dividing a finite, non-zero number by a zero, or an infinity by a finite number produces an infinity with the correct sign. (Note that zeros are signed.) A finite number divided by an infinity is 0 with the correct sign.

*+ (a, b, c)
*- (a, b, c)
return a*b + c and a*b - c, respectively. Their behaviors on infinities follow from the behaviors derived from addition, subtraction and multiplication.

The precise semantics of these operations depend on the language implementation and the underlying hardware. Specifically, certain architectures provide these operations as a single instruction, possibly using a single rounding operation. Thus, the use of these operations may be faster than performing the individual arithmetic operations sequentially, but may also cause different rounding behavior.

~ r
the negation of r, i.e., (- r). ~ (+-infinity) = -+infinity.

abs r
the absolute value of r. abs (+-infinity) = infinity.

min (a, b)
max (a, b)
returns the smaller (respectively, larger) of a and b. If exactly one argument is NaN, return the other argument. If both arguments are NaN, return NaN.

sign r
~1 if r is negative, 0 if r is zero, or 1 if r is positive. An infinity returns its sign; a zero returns 0 regardless of its sign. Raises Domain on NaN.

signBit r
returns true if and only if the sign of r (infinities, zeros and NaNs, included) is negative.

sameSign (r1, r2)
returns true if and only if signBit r1 equals signBit r2.

copySign (x, y)
returns x with the sign of y, even if y is a NaN.

compare (r1, r2)
compareReal (r1, r2)
The function compare returns LESS, EQUAL or GREATER according to whether r1 is less than, equal to, or greater than r2. It raises IEEEReal.Unordered on unordered arguments.

The function compareReal behaves similarly except it returns values of type IEEEReal.real_order and returns IEEEReal.UNORDERED on unordered arguments.

Implementation note:

Implementations should try to optimize use of Real.compare, since it is necessary for catching NaNs.



r1 < r2
r1 <= r2
r1 > r2
r1 >= r2
return true if the corresponding relation holds between the two reals.

Note that these operators return false on unordered arguments, i.e., if either argument is NaN, so that the usual reversal of comparison under negation does not hold, e.g., a < b is not the same as not (a >= b).

== (x, y)
!= (x, y)
The first returns true if and only if neither y nor x is NaN, and y and x are equal, ignoring signs on zeros. This is equivalent to the IEEE = operator.

The second function != is equivalent to not o op == and the IEEE ?<> operator.

?= (x, y)
returns true if either argument is a NaN or if the arguments are bitwise equal, ignoring signs on zeros. It is equivalent to the IEEE ?= operator.

unordered (x, y)
returns true if x and y are unordered, i.e., at least one of x and y is a NaN.

isFinite x
returns true if x is neither a NaN nor an infinity.

isNan x
returns true if x is a NaN.

isNormal x
returns true if x is normal, i.e., neither zero, subnormal, infinite nor NaN.

class x
returns the IEEEReal.float_class to which x belongs.

fmt spec r
toString r
convert reals into strings. The conversion provided by the function fmt is parameterized by spec, which has the following forms and interpretations.
SCI arg
Scientific notation: [~]d.dddE[~]dd, where there is always one digit before the decimal point, nonzero if the number is nonzero. arg specifies the number of digits to appear after the decimal point, with 6 the default if arg is NONE.
FIX arg
Fixed-point notation: [~]ddd.ddd. arg specifies the number of digits to appear after the decimal point, with 6 the default if arg is NONE.
GEN arg
Adaptive notation: the notation used is either scientific or fixed-point depending on the value converted. arg specifies the maximum number of significant digits used, with 12 the default if arg is NONE.
EXACT
Exact decimal notation: refer to IEEEReal.toString for a complete description of this format.
In all cases, positive and negative infinities are converted to "inf" and "~inf", respectively. If spec is not EXACT, NaN values are returned as "nan"; otherwise, NaN values are converted to the form "nan(d(1)d(2)...d(n))".

fmt raises Size if spec is an invalid precision, i.e., if spec is

The value returned by toString is equivalent to:

(fmt (StringCvt.GEN NONE) r)
	  


fromString s
returns SOME(r) if a real value can be scanned from a prefix of s, ignoring any initial whitespace; otherwise, returns NONE. Equivalent to StringCvt.scanString scan.

scan getc a
scans a real value from character source a using reader getc, ignoring initial whitespace. If successful, returns SOME(r,rest) where r is the scanned real value and rest is the unused portion of the character source a. Raises Overflow if the value cannot be represented in real value.

The format for valid string representation of reals is given by the regular expression

	  [+~-]?(([0-9]+(\.[0-9]+)?)|(\.[0-9]+))([eE][+~-]?[0-9]+)?
          


toManExp r
returns {man, exp}, where man and exp are the mantissa and exponent of r, respectively. Specifically, we have the relation
r = man * radix(exp)
where 1.0 <= man * radix < radix. This function is comparable to frexp in the C library.

If r is +-0, man is +-0 and exp is +0. If r is +-infinity, man is +-infinity and exp is unspecified. If r is NaN, man is Nan and exp is unspecified.

fromManExp {man, exp}
returns man * radix(exp). This function is comparable to ldexp in the C library. Note that non-exceptional arguments can produce zero or infinities, essentially because of underflows and overflows.

If man is +-0, the result is +-0. If man is +-infinity, the result is +-infinity. If man is NaN, the result is NaN.

split r
realMod r
The former returns {whole, frac}, where frac and whole are the fractional and integral parts of r, respectively. Specifically, whole is integral, |frac| < 1.0, whole and frac have the same sign as r, and r = whole + frac. This function is comparable to modf in the C library.

If r is +-infinity, whole is +-infinity and frac is +-0. If r is NaN, both whole and frac are NaN.

realMod is equivalent to #frac o split.

rem (x, y)
returns the remainder x - n*y, where n = trunc (x / y). The result has the same sign as x and has absolute value less than the absolute value of y.

If x is an infinity or y is 0, rem returns NaN. If y is an infinity, rem returns x.

nextAfter (r, t)
returns the next representable real after r in the direction of t. Thus, if t is less than r, nextAfter returns the largest representable floating-point number less than r. If r = t then it returns r. If r is +-infinity, it returns +-infinity. If either argument is a NaN, this returns NaN.

checkFloat x
raises Overflow if x is an infinity, and raises Div if x is a NaN. Otherwise, it returns its argument.

This can be used to synthesize trapping arithmetic from the non-trapping operations given here. Note, however, that infinities can be converted to NaNs by some operations, so that if accurate exceptions are required, checks must be done after each operation.

realFloor r
realCeil r
realTrunc r
truncate reals to integer-valued reals. realFloor produces the largest integer not larger than r. realCeil produces the smallest integer not less than r. realTrunc rounds r towards zero. If r is NaN or an infinity, these functions return r.

floor r
ceil r
trunc r
round r
convert reals to integers. floor produces the largest int not larger than r. ceil produces the smallest int not less than r. trunc rounds r towards zero. round yields the integer nearest to r. In the case of a tie, rounds to the nearest even integer. They raise Overflow if the resulting value cannot be represented as an int, for example, on infinity. They raise Domain on NaN arguments.

These are respectively equivalent to:

         toInt IEEEReal.TO_NEGINF r
         toInt IEEEReal.TO_POSINF r
         toInt IEEEReal.TO_ZERO r
         toInt IEEEReal.TO_NEAREST r
       


toInt mode x
toLargeInt mode x
convert the argument x to an integral type using the specified rounding mode. Raise Overflow if the result is not representable, in particular, if x is an infinity. Raise Domain if the input real is a NaN.

fromInt i
fromLargeInt i
convert integers to type real.

toLarge x
fromLarge mode x
convert between values of type real and type LargeReal.real.

toDecimal r
fromDecimal d
convert between real values and decimal approximations. Decimal approximations are to be converted using the IEEEReal.TO_NEAREST rounding mode. toDecimal should produce only as many digits as are necessary for fromDecimal to convert back to the same number, i.e., for any Normal or SubNormal real value r, we have:
    fromDecimal (toDecimal r) = r.

For toDecimal, when the kind field is not Normal or SubNormal, then exp = 0 and digits = [] except if kind is NAN, which case the digits field provides a decimal representation of the fraction field of r.

For fromDecimal, if kind is ZERO or INF, the resulting real is the appropriate signed zero or infinity, with the digits and exp fields ignored. If kind is NAN, a signed NaN is generated, where the exp field is ignored and the digits field is used as the decimal representation of the fractional field. If the resulting fractional field has all zero bits, which corresponds to an infinity, fromDecimal raises the Domain exception. If digits is empty, an implementation-dependent NaN is produced. If kind is NORMAL or SUBNORMAL, the sign, digits and exp fields are used to produce a real value. Note that the conversion itself should ignore the kind field, so that the resulting value might have class NORMAL, SUBNORMAL or ZERO. In particular, is digits is empty or a list of all 0's, the result should be a signed zero.

Implementation note:

Algorithms for accurately and efficiently converting between binary and decimal real representations are readily available, e.g., see the technical report by [CITE]Gay/.




Discussion

The sign of a zero is ignored in all comparisons.

Note that, if x is real, ~x is equivalent to ~(x), that is, it is identical to x but with its sign bit flipped. In particular, the literal ~0.0 is just 0.0 with it sign bit set. On the other hand, this might not be the same as 0.0-0.0, in which rounding modes come into play.

Except for the *+ and *- functions, arithmetic should be done in the exact precision specified by the precision value. In particular, arithmetic must not be done in some extended precision and then rounded.

Implementation note:

Implementations may choose to provide a debugging mode, in which NaNs and Infs are detected when they are generated.

See Also

MATH, IEEEReal, StringCvt

[ INDEX | TOP | Parent | Root ]

Last Modified October 5, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies