Revise the interface routines for byte arrays to use "numBytes" rather than

"length" as argument names.

1 files changed, 26 insertions, 25 deletions

diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index a8b70eb..0703164 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -8,44 +8,44 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_GetBytesFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate a Tcl value as an array of bytes
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 Tcl_Obj *
-\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR)
+\fBTcl_NewByteArrayObj\fR(\fIbytes, numBytes\fR)
 .sp
 void
-\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR)
+\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, numBytes\fR)
 .sp
 .VS TIP568
 unsigned char *
-\fBTcl_GetBytesFromObj\fR(\fIinterp, objPtr, lengthPtr\fR)
+\fBTcl_GetBytesFromObj\fR(\fIinterp, objPtr, numBytesPtr\fR)
 .VE TIP568
 .sp
 unsigned char *
-\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR)
+\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, numBytesPtr\fR)
 .sp
 unsigned char *
-\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
+\fBTcl_SetByteArrayLength\fR(\fIobjPtr, numBytes\fR)
 .SH ARGUMENTS
-.AS "const unsigned char" *lengthPtr in/out
-.AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+.AS "const unsigned char" *numBytesPtr in/out
 .AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array value. May be NULL
-even if \fIlength\fR is non-zero.
-.AP int length in
-The length of the array of bytes.  It must be >= 0.
+even if \fInumBytes\fR is non-zero.
+.AP int numBytes in
+The number of bytes in the array.  It must be >= 0.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be
 overwritten by a byte-array value.  For \fBTcl_GetBytesFromObj\fR,
 \fBTcl_GetByteArrayFromObj\fR and \fBTcl_SetByteArrayLength\fR, this points
-to the value from which to extract a byte-array value.
-.AP "size_t | int" *lengthPtr out
-Points to space to be filled with the length of the array of bytes extracted
-from \fIobjPtr\fR.  May be NULL when the caller does not need the length.
+to the value from which to extract an array of bytes.
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP "size_t | int" *numBytesPtr out
+Points to space where the number of bytes in the array may be written.
+Caller may pass NULL when it does not need this information.
 .BE
 
 .SH DESCRIPTION
@@ -66,11 +66,11 @@ Modified UTF-8 encoding.
 .PP
 \fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR 
 create a new value or overwrite an existing unshared value, respectively,
-to hold a byte-array value of \fIlength\fR bytes.  \fBTcl_NewByteArrayObj\fR
+to hold a byte-array value of \fInumBytes\fR bytes.  \fBTcl_NewByteArrayObj\fR
 returns a pointer to the created value with a reference count of zero.
 \fBTcl_SetByteArrayObj\fR overwrites and invalidates any old contents
 as appropriate, and keeps the same reference count (0 or 1).  When
-the \fIbytes\fR argument passed to either routine is not NULL, \fIlength\fR
+the \fIbytes\fR argument passed to either routine is not NULL, \fInumBytes\fR
 bytes are copied from \fIbytes\fR into the new value. When
 the \fIbytes\fR argument passed to either routine is NULL, the
 contents of the resulting byte array value are undefined.  A \fIbytes\fR
@@ -81,8 +81,8 @@ only on unshared values, and accompanied by all appropriate invalidations.
 .PP
 \fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
 returns a pointer to the value's new internal representation as an array of
-bytes.  The length of this array is stored in \fIlengthPtr\fR if
-\fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
+bytes.  The number of bytes in this array is stored in \fInumBytesPtr\fR if
+\fInumBytesPtr\fR is non-NULL.  The storage for the array of bytes is owned by
 the value and should not be freed.  The contents of the array may be
 modified by the caller only if the value is not shared and the caller
 invalidates the string representation.
@@ -92,11 +92,12 @@ the difference is that this function can error if the object contains
 characters > 255. If \fBinterp\fR is not NULL, an error-message will be left there.
 .PP
 \fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type
-and changes the length of the value's internal representation as an
-array of bytes.  If \fIlength\fR is greater than the space currently
-allocated for the array, the array is reallocated to the new length; the
-newly allocated bytes at the end of the array have arbitrary values.  If
-\fIlength\fR is less than the space currently allocated for the array,
+and changes the number of bytes in the value's internal representation as an
+array of bytes.  If \fInumBytes\fR is greater than the space currently
+allocated for the array, the array is reallocated be large enough to store
+the larger number of bytes; the newly allocated bytes at the end of the
+array have arbitrary values.  If
+\fInumBytes\fR is less than the space currently allocated for the array,
 the length of array is reduced to the new length.  The return value is a
 pointer to the value's new array of bytes.