Attachment "500930.patch" to
ticket [500930ffff]
added by
dgp
2002-06-26 07:11:26.
Index: doc/StringObj.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/StringObj.3,v
retrieving revision 1.11
diff -u -r1.11 StringObj.3
--- doc/StringObj.3 24 Apr 2002 09:44:36 -0000 1.11
+++ doc/StringObj.3 26 Jun 2002 00:10:27 -0000
@@ -154,8 +154,19 @@
representation is invalid (its byte pointer is NULL), the string
representation is regenerated from the object's internal
representation. The storage referenced by the returned byte pointer
-is owned by the object manager and should not be modified by the
-caller. The procedure \fBTcl_GetString\fR is used in the common case
+is owned by the object manager. It is passed back as a writable
+pointer so that extension author creating their own \fBTcl_ObjType\fR
+will be able to modify the string representation within the
+\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that
+limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
+or \fBTcl_GetString\fR should be treated as read-only. It is
+recommended that this pointer be assigned to a (CONST char *) variable.
+Even in the limited situations where writing to this pointer is
+acceptable, one should take care to respect the copy-on-write
+semantics required by \fBTcl_Obj\fR's, with appropriate calls
+to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
+in-place modification of the string representation.
+The procedure \fBTcl_GetString\fR is used in the common case
where the caller does not need the length of the string
representation.
.PP
