summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorhobbs <hobbs>2001-08-31 17:59:32 (GMT)
committerhobbs <hobbs>2001-08-31 17:59:32 (GMT)
commit64560d95933f485db584e3a2bdedb5c7d8362420 (patch)
tree938058fcc3d10fd988024abd39b2d4df0d97cff1 /doc
parent817b9b601b9d9554766f2d5993eff50a07a733d6 (diff)
downloadtcl-64560d95933f485db584e3a2bdedb5c7d8362420.zip
tcl-64560d95933f485db584e3a2bdedb5c7d8362420.tar.gz
tcl-64560d95933f485db584e3a2bdedb5c7d8362420.tar.bz2
* doc/StringObj.3: added words of warning to use Tcl_ResetResult
with the Tcl_Append* functions.
Diffstat (limited to 'doc')
-rw-r--r--doc/StringObj.322
1 files changed, 5 insertions, 17 deletions
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index b1c5c00..f21c667 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.8 2001/04/06 23:14:08 andreas_kupries Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.9 2001/08/31 17:59:32 hobbs Exp $
'\"
.so man.macros
.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -17,26 +17,21 @@ Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_Ge
.sp
Tcl_Obj *
\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
-.VS 8.1.2
.sp
Tcl_Obj *
\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
-.VE
.sp
void
\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
-.VS 8.1.2
.sp
void
\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
-.VE
.sp
char *
\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
.sp
char *
\fBTcl_GetString\fR(\fIobjPtr\fR)
-.VS 8.1.2
.sp
Tcl_UniChar *
\fBTcl_GetUnicode\fR(\fIobjPtr\fR)
@@ -49,15 +44,12 @@ int
.sp
Tcl_Obj *
\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
-.VE
.sp
void
\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
-.VS 8.1.2
.sp
void
\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
-.VE
.sp
void
\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
@@ -92,7 +84,6 @@ Points to the first byte of an array of Unicode characters
used to set or append to a string object.
This byte array may contain embedded null characters
unless \fInumChars\fR is negative.
-.VS 8.1.2
.AP int numChars in
The number of Unicode characters to copy from \fIunicode\fR when
initializing, setting, or appending to a string object.
@@ -105,7 +96,6 @@ returned as a new object.
.AP int last in
The index of the last Unicode character in the Unicode range to be
returned as a new object.
-.VE
.AP Tcl_Obj *objPtr in/out
Points to an object to manipulate.
.AP Tcl_Obj *appendObjPtr in
@@ -135,12 +125,13 @@ of the object to store additional information to make the string
manipulations more efficient. In particular, they make a series of
append operations efficient by allocating extra storage space for the
string so that it doesn't have to be copied for each append.
-.VS 8.1.2
Also, indexing and length computations are optimized because the
Unicode string representation is calculated and cached as needed.
-.VE
+When using the \fBTcl_Append*\fR family of functions where the
+interpreter's result is the object being appended to, it is important
+to call Tcl_ResetResult first to ensure you are not unintentionally
+appending to existing data in the result object.
.PP
-.VS 8.1.2
\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
or modify an existing object to hold a copy of the string given by
\fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and
@@ -152,7 +143,6 @@ All four procedures set the object to hold a copy of the specified
string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
old string representation as well as any old internal representation
of the object.
-.VE
.PP
\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
string representation. This is given by the returned byte pointer and
@@ -166,7 +156,6 @@ caller. The procedure \fBTcl_GetString\fR is used in the common case
where the caller does not need the length of the string
representation.
.PP
-.VS 8.1.2
\fBTcl_GetUnicode\fR returns an object's value as a Unicode string.
\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
object's Unicode representation.
@@ -203,7 +192,6 @@ object's string value).
appends the string or Unicode value (whichever exists and is best
suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
\fIobjPtr\fR.
-.VE
.PP
\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
except that it can be passed more than one value to append and