Author:         Kevin B. Kenny <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        21 October 2018
Post-History:
Tcl-Version:    8.7
Keywords:       Tcl, floating point, NaN, not a number
Tcl-Branch:     tip-521
Votes-For:      DKF, BG, KBK, JN, DGP, FV, AK
Votes-Against:  none
Votes-Present:  SL

---

Abstract

This TIP proposes that the functions, isfinite, isinf, isnan, isnormal, issubnormal and isunordered be added to the standard set of Tcl mathematical functions, and that fpclassify be added to the standard set of Tcl commands.

Background

The discussion of TIP 520 has revealed an additional shortcoming in Tcl's model of floating point values: it provides no easy way to classify them in terms of whether they are:

• finite or infinite
• unexceptional or Not-a-Number (NaN)
• normal or subnormal (that is, in the ordinary arithmetic range or gradually underflowed)

The functions can be worked around from behaviours: for instance, [if {$x != $x} {...}] will test for NaN, but these tests are somewhat obscure and may also be fragile.

This TIP proposes to add the necessary classifiers.

Proposal

The set of mathematical functions shall be expanded to include the following:

• isfinite(value)

Returns 1 if value is finite. that is, if it is zero, subnormal, or normal. Returns 0 if the number is infinite or NaN. Throws an error if value cannot be promoted to a floating-point value.

• isinf(value)

Returns 1 if value is infinite. Returns 0 for anything else, that is, if it is zero, subnormal, normal or NaN. Throws an error if value cannot be promoted to a floating-point value.

• isnan(value)

Returns 1 if value is a Not-a-Number. Returns 0 for anything else, that is, if it is zero, subnormal, normal or infinite. Throws an error if value cannot be promoted to a floating-point value.

• isnormal(value)

Returns 1 if value is a normal floating_point value. Returns 0 if it is any other floating_point value, that is, if it is zero, subnormal, infinite or NaN. Throws an error if value cannot be promoted to a floating-point value.

• issubnormal(value)

Returns 1 if value is a subnormal number, that is, the result of a gradual underflow. Returns 0 if the number is anything else (zero, normal, infinite, or NaN). Throws an error if value cannot be promoted to a floating-point value.

• isunordered(value1, value2)

Returns 1 if value1 and value2 cannot be compared for ordering, that is, if either one is NaN. Returns 0 if both values can be ordered, that is, if they are both chosen from among the set of zero, subnormal, normal and infinite values. Throws an error if either value1 or value2 cannot be promoted to a floating-point value.

The set of Tcl commands shall be augmented with the following:

• fpclassify value

Returns one of the following strings:

zero - value is a floating point zero

subnormal - value is the result of a gradual underflow

normal - value is an ordinary floating-point number (not zero, subnormal, infinite, nor NaN).

infinite - value is a floating-point infinity

nan - value is Not-a-Number.

Throws an error if value is not a floating-point value.

Reference implementation

To be developed.

Note

This TIP is intended as a companion TIP to TIP 520, but the functions are thought to be useful irrespective of whether 520 is accepted. Hence, it is being proposed separately.