NAME

       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

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
                                           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_DStringStartSublist,             then             call
       Tcl_DStringAppendElement  for  each of the elements in the
       sublist, then call Tcl_DStringEndSublist to end  the  sub-
       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_DStringResult.   It  sets  the  value  of dsPtr to the
       result of interp and it clears interp's result.  If possi-
       ble  it does this by moving a pointer rather than by copy-
       ing the string.

KEYWORDS

       append, dynamic string, free, result