Manual Pages for UNIX Operating System command usage for man Tcl_DStringTrunc

Tcl Library Procedures                          Tcl_DString(3TCL)



_________________________________________________________________

NAME
     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

SYNOPSIS
     #include 

     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.

     CONST 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,



Tcl                     Last change: 7.4                        1






Tcl Library Procedures                          Tcl_DString(3TCL)



                                         add all characters up to
                                         null terminating charac-
                                         ter.

     int           newLength   (in)      New length  for  dynamic
                                         string,   not  including
                                         null terminating charac-
                                         ter.

     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  memory
     allocation  overhead;  as the string gets larger, additional
     space will be allocated as needed.

     Tcl_DStringInit 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,  Tcl_DStringFree  should
     be  called first to free up any memory 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 specifies 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  struc-
     ture.

     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 char-
     acter  ``{'',  or  the  last  two  characters of the current
     string are  ``  {'').   Tcl_DStringAppendElement  returns  a
     pointer to the characters of the new string.





Tcl                     Last change: 7.4                        2






Tcl Library Procedures                          Tcl_DString(3TCL)



     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
     sublist.   Tcl_DStringStartSublist appends a 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 allocated 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_DStringResult.
     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                     Last change: 7.4                        3






Tcl Library Procedures                          Tcl_DString(3TCL)



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.









































Tcl                     Last change: 7.4                        4