Sophie: mozart-1.4.0-1mdv2010.0 i586

mozart-1.4.0-1mdv2010.0.i586.rpm

<HTML><HEAD><TITLE>Tcl Library Procedures - Tcl_DString manual page</TITLE></HEAD><BODY>
<H3><A NAME="M2">NAME</A></H3>
Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult - manipulate dynamic strings
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
<B>Tcl_DStringInit</B>(<I>dsPtr</I>)<BR>
char *<BR>
<B>Tcl_DStringAppend</B>(<I>dsPtr, string, length</I>)<BR>
char *<BR>
<B>Tcl_DStringAppendElement</B>(<I>dsPtr, string</I>)<BR>
<B>Tcl_DStringStartSublist</B>(<I>dsPtr</I>)<BR>
<B>Tcl_DStringEndSublist</B>(<I>dsPtr</I>)<BR>
int<BR>
<B>Tcl_DStringLength</B>(<I>dsPtr</I>)<BR>
char *<BR>
<B>Tcl_DStringValue</B>(<I>dsPtr</I>)<BR>
<B>Tcl_DStringSetLength</B>(<I>dsPtr, newLength</I>)<BR>
<B>Tcl_DStringFree</B>(<I>dsPtr</I>)<BR>
<B>Tcl_DStringResult</B>(<I>interp, dsPtr</I>)<BR>
<B>Tcl_DStringGetResult</B>(<I>interp, dsPtr</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL>
<P><DT>Tcl_DString <B>*dsPtr</B> (in/out)<DD>
Pointer to structure that is used to manage a dynamic string.
<P><DT>char <B>*string</B> (in)<DD>
Pointer to characters to add to dynamic string.
<P><DT>int <B>length</B> (in)<DD>
Number of characters from string to add to dynamic string.  If -1,
add all characters up to null terminating character.
<P><DT>int <B>newLength</B> (in)<DD>
New length for dynamic string, not including null terminating
character.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in/out)<DD>
Interpreter whose result is to be set from or moved to the
dynamic string.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
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.
<P>
<B>Tcl_DStringInit</B> 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, <B>Tcl_DStringFree</B> should
be called first to free up any memory allocated for the old
string.
<P>
<B>Tcl_DStringAppend</B> adds new information to a dynamic string,
allocating more memory for the string if needed.
If <I>length</I> is less than zero then everything in <I>string</I>
is appended to the dynamic string;  otherwise <I>length</I>
specifies the number of bytes to append.
<B>Tcl_DStringAppend</B> returns a pointer to the characters of
the new string.  The string can also be retrieved from the
<I>string</I> field of the Tcl_DString structure.
<P>
<B>Tcl_DStringAppendElement</B> is similar to <B>Tcl_DStringAppend</B>
except that it doesn't take a <I>length</I> argument (it appends
all of <I>string</I>) and it converts the string to a proper list element
before appending.
<B>Tcl_DStringAppendElement</B> 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 `` {'').
<B>Tcl_DStringAppendElement</B> returns a pointer to the
characters of the new string.
<P>
<B>Tcl_DStringStartSublist</B> and <B>Tcl_DStringEndSublist</B> can be
used to create nested lists.
To append a list element that is itself a sublist, first
call <B>Tcl_DStringStartSublist</B>, then call <B>Tcl_DStringAppendElement</B>
for each of the elements in the sublist, then call
<B>Tcl_DStringEndSublist</B> to end the sublist.
<B>Tcl_DStringStartSublist</B> appends a space character if needed,
followed by an open brace;  <B>Tcl_DStringEndSublist</B> appends
a close brace.
Lists can be nested to any depth.
<P>
<B>Tcl_DStringLength</B> is a macro that returns the current length
of a dynamic string (not including the terminating null character).
<B>Tcl_DStringValue</B> is a  macro that returns a pointer to the
current contents of a dynamic string.
<P>
<P>
<B>Tcl_DStringSetLength</B> changes the length of a dynamic string.
If <I>newLength</I> is less than the string's current length, then
the string is truncated.
If <I>newLength</I> 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, <B>Tcl_DStringSetLength</B> 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.
<B>Tcl_DStringSetLength</B> does not free up the string's storage space
even if the string is truncated to zero length, so <B>Tcl_DStringFree</B>
will still need to be called.
<P>
<B>Tcl_DStringFree</B> 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.
<P>
<B>Tcl_DStringResult</B> sets the result of <I>interp</I> to the value of
the dynamic string given by <I>dsPtr</I>.  It does this by moving
a pointer from <I>dsPtr</I> to <I>interp-&gt;result</I>.
This saves the cost of allocating new memory and copying the string.
<B>Tcl_DStringResult</B> also reinitializes the dynamic string to
an empty string.
<P>
<B>Tcl_DStringGetResult</B> does the opposite of <B>Tcl_DStringResult</B>.
It sets the value of <I>dsPtr</I> to the result of <I>interp</I> and
it clears <I>interp</I>'s result.
If possible it does this by moving a pointer rather than by copying
the string.

<H3><A NAME="M6">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/D.htm#dynamic string">dynamic string</A>, <A href="../Keywords/F.htm#free">free</A>, <A href="../Keywords/R.htm#result">result</A>
<HR><PRE>
<A HREF="../copyright.htm">Copyright</A> &#169; 1993 The Regents of the University of California.
<A HREF="../copyright.htm">Copyright</A> &#169; 1994-1996 Sun Microsystems, Inc.
<A HREF="../copyright.htm">Copyright</A> &#169; 1995-1997 Roger E. Critchlow Jr.</PRE>
</BODY></HTML>