Tcl_StringObj(3) Tcl Library Procedures Tcl_StringObj(3)______________________________________________________________________________NAME
Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_Append‐
ToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj - manipu‐
late Tcl objects as strings
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewStringObj(bytes, length)
Tcl_SetStringObj(objPtr, bytes, length)
char *
Tcl_GetStringFromObj(objPtr, lengthPtr)
Tcl_AppendToObj(objPtr, bytes, length)
Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)
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 nega‐
tive.
int length (in) The number of bytes to copy from
bytes when initializing, setting,
or appending to a string object.
If negative, all bytes up to the
first null are used.
Tcl_Obj *objPtr (in/out) Points to an object to manipulate.
int *lengthPtr (out) If non-NULL, the location where
Tcl_GetStringFromObj will store the
the length of an object's string
representation.
char *string (in) Null-terminated string value to
append to objPtr.
int newLength (in) New length for the string value of
objPtr, not including the final
NULL character.
int objc (in) The number of elements 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 manipula‐
tions 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.
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_NewStringObj returns a pointer to a newly created object with ref‐
erence count zero. Both procedures set the object to hold a copy of
the specified string. Tcl_SetStringObj frees any old string represen‐
tation as well as any old internal representation of the object.
Tcl_GetStringFromObj returns an object's string representation. This
is given by the returned byte pointer and length, which is stored in
lengthPtr if it is non-NULL. If the object's string representation is
invalid (its byte pointer is NULL), the string representation is regen‐
erated from the object's internal representation. The storage refer‐
enced by the returned byte pointer is owned by the object manager and
should not be modified by the caller.
Tcl_AppendToObj appends the data given by bytes and length to the
object specified by objPtr. 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).
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.
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 real‐
located 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 val‐
ues. If the newLength argument is less than the current length of the
object's string, with objPtr->length 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 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 consists 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
Tcl 8.0 Tcl_StringObj(3)
