Tcl_DString(3) Tcl Library Procedures Tcl_DString(3)_________________________________________________________________NAME
Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendEle-
ment, Tcl_DStringStartSublist, Tcl_DStringEndSublist,
Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength,
Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult -
manipulate dynamic strings
SYNOPSIS
#include <tcl.h>
Tcl_DStringInit(dsPtr)
char *
Tcl_DStringAppend(dsPtr, string, length)
char *
Tcl_DStringAppendElement(dsPtr, string)
Tcl_DStringStartSublist(dsPtr)Tcl_DStringEndSublist(dsPtr)
int
Tcl_DStringLength(dsPtr)
char *
Tcl_DStringValue(dsPtr)
Tcl_DStringSetLength(dsPtr, newLength)
Tcl_DStringFree(dsPtr)
Tcl_DStringResult(interp, dsPtr)
Tcl_DStringGetResult(interp, dsPtr)
ARGUMENTS
Tcl_DString *dsPtr (in/out) Pointer to structure
that is used to manage
a dynamic string.
char *string (in) Pointer to characters
to add to dynamic
string.
int length (in) Number of characters
from string to add to
dynamic string. If
-1, add all characters
up to null terminating
character.
Tcl 7.4 1
Tcl_DString(3) Tcl Library Procedures Tcl_DString(3)
int newLength (in) New length for dynamic
string, not including
null terminating char-
acter.
Tcl_Interp *interp (in/out) Interpreter whose
result is to be set
from or moved to the
dynamic string.
_________________________________________________________________DESCRIPTION
Dynamic strings provide a mechanism for building up arbi-
trarily long strings by gradually appending information.
If the dynamic string is short then there will be no mem-
ory allocation overhead; as the string gets larger, addi-
tional space will be allocated as needed.
Tcl_DStringInit initializes a dynamic string to zero
length. The Tcl_DString structure must have been allo-
cated 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,
Tcl_DStringFree should be called first to free up any mem-
ory allocated for the old string.
Tcl_DStringAppend adds new information to a dynamic
string, allocating more memory for the string if needed.
If length is less than zero then everything in string is
appended to the dynamic string; otherwise length speci-
fies the number of bytes to append. Tcl_DStringAppend
returns a pointer to the characters of the new string.
The string can also be retrieved from the string field of
the Tcl_DString structure.
Tcl_DStringAppendElement is similar to Tcl_DStringAppend
except that it doesn't take a length argument (it appends
all of string) and it converts the string to a proper list
element before appending. Tcl_DStringAppendElement 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 `` {''). Tcl_DStringAppendElement
returns a pointer to the characters of the new string.
Tcl_DStringStartSublist and Tcl_DStringEndSublist can be
used to create nested lists. To append a list element
that is itself a sublist, first call Tcl_DStringStartSub-
list, then call Tcl_DStringAppendElement for each of the
elements in the sublist, then call Tcl_DStringEndSublist
to end the sublist. Tcl_DStringStartSublist appends a
space character if needed, followed by an open brace;
Tcl 7.4 2
Tcl_DString(3) Tcl Library Procedures Tcl_DString(3)
Tcl_DStringEndSublist appends a close brace. Lists can be
nested to any depth.
Tcl_DStringLength is a macro that returns the current
length of a dynamic string (not including the terminating
null character). Tcl_DStringValue is a macro that
returns a pointer to the current contents of a dynamic
string.
Tcl_DStringSetLength changes the length of a dynamic
string. If newLength is less than the string's current
length, then the string is truncated. If newLength 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, Tcl_DStringSetLength 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. Tcl_DStringSetLength does not free up the string's
storage space even if the string is truncated to zero
length, so Tcl_DStringFree will still need to be called.
Tcl_DStringFree should be called when you're finished
using the string. It frees up any memory that was allo-
cated for the string and reinitializes the string's value
to an empty string.
Tcl_DStringResult sets the result of interp to the value
of the dynamic string given by dsPtr. It does this by
moving a pointer from dsPtr to interp->result. This saves
the cost of allocating new memory and copying the string.
Tcl_DStringResult also reinitializes the dynamic string to
an empty string.
Tcl_DStringGetResult does the opposite of Tcl_DStringRe-
sult. It sets the value of dsPtr to the result of interp
and it clears interp's result. If possible it does this
by moving a pointer rather than by copying the string.
KEYWORDS
append, dynamic string, free, result
Tcl 7.4 3
