DString

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.


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.


  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:

And the following will explicitly not return TCL UTF8 format: