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

Login
Home Timeline Branches Tags Help 
Author:         Jan Nijtmans <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        27-Oct-2017
Post-History:
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

Abstract

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

Rationale

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.

Specification

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.

Addendum

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.

Implementation

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