1Tcl_DString(3)              Tcl Library Procedures              Tcl_DString(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_DStringInit,      Tcl_DStringAppend,      Tcl_DStringAppendElement,
9       Tcl_DStringStartSublist,   Tcl_DStringEndSublist,    Tcl_DStringLength,
10       Tcl_DStringValue,        Tcl_DStringSetLength,        Tcl_DStringTrunc,
11       Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult  -  manipulate
12       dynamic strings
13

SYNOPSIS

15       #include <tcl.h>
16
17       Tcl_DStringInit(dsPtr)
18
19       char *
20       Tcl_DStringAppend(dsPtr, bytes, length)
21
22       char *
23       Tcl_DStringAppendElement(dsPtr, element)
24
25       Tcl_DStringStartSublist(dsPtr)
26
27       Tcl_DStringEndSublist(dsPtr)
28
29       int
30       Tcl_DStringLength(dsPtr)
31
32       char *
33       Tcl_DStringValue(dsPtr)
34
35       Tcl_DStringSetLength(dsPtr, newLength)
36
37       Tcl_DStringTrunc(dsPtr, newLength)
38
39       Tcl_DStringFree(dsPtr)
40
41       Tcl_DStringResult(interp, dsPtr)
42
43       Tcl_DStringGetResult(interp, dsPtr)
44

ARGUMENTS

46       Tcl_DString *dsPtr (in/out)         Pointer  to  structure that is used
47                                           to manage a dynamic string.
48
49       const char *bytes (in)              Pointer to characters to append  to
50                                           dynamic string.
51
52       const char *element (in)            Pointer  to characters to append as
53                                           list element to dynamic string.
54
55       int length (in)                     Number of bytes from bytes  to  add
56                                           to  dynamic string.  If -1, add all
57                                           characters up to  null  terminating
58                                           character.
59
60       int newLength (in)                  New  length for dynamic string, not
61                                           including null terminating  charac‐
62                                           ter.
63
64       Tcl_Interp *interp (in/out)         Interpreter  whose  result is to be
65                                           set from or moved  to  the  dynamic
66                                           string.
67_________________________________________________________________
68
69

DESCRIPTION

71       Dynamic  strings  provide  a mechanism for building up arbitrarily long
72       strings by gradually appending information.  If the dynamic  string  is
73       short  then there will be no memory allocation overhead;  as the string
74       gets larger, additional space will be allocated as needed.
75
76       Tcl_DStringInit initializes a  dynamic  string  to  zero  length.   The
77       Tcl_DString  structure  must  have  been  allocated  by the caller.  No
78       assumptions are made about the current state of the structure; anything
79       already in it is discarded.  If the structure has been used previously,
80       Tcl_DStringFree should be called first to free up any memory  allocated
81       for the old string.
82
83       Tcl_DStringAppend  adds new information to a dynamic string, allocating
84       more memory for the string if needed.  If length is less than zero then
85       everything  in  bytes  is  appended  to  the dynamic string;  otherwise
86       length specifies the number  of  bytes  to  append.   Tcl_DStringAppend
87       returns  a pointer to the characters of the new string.  The string can
88       also be retrieved from the string field of the Tcl_DString structure.
89
90       Tcl_DStringAppendElement is similar to Tcl_DStringAppend except that it
91       does not take a length argument (it appends all of element) and it con‐
92       verts  the  string  to  a  proper  list   element   before   appending.
93       Tcl_DStringAppendElement  adds  a  separator  space before the new list
94       element unless the new list element is the first in a list or  sub-list
95       (i.e.  either  the  current  string is empty, or it contains the single
96       character “{”, or the last two characters of the current string  are  “
97       {”).   Tcl_DStringAppendElement  returns a pointer to the characters of
98       the new string.
99
100       Tcl_DStringStartSublist and Tcl_DStringEndSublist can be used to create
101       nested lists.  To append a list element that is itself a sublist, first
102       call Tcl_DStringStartSublist, then  call  Tcl_DStringAppendElement  for
103       each of the elements in the sublist, then call Tcl_DStringEndSublist to
104       end the sublist.  Tcl_DStringStartSublist appends a space character  if
105       needed,  followed  by  an  open brace;  Tcl_DStringEndSublist appends a
106       close brace.  Lists can be nested to any depth.
107
108       Tcl_DStringLength is a macro that  returns  the  current  length  of  a
109       dynamic   string   (not  including  the  terminating  null  character).
110       Tcl_DStringValue is a  macro that returns a pointer to the current con‐
111       tents of a dynamic string.
112
113       Tcl_DStringSetLength  changes  the  length  of  a  dynamic  string.  If
114       newLength is less than the string's current length, then the string  is
115       truncated.   If  newLength is greater than the string's current length,
116       then the string will become longer and new space will be allocated  for
117       the  string if needed.  However, Tcl_DStringSetLength will not initial‐
118       ize the new space except to provide a terminating null  character;   it
119       is  up  to  the  caller to fill in the new space.  Tcl_DStringSetLength
120       does not free up the string's storage space even if the string is trun‐
121       cated to zero length, so Tcl_DStringFree will still need to be called.
122
123       Tcl_DStringTrunc  changes  the length of a dynamic string.  This proce‐
124       dure is now deprecated.  Tcl_DStringSetLength  should be used instead.
125
126       Tcl_DStringFree should be  called  when  you  are  finished  using  the
127       string.   It  frees up any memory that was allocated for the string and
128       reinitializes the string's value to an empty string.
129
130       Tcl_DStringResult sets the result of interp to the value of the dynamic
131       string  given by dsPtr.  It does this by moving a pointer from dsPtr to
132       the interpreter's result.  This saves the cost of allocating new memory
133       and  copying  the  string.   Tcl_DStringResult  also  reinitializes the
134       dynamic string to an empty string.
135
136       Tcl_DStringGetResult does the opposite of Tcl_DStringResult.   It  sets
137       the  value  of  dsPtr  to  the  result of interp and it clears interp's
138       result.  If possible it does this by moving a pointer  rather  than  by
139       copying the string.
140
141

KEYWORDS

143       append, dynamic string, free, result
144
145
146
147Tcl                                   7.4                       Tcl_DString(3)
Impressum