TIP 481: <code>Tcl_GetStringFromObj()</code> with <code>ptrdiff_t</code> length parameter

Author:         Jan Nijtmans <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        27-Oct-2017
Keywords:       Tcl
Tcl-Version:    8.7
Tcl-Branch:     tip-481
Vote-Summary:	Accepted 4/0/2
Votes-For:	JN, KW, KK, MC
Votes-Against:	none
Votes-Present:	FV, SL


This TIP proposes enhancing various C API functions which having a int * parameter, to be used with a ptrdiff_t * parameter as well.


In Tcl 9, the range of various functions need to be increased. For example Tcl_GetStringFromObj() is currently limited to returning 31 bit for the maximum string length. This can be fixed by introducing a new internal function which has a ptrdiff_t * parameter in stead of int *. On top of that, Tcl_GetStringFromObj() is provided as a macro, which switches between the two possible functions depending on the size of the parameter.

The same is done for Tcl_GetUnicodeFromObj() and Tcl_GetByteArrayFromObj().

This way, we have a compatibility layer, easing the transition to Tcl 9. In Tcl 8.7, although the parameter has type ptrdiff_t, the length range that can be returned is actually only 0 up to 4294967294. In Tcl 9, the full ptrdiff_t range is available.

Commits like this one (in Tk) will no longer be needed; the function TkGetStringFromObj() will just become obsolete: Tcl_GetStringFromObj() will be useable no matter the string length being stored in an int or a ptrdiff_t' variable.


Add to Tcl's stub table of public C routines the following new (internal) routines

int TclGetStringFromObj(Tcl_Obj *objPtr, ptrdiff_t *lengthPtr)

int TclGetUnicodeFromObj(Tcl_Obj *objPtr, ptrdiff_t *lengthPtr)

int TclGetByteArrayFromObj(Tcl_Obj *objPtr, ptrdiff_t *lengthPtr)

Those 3 functions do exactly the same as their existing counterparts, only the lengthPtr parameter is of type ptrdiff_t in stead of int. The original 3 functions will be wrapped in a macro of the same name, so depending on the actual size of the variable where lengthPtr points to, the switch between the two function versions are done automatically. Therefore, the new functions are not supposed to be used directly in code, usage is fully transparent through the Tcl_GetStringFromObj/Tcl_GetUnicodeFromObj/Tcl_GetByteArrayFromObj macros.


After TIP #660 was accepted, a lot of functions changed from using size_t to ptrdiff_t parameters. In order to prevent confusion, this change has been adapted in the TIP text above as well.


See the tip-481 branch in Tcl's fossil repository https://core.tcl-lang.org/tcl/timeline?r=tip-481 .