<\/a> <\/h2>\nDynamic 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>\n
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, Tcl_DStringFree<\/b> should be called first to free up any memory allocated for the old string.<\/p>\n
Tcl_DStringAppend<\/b> adds new information to a dynamic string, allocating more memory for the string if needed. If length<\/i> is less than zero then everything in bytes<\/i> is appended to the dynamic string; otherwise length<\/i> specifies the number of bytes to append. Tcl_DStringAppend<\/b> returns a pointer to the characters of the new string. The string can also be retrieved from the string<\/i> field of the Tcl_DString structure.<\/p>\n
Tcl_DStringAppendElement<\/b> is similar to Tcl_DStringAppend<\/b> except that it does not take a length<\/i> argument (it appends all of element<\/i>) and it converts the string to a proper list element before appending. 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 \u201c{\u201d, or the last two characters of the current string are \u201c {\u201d). Tcl_DStringAppendElement<\/b> returns a pointer to the characters of the new string.<\/p>\n
Tcl_DStringStartSublist<\/b> and Tcl_DStringEndSublist<\/b> can be used to create nested lists. To append a list element that is itself a sublist, first call Tcl_DStringStartSublist<\/b>, then call Tcl_DStringAppendElement<\/b> for each of the elements in the sublist, then call Tcl_DStringEndSublist<\/b> to end the sublist. Tcl_DStringStartSublist<\/b> appends a space character if needed, followed by an open brace; Tcl_DStringEndSublist<\/b> appends a close brace. Lists can be nested to any depth.<\/p>\n
Tcl_DStringLength<\/b> is a macro that returns the current length of a dynamic string (not including the terminating null character). Tcl_DStringValue<\/b> is a macro that returns a pointer to the current contents of a dynamic string.<\/p>\n
Tcl_DStringSetLength<\/b> changes the length of a dynamic string. If newLength<\/i> is less than the string\u2019s current length, then the string is truncated. If newLength<\/i> is greater than the string\u2019s current length, then the string will become longer and new space will be allocated for the string if needed. However, 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. Tcl_DStringSetLength<\/b> does not free up the string\u2019s storage space even if the string is truncated to zero length, so Tcl_DStringFree<\/b> will still need to be called.<\/p>\n
Tcl_DStringTrunc<\/b> changes the length of a dynamic string. This procedure is now deprecated. Tcl_DStringSetLength<\/b> should be used instead.<\/p>\n
Tcl_DStringFree<\/b> should be called when you are finished using the string. It frees up any memory that was allocated for the string and reinitializes the string\u2019s value to an empty string.<\/p>\n
Tcl_DStringResult<\/b> sets the result of interp<\/i> to the value of the dynamic string given by dsPtr<\/i>. It does this by moving a pointer from dsPtr<\/i> to the interpreter\u2019s result. This saves the cost of allocating new memory and copying the string. Tcl_DStringResult<\/b> also reinitializes the dynamic string to an empty string.<\/p>\n
Tcl_DStringGetResult<\/b> does the opposite of Tcl_DStringResult<\/b>. It sets the value of dsPtr<\/i> to the result of interp<\/i> and it clears interp<\/i>\u2019s result. If possible it does this by moving a pointer rather than by copying the string.<\/p>\n