133 lines
5.4 KiB
Groff
133 lines
5.4 KiB
Groff
'\"
|
|
'\" 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.
|
|
'\"
|
|
'\" SCCS: @(#) @(#) StringObj.3 1.13 97/06/25 13:40:25
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
Tcl_Obj *
|
|
\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
|
|
.sp
|
|
\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
|
|
.sp
|
|
char *
|
|
\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
|
|
.sp
|
|
\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
|
|
.sp
|
|
\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
|
|
.sp
|
|
\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
|
|
.sp
|
|
Tcl_Obj *
|
|
\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_Interp *lengthPtr out
|
|
.AP 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 \fIlength\fR is negative.
|
|
.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 Tcl_Obj *objPtr in/out
|
|
Points to an object to manipulate.
|
|
.AP int *lengthPtr out
|
|
If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
|
|
the the length of an object's string representation.
|
|
.AP char *string in
|
|
Null-terminated string value to append to \fIobjPtr\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 doesn't have to be copied for each append.
|
|
.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_NewStringObj\fR returns a pointer to a newly created object
|
|
with reference count zero.
|
|
Both procedures set the object to hold a copy of the specified string.
|
|
\fBTcl_SetStringObj\fR frees any old string representation
|
|
as well as any old internal representation of the object.
|
|
.PP
|
|
\fBTcl_GetStringFromObj\fR returns an object's string representation.
|
|
This is given by the returned byte pointer
|
|
and length, which is stored in \fIlengthPtr\fR 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.
|
|
The storage referenced by the returned byte pointer
|
|
is owned by the object manager and should not be modified by the caller.
|
|
.PP
|
|
\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
|
|
\fIlength\fR to the object specified by \fIobjPtr\fR. 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).
|
|
.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
|
|
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
|
|
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
|