line endings

1 files changed, 272 insertions, 272 deletions

diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 78b801e..8b80b2a 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.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

+'\"
+'\" 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.22 2007/10/29 17:17:54 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\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