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_DStringTrunc(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

       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
       space character if needed,  followed  by  an  open  brace;
       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_DStringTrunc changes the length of a  dynamic  string.
       This  procedure  is  now deprecated.  Tcl_DStringSetLength
       should be used instead.

       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 the interpreter's 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