Merge 9.0

doc/IntObj.3

@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetSizeIntFromObj, Tcl_GetWideIntFromObj, Tcl_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -124,6 +124,11 @@ typedef defined to be whatever signed integral type covers at least the
 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
 \fBlong long int\fR, or something else.
+The \fBTcl_Size\fR typedef is a signed integer type
+capable of holding the maximum permitted lengths of Tcl values like
+strings and lists. Correspondingly, the preprocessor constant
+\fBTCL_SIZE_MAX\fR defines the maximum value that can be stored
+in a variable of this type.
 The \fBmp_int\fR type is a multiple-precision integer type defined
 by the LibTomMath multiple-precision integer library.
 .PP
@@ -193,7 +198,8 @@ integer value in the \fBmp_int\fR value \fIbigValue\fR.
 arguments, but do require that the object be unshared.
 .PP
 \fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR,
-\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR,
+\fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR do not modify the reference count of their
 \fIobjPtr\fR arguments; they only read. Note however that this function may
 set the interpreter result; if that is the only place that is holding a

doc/StringObj.3

@@ -214,7 +214,7 @@ characters between \fIfirst\fR and \fIlast\fR (inclusive) in the value's
 Unicode representation.  If the value's Unicode representation
 is invalid, the Unicode representation is regenerated from the value's
 string representation.  If \fIfirst\fR is negative, then the returned
-string starts at the beginning of the value. If \fIlast\fR negative,
+string starts at the beginning of the value. If \fIlast\fR is negative,
 then the returned string ends at the end of the value.
 .PP
 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
@@ -352,6 +352,22 @@ Tcl_Obj *newPtr = \fBTcl_ObjPrintf\fR(format, ...);
 but with greater convenience and efficiency when the appending
 functionality is needed.
 .PP
+When printing integer types defined by Tcl, such as \fBTcl_Size\fR
+or \fBTcl_WideInt\fR, a format size specifier is needed as the
+integer width of those types is dependent on the Tcl version,
+platform and compiler. To accomodate these differences, Tcl defines
+C preprocessor symbols \fBTCL_LL_MODIFER\fR and
+\fBTCL_SIZE_MODIFER\fR for use when formatting values of type
+\fBTcl_WideInt\fR and \fBTcl_Size\fR respectively. Their usage
+is illustrated by
+.PP
+.CS
+Tcl_WideInt wide;
+Tcl_Size len;
+Tcl_Obj *wideObj = Tcl_ObjPrintf("wide = %" \fBTCL_LL_MODIFIER\fR "d", wide);
+Tcl_Obj *lenObj = Tcl_ObjPrintf("len = %" \fBTCL_SIZE_MODIFIER\fR "d", len);
+.CE
+.PP
 The \fBTcl_SetObjLength\fR procedure changes the length of the
 string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR
 argument is greater than the space allocated for the value's