# TIP 521: Floating Point Classification Functions Bounty program for improvements to Tcl and certain Tcl packages.
``````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
``````

# 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 floatingpoint value. Returns 0 if it is any other floatingpoint 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.

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.