1 files changed, 118 insertions, 33 deletions
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 46fe959..d195362 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -4,38 +4,71 @@
 '\" 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.4 1999/04/16 00:46:33 stanton Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.5 1999/06/15 01:16:21 hershey Exp $
 '\" 
 .so man.macros
 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .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)
 .sp
+Tcl_UniChar
+\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
+.sp
+int
+\fBTcl_GetCharLength\fR(\fIobjPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
+.VE
+.sp
+void
 \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
-.VS
+.VS 8.1.2
 .sp
-\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
+void
+\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
 .VE
 .sp
+void
+\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
+.sp
+void
 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
 .sp
+void
 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
 .sp
+void
 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
 .sp
 Tcl_Obj *
@@ -51,12 +84,29 @@ unless \fIlength\fR is negative.
 The number of bytes to copy from \fIbytes\fR when
 initializing, setting, or appending to a string object.
 If negative, all bytes up to the first null are used.
+.AP Tcl_UniChar *unicode in
+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.
+If negative, all characters up to the first null character are used.
+.AP int index in
+The index of the Unicode character to return.
+.AP int first in
+The index of the first Unicode character in the Unicode range to be
+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.
-.VS
 .AP Tcl_Obj *appendObjPtr in
 The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
-.VE
 .AP int *lengthPtr out
 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
 the the length of an object's string representation.
@@ -82,39 +132,74 @@ 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
 .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_NewStringObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object to hold a copy of the specified string.
-\fBTcl_SetStringObj\fR frees any old string representation
-as well as any old internal representation of the object.
+or modify an existing object to hold a copy of the string given by
+\fIbytes\fR and \fIlength\fR.  \fBTcl_NewUnicodeObj\fR and
+\fBTcl_SetUnicodeObj\fR create a new object or modify an existing
+object to hold a copy of the Unicode string given by \fIunicode\fR and
+\fInumChars\fR.  \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
+return a pointer to a newly created object with reference count zero.
+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
+(for \fBTcl_GetStringFromObj\fR) length, which is stored in
+\fIlengthPtr\fR if it is non-NULL.  If the object's UTF string
+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
+where the caller does not need the length of the string
+representation.
 .PP
-\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR
-return an object's string representation.
-This is given by the returned byte pointer
-and (for \fBTcl_GetStringFromObj\fR) length,
-which is stored in \fIlengthPtr\fR if it is non-NULL.
-If the object's string 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
-where the caller does not need the length of the string representation.
+.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.
+.PP
+\fBTcl_GetRange\fR returns a newly created object comprised of the
+characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
+object's Unicode representation.  If the object's Unicode
+representation is invalid, the Unicode representation is regenerated
+from the object's string representation.
+.PP
+\fBTcl_GetCharLength\fR returns the number of characters (as opposed
+to bytes) in the string object.
 .PP
 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
-\fIlength\fR to the object specified by \fIobjPtr\fR.  It does this
-in a way that handles repeated calls relatively efficiently (it
-overallocates the string space to avoid repeated reallocations
-and copies of object's string value).
-.VS
+\fIlength\fR to the string representation of the object specified by
+\fIobjPtr\fR.  If the object has an invalid string representation,
+then an attempt is made to convert \fIbytes\fR is to the Unicode
+format.  If the conversion is successful, then the converted form of
+\fIbytes\fR is appended to the object's Unicode representation.
+Otherwise, the object's Unicode representation is invalidated and
+converted to the UTF format, and \fIbytes\fR is appended to the
+object's new string representation.
+.PP
+\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
+\fIunicode\fR and \fInumChars\fR to the object specified by
+\fIobjPtr\fR.  If the object has an invalid Unicode representation,
+then \fIunicode\fR is converted to the UTF format and appended to the
+object's string representation.  Appends are optimized to handle
+repeated appends relatively efficiently (it overallocates the string
+or Unicode space to avoid repeated reallocations and copies of
+object's string value).
 .PP
 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
-appends the string value of \fIappendObjPtr\fR to \fIobjPtr\fR.
+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
@@ -158,4 +243,4 @@ Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
 
 .SH KEYWORDS
 append, internal representation, object, object type, string object,
-string type, string representation, concat, concatenate
+string type, string representation, concat, concatenate, unicode