NAME
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
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewStringObj(bytes, length)
Tcl_Obj * |
Tcl_NewUnicodeObj(unicode, numChars) |
void
Tcl_SetStringObj(objPtr, bytes, length)
void |
Tcl_SetUnicodeObj(objPtr, unicode, numChars) |
char *
Tcl_GetStringFromObj(objPtr, lengthPtr)
char *
Tcl_GetString(objPtr)
Tcl_UniChar * |
Tcl_GetUnicode(objPtr) |
Tcl_UniChar |
Tcl_GetUniChar(objPtr, index) |
int |
Tcl_GetCharLength(objPtr) |
Tcl_Obj * |
Tcl_GetRange(objPtr, first, last) |
void
Tcl_AppendToObj(objPtr, bytes, length)
void |
Tcl_AppendUnicodeToObj(objPtr, unicode, numChars) |
void
Tcl_AppendObjToObj(objPtr, appendObjPtr)
void
void
Tcl_AppendStringsToObjVA(objPtr, argList)
void
Tcl_SetObjLength(objPtr, newLength)
Tcl_Obj *
Tcl_ConcatObj(objc, objv)
ARGUMENTS
char *bytes (in) Points to the first
byte of an array of
bytes used to set
or append to a
string object.
This byte array may
contain embedded
null bytes unless
length is negative.
int length (in) The number of bytes
to copy from bytes
when initializing,
setting, or append
ing to a string
object. If nega
tive, all bytes up
to the first null
are used.
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 char
acters unless num
Chars is negative. |
int numChars (in) ||
The number of Uni |
code characters to |
copy from unicode |
when initializing, |
setting, or append |
ing to a string |
object. If nega |
tive, all charac |
ters up to the |
first null |
int index (in) ||
The index of the |
Unicode character |
to return. |
int first (in) ||
The index of the |
first Unicode char |
acter in the Uni |
code range to be |
returned as a new |
object. |
int last (in) ||
The index of the |
last Unicode char |
acter in the Uni |
code range to be |
returned as a new |
object.
Tcl_Obj *objPtr (in/out) Points to an object
to manipulate.
Tcl_Obj *appendObjPtr (in) The object to
append to objPtr in
Tcl_AppendObjToObj.
int *lengthPtr (out) If non-NULL, the
location where
Tcl_GetStringFro
mObj will store the
the length of an
object's string
representation.
char *string (in) Null-terminated
string value to
append to objPtr.
va_list argList (in) An argument list
which must have
been initialised
using
TCL_VARARGS_START,
and cleared using
va_end.
int newLength (in) New length for the
string value of
objPtr, not includ
ing the final NULL
int objc (in) The number of ele
ments to concate
nate.
Tcl_Obj *objv[] (in) The array of
objects to concate
nate.
_________________________________________________________________
DESCRIPTION
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 effi
cient. In particular, they make a series of append opera
tions 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 opti |
mized because the Unicode string representation is calcu |
lated and cached as needed.
Tcl_NewStringObj and Tcl_SetStringObj create a new object |
or modify an existing object to hold a copy of the string |
given by bytes and length. Tcl_NewUnicodeObj and |
Tcl_SetUnicodeObj create a new object or modify an exist |
ing object to hold a copy of the Unicode string given by |
unicode and numChars. Tcl_NewStringObj and Tcl_NewUni |
codeObj 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. Tcl_SetStringObj |
and Tcl_SetUnicodeObj free any old string representation |
as well as any old internal representation of the object.
Tcl_GetStringFromObj and Tcl_GetString return an object's
string representation. This is given by the returned byte
pointer and (for Tcl_GetStringFromObj) length, which is
stored in lengthPtr 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 man
ager and should not be modified by the caller. The proce
dure Tcl_GetString is used in the common case where the
caller does not need the length of the string representa
tion.
Tcl_GetUnicode returns an object's value as a Unicode |
string. Tcl_GetUniChar returns the index'th character in |
the object's Unicode representation. |
Tcl_GetRange returns a newly created object comprised of |
object's Unicode representation. If the object's Unicode |
representation is invalid, the Unicode representation is |
regenerated from the object's string representation. |
Tcl_GetCharLength returns the number of characters (as |
opposed to bytes) in the string object. |
Tcl_AppendToObj appends the data given by bytes and length |
to the string representation of the object specified by |
objPtr. If the object has an invalid string representa |
tion, then an attempt is made to convert bytes is to the |
Unicode format. If the conversion is successful, then the |
converted form of bytes is appended to the object's Uni |
code representation. Otherwise, the object's Unicode rep |
resentation is invalidated and converted to the UTF for |
mat, and bytes is appended to the object's new string rep |
resentation. |
Tcl_AppendUnicodeToObj appends the Unicode string given by |
unicode and numChars to the object specified by objPtr. |
If the object has an invalid Unicode representation, then |
unicode is converted to the UTF format and appended to the |
object's string representation. Appends are optimized to |
handle repeated appends relatively efficiently (it overal |
locates the string or Unicode space to avoid repeated |
reallocations and copies of object's string value). |
Tcl_AppendObjToObj is similar to Tcl_AppendToObj, but it |
appends the string or Unicode value (whichever exists and |
is best suited to be appended to objPtr) of appendObjPtr |
to objPtr.
Tcl_AppendStringsToObj is similar to Tcl_AppendToObj
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 string arguments may be provided, but the last
argument must be a NULL pointer to indicate the end of the
list.
Tcl_AppendStringsToObjVA is the same as Tcl_Append
StringsToObj except that instead of taking a variable num
ber of arguments it takes an argument list.
The Tcl_SetObjLength procedure changes the length of the
string value of its objPtr argument. If the newLength
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 newLength argument is
less than the current length of the object's string, with
objPtr->length is reduced without reallocating the string
recorded in the object, so that the string length can be
enlarged in a subsequent call to Tcl_SetObjLength without
reallocating storage. In all cases Tcl_SetObjLength
leaves a null character at objPtr->bytes[newLength].
The Tcl_ConcatObj function returns a new string object
whose value is the space-separated concatenation of the
string representations of all of the objects in the objv
array. Tcl_ConcatObj eliminates leading and trailing white
space as it copies the string representations of the objv
array to the result. If an element of the objv array con
sists of nothing but white space, then that object is
ignored entirely. This white-space removal was added to
make the output of the concat command cleaner-looking.
Tcl_ConcatObj returns a pointer to a newly-created object
whose ref count is zero.
SEE ALSO
Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
KEYWORDS
append, internal representation, object, object type,
string object, string type, string representation, concat,
concatenate, unicode
Man(1) output converted with
man2html