The DString (formally, a ''Tcl_DString'') is a data type defined in the Tcl C library. It is similar to a C string, but it can dynamically (hence the D) grow to be as large as it needs to be. Using DStrings thus avoids a lot of risks for buffer overflow that plague many "ordinary" C programs.
----
[[Guess by a newcomer: DStrings used to be the main workhorses in Tcl before the introduction of [Tcl_Obj]s, and thus have a bunch of features for constructing DStrings with list structure. These features are not so interesting now, but DStrings remain useful for constructing complex strings of other sorts (e.g., error messages).]]

[DKF]: They're good for things like temporary buffers, and are used in quite a lot of places in the Tcl core still. The list-related stuff is rare though; that's usually done with [Tcl_Obj]-based list routines nowadays.
----
**Initialization**

There are two ways:

 /* either this: */
 Tcl_DString *dsPtr;
 dsPtr = malloc(sizeof(Tcl_DString));
 Tcl_DStringInit(dsPtr);

 /* or this: */
 Tcl_DString dsStrng;
 Tcl_DStringInit(&dsStrng);

Which is the preferred way and why. The Tcl sources use both forms.

----
<<discussion>> Is a DString in TCL UTF 8 format ?

[HaO] 2014-01-29: The DString data may be of any type and need not be in the TCL UTF8 format.
It is a bit like dynamical malloc.
The length is always in bytes and not in UTF characters.

Nevertheless, the following  functions will require or return TCL UTF8 format:

   * [Tcl_DStringResult]
   * [Tcl_DStringGetResult]
   * [Tcl_ExternalToUtfDString]

And the following will explicitly not return TCL UTF8 format:

   * [Tcl_UtfToExternalDString]

<<enddiscussion>>

<<categories>> Internals | Tcl Library