From 0c41a44c782e5c13f6aa1bca5f83dfb33ecd826b Mon Sep 17 00:00:00 2001
From: "jan.nijtmans" <nijtmans@users.sourceforge.net>
Date: Fri, 3 Jan 2025 13:28:41 +0000
Subject: [PATCH] (Cherry-pick): [2bc08cd2e6] - document
 TCL_{LL,SIZE}_MODIFIER, Tcl_Size, TCL_SIZE_MAX

---
 doc/IntObj.3    | 10 ++++++++--
 doc/StringObj.3 | 26 ++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/doc/IntObj.3 b/doc/IntObj.3
index 8386bc38974..6c493dd6505 100644
--- a/doc/IntObj.3
+++ b/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
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index a31ada65482..c0d9099d96c 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -19,8 +19,10 @@ Tcl_Obj *
 Tcl_Obj *
 \fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
 .sp
+void
 \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
 .sp
+void
 \fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
 .sp
 char *
@@ -44,16 +46,22 @@ int
 Tcl_Obj *
 \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
 .sp
+void
 \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
 .sp
+void
 \fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
 .sp
+void
 \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
 .sp
+void
 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *)NULL\fR)
 .sp
+void
 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
 .sp
+void
 \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
 .sp
 Tcl_Obj *
@@ -65,8 +73,10 @@ int
 Tcl_Obj *
 \fBTcl_ObjPrintf\fR(\fIformat, ...\fR)
 .sp
+void
 \fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR)
 .sp
+void
 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
 .sp
 int
@@ -349,6 +359,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