Tcl Library Procedures
NAME
Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_StringObjAppend, Tcl_StringObjAppendObj - manipulate Tcl string objects
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewStringObj(bytes, length)
Tcl_SetStringObj(objPtr, bytes, length)
char *
Tcl_GetStringFromObj(interp, objPtr, lengthPtr)
Tcl_StringObjAppend(interp, objPtr, bytes, length)
Tcl_StringObjAppendObj(interp, objPtr, srcPtr)
ARGUMENTS
-
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).
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.
-
Tcl_Interp *interp (in/out)
-
Interpreter used to obtain any information needed for type conversion
such as the current double-to-string formatting precision.
-
int *lengthPtr (out)
-
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.
-
int objc (in)
-
The number of objects that Tcl_ConcatObj will concatenate.
-
Tcl_Obj **objv (in)
-
Points to an array of pointers to Tcl objects whose string representations
are concatenated by Tcl_ConcatObj.
DESCRIPTION
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 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.
SEE ALSO
Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
KEYWORDS
append, concatenate, internal representation, object, object type, string object, string type, string representation
Last change: 8.0
[ tcl8.0a1 | tk8.0a1 | X-ref ]
Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.