First stage of doing GOOBE improvements to documentation now that the html generation works

1 files changed, 272 insertions, 272 deletions

diff --git a/doc/StringObj.3 b/doc/StringObj.3
index f326315..78b801e 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -1,272 +1,272 @@
-'\"
-'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
-'\"
-'\" 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.20 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
-.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_Obj *
-\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
-.sp
-Tcl_Obj *
-\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
-.sp
-void
-\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
-.sp
-void
-\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
-.sp
-char *
-\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
-.sp
-char *
-\fBTcl_GetString\fR(\fIobjPtr\fR)
-.sp
-Tcl_UniChar *
-\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)
-.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)
-.sp
-void
-\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
-.sp
-void
-\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
-.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
-int
-\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)
-.sp
-Tcl_Obj *
-\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
-.SH ARGUMENTS
-.AS "const Tcl_UniChar" *appendObjPtr in/out
-.AP "const char" *bytes in
-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 characters
-unless \fInumChars\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.)
-.AP int length in
-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 "const 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.
-.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.
-.AP Tcl_Obj *objPtr in/out
-Points to an object to manipulate.
-.AP Tcl_Obj *appendObjPtr in
-The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
-.AP int *lengthPtr out
-If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
-the length of an object's string representation.
-.AP "const char" *string in
-Null-terminated string value to append to \fIobjPtr\fR.
-.AP va_list argList in
-An argument list which must have been initialised using
-\fBva_start\fR, and cleared using \fBva_end\fR.
-.AP int newLength in
-New length for the string value of \fIobjPtr\fR, not including the
-final null character.
-.AP int objc in
-The number of elements to concatenate.
-.AP Tcl_Obj *objv[] in
-The array of objects to concatenate.
-.BE
-
-.SH DESCRIPTION
-.PP
-The procedures described in this manual entry allow Tcl objects to
-be manipulated as string values.  They use the internal representation
-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.
-Also, indexing and length computations are optimized because the
-Unicode string representation is calculated and cached as needed.
-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
-\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
-\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.
-.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.  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
-\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's
-value as a Unicode string.  This is given by the returned pointer and
-(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
-\fIlengthPtr\fR if it is non-NULL.  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_GetUnicode\fR is used in the common case
-where the caller does not need the length of the unicode string
-representation.
-.PP
-\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 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 or Unicode value (whichever exists and is best
-suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
-\fIobjPtr\fR.
-.PP
-\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
-except that it can be passed more than one value to append and
-each value must be a null-terminated string (i.e. none of the
-values may contain internal null characters).  Any number of
-\fIstring\fR arguments may be provided, but the last argument
-must be a NULL pointer to indicate the end of the list.
-.PP
-\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
-except that instead of taking a variable number of arguments it takes an
-argument list.
-.PP
-The \fBTcl_SetObjLength\fR procedure changes the length of the
-string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR
-argument is greater than the space allocated for the object's
-string, then the string space is reallocated and the old value
-is copied to the new space; the bytes between the old length of
-the string and the new length may have arbitrary values.
-If the \fInewLength\fR argument is less than the current length
-of the object's string, with \fIobjPtr->length\fR is reduced without
-reallocating the string space; the original allocated size for the
-string is recorded in the object, so that the string length can be
-enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
-reallocating storage.  In all cases \fBTcl_SetObjLength\fR leaves
-a null character at \fIobjPtr->bytes[newLength]\fR.
-.PP
-\fBTcl_AttemptSetObjLength\fR is identical in function to
-\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
-request cannot be allocated, it does not cause the Tcl interpreter to
-\fBpanic\fR.  Thus, if \fInewLength\fR is greater than the space
-allocated for the object's string, and there is not enough memory
-available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
-no action and return 0 to indicate failure.  If there is enough memory
-to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
-\fBTcl_SetObjLength\fR and returns 1 to indicate success.
-.PP
-The \fBTcl_ConcatObj\fR function returns a new string object whose
-value is the space-separated concatenation of the string
-representations of all of the objects in the \fIobjv\fR
-array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
-as it copies the string representations of the \fIobjv\fR array to the
-result. If an element of the \fIobjv\fR array consists of nothing but
-white space, then that object is ignored entirely. This white-space
-removal was added to make the output of the \fBconcat\fR command
-cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
-newly-created object whose ref count is zero.
-
-.SH "SEE ALSO"
-Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
-
-.SH KEYWORDS
-append, internal representation, object, object type, string object,
-string type, string representation, concat, concatenate, unicode
+'\"

+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.

+'\"

+'\" 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.21 2007/10/28 14:17:39 dkf Exp $

+'\" 

+.so man.macros

+.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"

+.BS

+.SH NAME

+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings

+.SH SYNOPSIS

+.nf

+\fB#include <tcl.h>\fR

+.sp

+Tcl_Obj *

+\fBTcl_NewStringObj\fR(\fIbytes, length\fR)

+.sp

+Tcl_Obj *

+\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)

+.sp

+void

+\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)

+.sp

+void

+\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)

+.sp

+char *

+\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)

+.sp

+char *

+\fBTcl_GetString\fR(\fIobjPtr\fR)

+.sp

+Tcl_UniChar *

+\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)

+.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)

+.sp

+void

+\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)

+.sp

+void

+\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)

+.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

+int

+\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)

+.sp

+Tcl_Obj *

+\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)

+.SH ARGUMENTS

+.AS "const Tcl_UniChar" *appendObjPtr in/out

+.AP "const char" *bytes in

+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 characters

+unless \fInumChars\fR is negative.  (Applications needing null bytes

+should represent them as the two-byte sequence \fI\e700\e600\fR, use

+\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if

+the string is a collection of uninterpreted bytes.)

+.AP int length in

+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 "const 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.

+.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.

+.AP Tcl_Obj *objPtr in/out

+Points to an object to manipulate.

+.AP Tcl_Obj *appendObjPtr in

+The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.

+.AP int *lengthPtr out

+If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store

+the length of an object's string representation.

+.AP "const char" *string in

+Null-terminated string value to append to \fIobjPtr\fR.

+.AP va_list argList in

+An argument list which must have been initialised using

+\fBva_start\fR, and cleared using \fBva_end\fR.

+.AP int newLength in

+New length for the string value of \fIobjPtr\fR, not including the

+final null character.

+.AP int objc in

+The number of elements to concatenate.

+.AP Tcl_Obj *objv[] in

+The array of objects to concatenate.

+.BE

+

+.SH DESCRIPTION

+.PP

+The procedures described in this manual entry allow Tcl objects to

+be manipulated as string values.  They use the internal representation

+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 does not have to be copied for each append.

+Also, indexing and length computations are optimized because the

+Unicode string representation is calculated and cached as needed.

+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

+\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

+\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.

+.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.  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

+\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's

+value as a Unicode string.  This is given by the returned pointer and

+(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in

+\fIlengthPtr\fR if it is non-NULL.  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_GetUnicode\fR is used in the common case

+where the caller does not need the length of the unicode string

+representation.

+.PP

+\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 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 or Unicode value (whichever exists and is best

+suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to

+\fIobjPtr\fR.

+.PP

+\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR

+except that it can be passed more than one value to append and

+each value must be a null-terminated string (i.e. none of the

+values may contain internal null characters).  Any number of

+\fIstring\fR arguments may be provided, but the last argument

+must be a NULL pointer to indicate the end of the list.

+.PP

+\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR

+except that instead of taking a variable number of arguments it takes an

+argument list.

+.PP

+The \fBTcl_SetObjLength\fR procedure changes the length of the

+string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR

+argument is greater than the space allocated for the object's

+string, then the string space is reallocated and the old value

+is copied to the new space; the bytes between the old length of

+the string and the new length may have arbitrary values.

+If the \fInewLength\fR argument is less than the current length

+of the object's string, with \fIobjPtr->length\fR is reduced without

+reallocating the string space; the original allocated size for the

+string is recorded in the object, so that the string length can be

+enlarged in a subsequent call to \fBTcl_SetObjLength\fR without

+reallocating storage.  In all cases \fBTcl_SetObjLength\fR leaves

+a null character at \fIobjPtr->bytes[newLength]\fR.

+.PP

+\fBTcl_AttemptSetObjLength\fR is identical in function to

+\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the

+request cannot be allocated, it does not cause the Tcl interpreter to

+\fBpanic\fR.  Thus, if \fInewLength\fR is greater than the space

+allocated for the object's string, and there is not enough memory

+available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take

+no action and return 0 to indicate failure.  If there is enough memory

+to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like

+\fBTcl_SetObjLength\fR and returns 1 to indicate success.

+.PP

+The \fBTcl_ConcatObj\fR function returns a new string object whose

+value is the space-separated concatenation of the string

+representations of all of the objects in the \fIobjv\fR

+array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space

+as it copies the string representations of the \fIobjv\fR array to the

+result. If an element of the \fIobjv\fR array consists of nothing but

+white space, then that object is ignored entirely. This white-space

+removal was added to make the output of the \fBconcat\fR command

+cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a

+newly-created object whose ref count is zero.

+

+.SH "SEE ALSO"

+Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

+

+.SH KEYWORDS

+append, internal representation, object, object type, string object,

+string type, string representation, concat, concatenate, unicode