From 6eceb08de21bddce6cacfd581a5b3bc08a1a431c Mon Sep 17 00:00:00 2001 From: dgp Date: Sun, 7 Nov 2021 20:39:32 +0000 Subject: Document the freedom to provide space of either type int or size_t. --- doc/ByteArrObj.3 | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index 1702c3a..fd7f245 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -151,6 +151,14 @@ has not been disturbed. The pointer may be used to overwrite the byte contents of the internal representation, so long as the value is unshared and any string representation is invalidated. .PP +On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR +write the number of bytes in the byte-array value of \fIobjPtr\fR +to the space pointed to by \fInumBytesPtr\fR. This space may be of type +\fBsize_t\fR or of type \fBint\fR. In Tcl 8, the largest number of +bytes possible is \fBINT_MAX\fR, so either type can receive the value. +In codebases meant to migrate to Tcl 9, the option to write to a space +of type \fBsize_t\fR may aid in the migration. +.PP \fBTcl_SetByteArrayLength\fR enables a caller to change the size of a byte-array in the internal representation of an unshared \fIobjPtr\fR to become \fInumBytes\fR bytes. This is most often useful after the -- cgit v0.12