summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2002-10-22 12:16:52 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2002-10-22 12:16:52 (GMT)
commit5356bb251e4978b7dc52fb21ee811b516ef2329f (patch)
tree78bb48178b7ca498830be71dfb41beb86e600845
parentbcd296f1929aa83bdf5693c9fbc268c61a55784e (diff)
downloadtcl-5356bb251e4978b7dc52fb21ee811b516ef2329f.zip
tcl-5356bb251e4978b7dc52fb21ee811b516ef2329f.tar.gz
tcl-5356bb251e4978b7dc52fb21ee811b516ef2329f.tar.bz2
Documentation didn't say that the UTF-8-rep of a Tcl_Obj was UTF-8 (sans NUL)!
[Bug 624919]
-rw-r--r--ChangeLog6
-rw-r--r--doc/Object.316
-rw-r--r--doc/StringObj.315
3 files changed, 25 insertions, 12 deletions
diff --git a/ChangeLog b/ChangeLog
index 134257d..5dd8996 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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.