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_Objs, 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.
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.
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:
And the following will explicitly not return TCL UTF8 format: