Check-in [7559790b52]

	Post-History:   
	Keywords:       Tcl
	Tcl-Version:	8.7
-----

# Abstract

This TIP proposes to resolve the platform differences between int/wide math functions and commands like "sting is integer"/"string is wide".
At the script level it should not be relevant whether the platform is 32-bit or 64-bit any more.

Originally, the int() math function was meant to be provide compatibility when introducing big integers using the libtommath library.
Code depending on the modulo behavior of all expressions could use the int() function to make the behavior the same as in Tcl 8.4 again.
In practice, the int() math function is rarely used.

# Rationale

Some examples:

<pre>
% string is int -4294967296
................................................................................
-9223372036854775808
</pre>

So, int() does either 32-bit or 64-bit truncation, but the highest left-over bit becomes the sign-bit. wide() does 64-bit truncation.

# Specification

 * On all platforms, the int() math function is modified to do 64-bit truncation, as it already does on [LP64/ILP64](https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models) systems (e.g. 64-bit Linux).
   int() will thus become synonym for wide(). The wide() function will become deprecated in Tcl 9.0, but it will not be removed yet.

 * The ranges of "string is integer" and "string is wideinteger" are changed to match the range of the int()/wide() math function.
   So these functions will report true (1) if the number is in the range -9223372036854775808..9223372036854775807.
   The "string is wideinteger" command will be deprecated in Tcl 9.0, but it will not be removed yet.

 * The C function Tcl\_GetIntFromObj() is changed to return TCL\_OK if the Tcl_Obj contains a value in the range of -2147483648..4294967295. So,
   it succeeds if the number fits in either a platform "int", either a platform "unsigned int" type.

 * The C function Tcl\_GetWideIntFromObj() is changed to return TCL\_OK if the Tcl_Obj contains a value in the range of -9223372036854775808..9223372036854775807.
   So, it succeeds if the number fits in a Tcl_WideInt.

 * The C function Tcl\_GetLongFromObj() is changed to behave like Tcl\_GetIntFromObj() if sizeof(long) == sizeof(int), and to behave like Tcl\_GetWideIntFromObj() if sizeof(long) == sizeof(Tcl_WideInt)












# Implementation

Currently, the proposed implementation is available in the [all-wideint branch]
(https://core.tcl.tk/tcl/timeline?r=all-wideint).

# Copyright

This document has been placed in the public domain.

	Post-History:   
	Keywords:       Tcl
	Tcl-Version:	8.7
-----

# Abstract

This TIP proposes to resolve the platform differences between int/wide/entier math functions and commands like "sting is integer"/"string is wide"/"string is entier".
At the script level it should not be relevant whether the platform is 32-bit or 64-bit any more.

Most Tcl command already accept unlimited integers, so there are hardly any commands left which need to checked for correct range.
A few lacking places (e.g. "binary scan" and "binary format"), are corrected as part of this TIP implementation.


# Rationale

Some examples:

<pre>
% string is int -4294967296
................................................................................
-9223372036854775808
</pre>

So, int() does either 32-bit or 64-bit truncation, but the highest left-over bit becomes the sign-bit. wide() does 64-bit truncation.

# Specification

 * On all platforms, the int() math function is modified not to do truncation any more.
   int() will thus become synonym for entier(). The wide() and entier() functions will become deprecated in Tcl 9.0, but they will not be removed yet.

 * On all platforms, "string is integer" will become synonym to "string is entier".
   So these functions will report true (1) if the number looks like an integer with unlimited range.
   The "string is wideinteger" and "string is entier" commands will become deprecated in Tcl 9.0, but they will not be removed yet.

 * The C function Tcl\_GetIntFromObj() is changed to return TCL\_OK if the Tcl_Obj contains a value in the range of -2147483648..4294967295. So,
   it succeeds if the number fits in either a platform "int", either a platform "unsigned int" type.

 * The C function Tcl\_GetWideIntFromObj() is changed to return TCL\_OK if the Tcl\_Obj contains a value in the range of -9223372036854775808..9223372036854775807.
   So, it succeeds if the number fits in a Tcl\_WideInt.

 * The C function Tcl\_GetLongFromObj() is changed to behave like Tcl\_GetIntFromObj() if sizeof(long) == sizeof(int), and to behave like Tcl\_GetWideIntFromObj() if sizeof(long) == sizeof(Tcl_WideInt)

# Implications

 * "string is integer" can no longer be used to check for a specific range.
   That doesn't matter any more, because the command argument that was being protected, doesn't throw an exception any more in case of under/overflow since the introduction of bignums.

 * int() can no longer be used for 32-bit/64-bit (platform-dependant) truncation.

 * If you still really want to protect some command argument from overflowing, Use Tcl\_GetWideIntFromObj() in this command, and use "string is wide" to check for proper range.
   But - still better - is use Tcl\_GetWideIntFromObj(), with falling back to Tcl\_GetBignumFromObj() if the range requires it.
   That's what Tcl itself is doing almost everywhere to prevent under/overflow errors.

# Implementation

Currently, the proposed implementation is available in the [all-wideint branch]
(https://core.tcl.tk/tcl/timeline?r=tip-514).

# Copyright

This document has been placed in the public domain.