```
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

valueis finite. that is, if it is zero, subnormal, or normal. Returns 0 if the number is infinite or`NaN`

. Throws an error ifvaluecannot be promoted to a floating-point value.

`isinf`

(*value*)

Returns 1 if

valueis infinite. Returns 0 for anything else, that is, if it is zero, subnormal, normal or`NaN`

. Throws an error ifvaluecannot be promoted to a floating-point value.

`isnan`

(*value*)

Returns 1 if

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

`isnormal`

(*value*)

Returns 1 if

valueis 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 ifvaluecannot be promoted to a floating-point value.

`issubnormal`

(*value*)

Returns 1 if

valueis 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 ifvaluecannot be promoted to a floating-point value.

`isunordered`

(*value1*,*value2*)

Returns 1 if

value1andvalue2cannot 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 eithervalue1orvalue2cannot 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`

-valueis a floating point zero

`subnormal`

-valueis the result of a gradual underflow

`normal`

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

`infinite`

-valueis a floating-point infinity

`nan`

-valueis Not-a-Number.Throws an error if

valueis 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.