Author: Jan Nijtmans <[email protected]> State: Draft Type: Project Vote: Pending Created: 27-Oct-2017 Post-History: Keywords: Tcl Tcl-Version: 8.7 Tcl-Branch: tip-481
This TIP proposes enhancing various C API functions which having a
int * parameter,
to be used with a
size_t * parameter as well. In addition, a new
function is proposed which can retrieve a signed or unsigned (wide) integer or a
float/double/long double from a
In Tcl 9, the range of various functions need to be increased. For example
Tcl_GetStringFromObj now is limited to returning 32 bit for the maximum
string length. This can be fixed by introducing an internal function
Tcl_GetStringFromObj2() which has a
size_t * parameter in stead of
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
This way, we have a compatibility layer, easing the transition to Tcl 9. In Tcl 8.7, although the parameter has type size_t, the actual length range that can be returned is actually -1 up to 4294967294. In Tcl 9, the full size_t range is available.
Add to Tcl's stub table of public C routines the following new routines
int Tcl_GetStringFromObj2(Tcl_Obj *objPtr, size_t *lengthPtr)
int Tcl_GetUnicodeFromObj2(Tcl_Obj *objPtr, size_t *lengthPtr)
int Tcl_GetByteArrayFromObj2(Tcl_Obj *objPtr, size_t *lengthPtr)
Those 3 functions do exactly the same as their existing counterparts, only the lengthPtr parameter is of type size_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. So, the new functions don't need to be used in code, the original function can be used pointing to a size_t length variable as well.
int Tcl_GetValue(Tcl_Interp *interp, Tcl_Obj *objPtr, void *valuePtr, int flags)
This functions is able to function the same as Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideFromObj and Tcl_GetDoubleFromObj. The flags argument determines the actual conversion done. The following flags are possible.
TCL_TYPE_I(int | long | Tcl_WideInt) : valuePtr points at an integer of given size
TCL_TYPE_U(int | long | Tcl_WideInt) : valuePtr points at an unsigned integer of given size
TCL_TYPE_D(float | double) : valuePtr points at a float or double
Those 3 macro's use the sizeof() macro on the type to provide the requested size to Tcl_GetValue(). Actually, you can use any integer type, so e.g. size_t or intmax_t work as well.
int Tcl_GetUIntFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, void *valuePtr)
This is a wrapper macro around Tcl_GetValue, handling unsigned integer values only.
For Tcl 9.0, the function Tcl_GetIntFromObj is modified to return 1 when the Tcl_Obj value is in the range -2147483648 .. 2147483647.
See the tip-481 branch in Tcl's fossil repository https://core.tcl.tk/tcl/timeline?r=tip-481 .