diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/Object.3 | 16 | ||||
| -rw-r--r-- | doc/StringObj.3 | 15 |
3 files changed, 25 insertions, 12 deletions
@@ -1,3 +1,9 @@ +2002-10-22 Donal K. Fellows <fellowsd@cs.man.ac.uk> + + * doc/StringObj.3, doc/Object.3: Documented that Tcl_Obj's + standard string form is a modified UTF-8; apparently, this was not + mentioned anywhere in the main docs, and lead to [Bug 624919]. + 2002-10-21 Daniel Steffen <das@users.sourceforge.net> * macosx/Tcl.pbproj/project.pbxproj: bumped version to 8.4.1 diff --git a/doc/Object.3 b/doc/Object.3 index 5df5bf9..d116b37 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -4,10 +4,10 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Object.3,v 1.5 2000/07/24 00:03:02 jenglish Exp $ +'\" RCS: @(#) $Id: Object.3,v 1.6 2002/10/22 12:16:53 dkf Exp $ '\" .so man.macros -.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_Obj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects @@ -129,15 +129,17 @@ typedef struct Tcl_Obj { } Tcl_Obj; .CE The \fIbytes\fR and the \fIlength\fR members together hold -an object's string representation, -which is a \fIcounted\fR or \fIbinary string\fR -that may contain binary data with embedded null bytes. +.VS 8.1 +an object's UTF-8 string representation, +which is a \fIcounted string\fR not containing null bytes (UTF-8 null +characters should be encoded as a two byte sequence: 192, 128.) \fIbytes\fR points to the first byte of the string representation. The \fIlength\fR member gives the number of bytes. -The byte array must always have a null after the last byte, +The byte array must always have a null byte after the last data byte, at offset \fIlength\fR; -this allows string representations that do not contain nulls +this allows string representations to be treated as conventional null-terminated C strings. +.VE 8.1 C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get an object's string representation. If \fIbytes\fR is NULL, diff --git a/doc/StringObj.3 b/doc/StringObj.3 index df2eafc..8d43dc6 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StringObj.3,v 1.12 2002/06/26 11:50:52 msofer Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.13 2002/10/22 12:16:53 dkf Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" @@ -72,12 +72,17 @@ int Tcl_Obj * \fBTcl_ConcatObj\fR(\fIobjc, objv\fR) .SH ARGUMENTS -.AS Tcl_Interp *appendObjPtr in/out +.AS "CONST Tcl_UniChar" *appendObjPtr in/out .AP "CONST char" *bytes in -Points to the first byte of an array of bytes +.VS 8.1 +Points to the first byte of an array of UTF-8-encoded bytes used to set or append to a string object. -This byte array may contain embedded null bytes -unless \fIlength\fR is negative. +This byte array should not contain embedded null bytes +unless \fIlength\fR is negative. (Applications needing null bytes +should represent them as the two-byte sequence \fI\\700\\600\fR, use +\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if +the string is a collection of uninterpreted bytes.) +.VE 8.1 .AP int length in The number of bytes to copy from \fIbytes\fR when initializing, setting, or appending to a string object. |