'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" RCS: @(#) $Id: DString.3,v 1.9 2002/02/08 02:52:54 dgp Exp $
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\" End of box enclosure.
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\" End of vertical sidebar.
'\" Begin an indented unfilled display.
'\" End of indented unfilled display.
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" End of list of standard options for a Tk widget.
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\" Print arg1 underlined, then print arg2 normally.
'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
'\" # Start an argument description
. ie !"\\$2"" .TP \\n()Cu
\&\\$1 \\fI\\$2\\fP (\\$3)
'\" # define tabbing values for .AP
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
.AS Tcl_Interp Tcl_CreateInterp in/out
'\" # BS - start boxed text
'\" # ^y = starting y location
'\" # BE - end boxed text (draw box now)
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
'\" # VS - start vertical sidebar
'\" # ^Y = starting y location
'\" # ^v = 1 (for troff; for nroff this doesn't matter)
'\" # VE - end of vertical sidebar
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
'\" # Special macro to handle page bottom: finish off current
'\" # box/sidebar if in box/sidebar mode, then invoked standard
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
'\" # SO - start of list of standard options
'\" # SE - end of list of standard options
See the \\fBoptions\\fR manual entry for details on the standard options.
'\" # OP - start of full description for a single option
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
'\" # CS - begin code excerpt
'\" # CE - end code excerpt
.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
\fBTcl_DStringInit\fR(\fIdsPtr\fR)
\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
\fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
\fBTcl_DStringLength\fR(\fIdsPtr\fR)
\fBTcl_DStringValue\fR(\fIdsPtr\fR)
\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
\fBTcl_DStringFree\fR(\fIdsPtr\fR)
\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
.AS Tcl_DString newLength
.AP Tcl_DString *dsPtr in/out
Pointer to structure that is used to manage a dynamic string.
.AP "CONST char" *string in
Pointer to characters to add to dynamic string.
Number of characters from string to add to dynamic string. If -1,
add all characters up to null terminating character.
New length for dynamic string, not including null terminating
.AP Tcl_Interp *interp in/out
Interpreter whose result is to be set from or moved to the
Dynamic strings provide a mechanism for building up arbitrarily long
strings by gradually appending information. If the dynamic string is
short then there will be no memory allocation overhead; as the string
gets larger, additional space will be allocated as needed.
\fBTcl_DStringInit\fR initializes a dynamic string to zero length.
The Tcl_DString structure must have been allocated by the caller.
No assumptions are made about the current state of the structure;
anything already in it is discarded.
If the structure has been used previously, \fBTcl_DStringFree\fR should
be called first to free up any memory allocated for the old
\fBTcl_DStringAppend\fR adds new information to a dynamic string,
allocating more memory for the string if needed.
If \fIlength\fR is less than zero then everything in \fIstring\fR
is appended to the dynamic string; otherwise \fIlength\fR
specifies the number of bytes to append.
\fBTcl_DStringAppend\fR returns a pointer to the characters of
the new string. The string can also be retrieved from the
\fIstring\fR field of the Tcl_DString structure.
\fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
except that it doesn't take a \fIlength\fR argument (it appends
all of \fIstring\fR) and it converts the string to a proper list element
\fBTcl_DStringAppendElement\fR adds a separator space before the
new list element unless the new list element is the first in a
list or sub-list (i.e. either the current string is empty, or it
contains the single character ``{'', or the last two characters of
the current string are `` {'').
\fBTcl_DStringAppendElement\fR returns a pointer to the
characters of the new string.
\fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
used to create nested lists.
To append a list element that is itself a sublist, first
call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
for each of the elements in the sublist, then call
\fBTcl_DStringEndSublist\fR to end the sublist.
\fBTcl_DStringStartSublist\fR appends a space character if needed,
followed by an open brace; \fBTcl_DStringEndSublist\fR appends
Lists can be nested to any depth.
\fBTcl_DStringLength\fR is a macro that returns the current length
of a dynamic string (not including the terminating null character).
\fBTcl_DStringValue\fR is a macro that returns a pointer to the
current contents of a dynamic string.
\fBTcl_DStringSetLength\fR changes the length of a dynamic string.
If \fInewLength\fR is less than the string's current length, then
If \fInewLength\fR is greater than the string's current length,
then the string will become longer and new space will be allocated
for the string if needed.
However, \fBTcl_DStringSetLength\fR will not initialize the new
space except to provide a terminating null character; it is up to the
caller to fill in the new space.
\fBTcl_DStringSetLength\fR does not free up the string's storage space
even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
will still need to be called.
\fBTcl_DStringTrunc\fR changes the length of a dynamic string.
This procedure is now deprecated. \fBTcl_DStringSetLength\fR should
\fBTcl_DStringFree\fR should be called when you're finished using
the string. It frees up any memory that was allocated for the string
and reinitializes the string's value to an empty string.
\fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of
the dynamic string given by \fIdsPtr\fR. It does this by moving
a pointer from \fIdsPtr\fR to the interpreter's result.
This saves the cost of allocating new memory and copying the string.
\fBTcl_DStringResult\fR also reinitializes the dynamic string to
\fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
it clears \fIinterp\fR's result.
If possible it does this by moving a pointer rather than by copying
append, dynamic string, free, result