Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_StringObjAppend, Tcl_StringObjAppendObj - manipulate Tcl string objects
#include <tcl.h>
Tcl_Obj *
Tcl_NewStringObj(bytes, length)
Tcl_SetStringObj(objPtr, bytes, length)
char *
Tcl_GetStringFromObj(objPtr, lengthPtr)
Tcl_StringObjAppend(objPtr, bytes, length)
Tcl_StringObjAppendObj(objPtr, srcPtr)
- char *bytes (in)
-
Points to the first byte of an array of bytes
used to initialize, 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 appending to a string object.
If negative, all bytes up to the first null are used.
- Tcl_Obj *objPtr (in/out)
-
For Tcl_SetStringObj, this points to the object to be modified
to hold the specified string.
In Tcl_GetStringFromObj, this points to the object
from which to get a string given by the returned byte pointer
and length (stored in lengthPtr if non-NULL).
For Tcl_StringObjAppend and Tcl_StringObjAppendObj,
this refers to the object to which is appended
either a specified string or another object's string representation;
if objPtr does not already point to a string object,
it will be converted to one.
- int *lengthPtr (out)
-
If non-NULL, the location where Tcl_GetStringFromObj will store
the the length of an object's string representation.
- Tcl_Obj *srcPtr (in/out)
-
This refers to an object whose string representation is appended
to objPtr by Tcl_StringObjAppendObj.
Tcl string objects have an internal representation that supports
the efficient construction of
arbitrarily long string values by appending information.
These procedures described in this man page
are used by C code to create, modify, concatenate, append to,
and get strings from Tcl string objects.
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 reference count 1.
Both procedures set the object to hold a copy of the specified string.
Tcl_SetStringObj frees any old string representation
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 regenerated from the
object's internal representation.
Tcl_StringObjAppend appends a string to the object
specified by objPtr.
Tcl_StringObjAppend ensures that objPtr
refers to a string object.
If objPtr does not already refer to a string object,
Tcl_StringObjAppend will convert it to one
(this conversion always succeeds).
Tcl_StringObjAppend frees any old string representation and,
if the object is not already a string object,
frees any old internal representation.
Tcl_StringObjAppendObj resembles Tcl_StringObjAppend
except that it appends a copy of another object's string representation.
srcPtr is a pointer to the object whose string representation
is to be appended to the object referenced by objPtr.
Tcl_StringObjAppendObj frees any old string representation
of objPtr and,
if it is not already a string object,
frees any old internal representation.
Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
append, concatenate, internal representation, object, object type, string object, string type, string representation
Copyright © 1994-1997 Sun Microsystems, Inc.
Copyright © 1995, 1996 Roger E. Critchlow Jr.