Tcl_DString(3tcl)

💖 Tcl_DString — a whole page about dynamic strings, bestie 💖

okay so this is the manual page for the Tcl library procedures that let you build up dynamic strings. It's literally filed under Tcl_DString(3tcl) and it's giving "underrated utility that carries the whole C API on its back". Come learn with me 🫶

---

✨ NAME ✨

Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult, Tcl_DStringToObj — all of these together are how you manipulate dynamic strings. That's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_DStringInit(dsPtr)

char *
Tcl_DStringAppend(dsPtr, bytes, length)

char *
Tcl_DStringAppendElement(dsPtr, element)

Tcl_DStringStartSublist(dsPtr)

Tcl_DStringEndSublist(dsPtr)

Tcl_Size
Tcl_DStringLength(dsPtr)

char *
Tcl_DStringValue(dsPtr)

Tcl_DStringSetLength(dsPtr, newLength)

Tcl_DStringFree(dsPtr)

Tcl_DStringResult(interp, dsPtr)

Tcl_DStringGetResult(interp, dsPtr)

Tcl_Obj *
Tcl_DStringToObj(dsPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_DString *dsPtr (in/out) — pointer to the structure that manages a dynamic string. She's the main character, everything revolves around her 💅
• const char *bytes (in) — pointer to the characters you wanna append onto the dynamic string.
• const char *element (in) — pointer to the characters you're appending as a list element onto the dynamic string.
• Tcl_Size length (in) — how many bytes from bytes to add to the dynamic string. If it's negative, you add all the characters up to the null terminating character. bestie behavior tbh.
• Tcl_Size newLength (in) — the new length you want for the dynamic string, and no, the null terminating character does not count toward it.
• Tcl_Interp *interp (in/out) — the interpreter whose result is gonna be set from, or moved to, the dynamic string.

---

🦋 DESCRIPTION 🦋

N.B. fr fr go check out the Tcl_UniChar documentation page if you want the tea on the TUTF-8 encoding and all the related terms that get name-dropped in here. ✨

Dynamic strings are the mechanism for building up arbitrarily long strings by gradually appending information. The way it works is lowkey genius: if the dynamic string is short, there's no memory allocation overhead. And as the string gets larger, extra space gets allocated as needed. gradual glow-up. 🌱➡️🌳

Tcl_DStringInit initializes a dynamic string to zero length. The Tcl_DString structure has to have been allocated by you, the caller. And no assumptions are made about the current state of the structure — anything already in it? gone, discarded, deleted, not your problem anymore. If the structure has been used previously, you should call Tcl_DStringFree first to free up any memory that got allocated for the old string. clean slate energy. 🧼

Tcl_DStringAppend adds new information to a dynamic string, allocating more memory for the string if it needs it. If length is less than zero, then everything in bytes gets appended to the dynamic string; otherwise length tells you exactly how many bytes to append. Tcl_DStringAppend returns a pointer to the characters of the new string. And plot twist — you can also grab the string from the string field of the Tcl_DString structure. two ways in, iconic. 😌

Tcl_DStringAppendElement is similar to Tcl_DStringAppend except for two things: it does not take a length argument (it appends all of element, every last crumb), and it converts the string to a proper list element before appending. Tcl_DStringAppendElement adds a separator space before the new list element unless that new list element is the first in a list or sub-list — meaning either the current string is empty, or it contains the single character {, or the last two characters of the current string are {. (yes, a space and then a brace, exactly like that, don't @ me.) Tcl_DStringAppendElement returns a pointer to the characters of the new string.

Tcl_DStringStartSublist and Tcl_DStringEndSublist are the besties you call to create nested lists. To append a list element that is itself a sublist: first call Tcl_DStringStartSublist, then call Tcl_DStringAppendElement for each of the elements in the sublist, then call Tcl_DStringEndSublist to close it out. Tcl_DStringStartSublist appends a space character if needed, followed by an open brace; Tcl_DStringEndSublist appends a close brace. And lists can be nested to any depth — go absolutely feral, there's no limit. 🪆🪆🪆

Tcl_DStringLength is a macro that returns the current length of a dynamic string — and no, the terminating null character is not included. Tcl_DStringValue is also a macro, and it returns a pointer to the current contents of a dynamic string.

Tcl_DStringSetLength changes the length of a dynamic string. If newLength is less than the string's current length, then the string gets truncated. If newLength is greater than the string's current length, then the string will become longer and new space will be allocated for the string if needed. But here's the catch, and it's a big one:

Tcl_DStringSetLength 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. ✋ don't forget, that's on you.

Also Tcl_DStringSetLength does not free up the string's storage space even if the string gets truncated to zero length, so Tcl_DStringFree will still need to be called. she keeps her room even when she moves out 💀

Tcl_DStringFree should be called when you're finished using the string. It frees up any memory that was allocated for the string and reinitializes the string's value to an empty string.

Tcl_DStringResult sets the result of interp to the value of the dynamic string given by dsPtr. It does this by moving a pointer from dsPtr to the interpreter's result — which saves the cost of allocating new memory and copying the string. efficiency queen. 👑 Tcl_DStringResult also reinitializes the dynamic string to an empty string. And since the dynamic string gets reinitialized, there's no need to further call Tcl_DStringFree on it, and it can be reused without calling Tcl_DStringInit. The caller must ensure that the dynamic string stored in dsPtr is encoded in TUTF-8.

Tcl_DStringGetResult does the opposite of Tcl_DStringResult. It sets the value of dsPtr to the result of interp and it clears interp's result. And if possible, it does this by moving a pointer rather than by copying the string. no wasteful copying in this house ✨

Tcl_DStringToObj returns a Tcl_Obj containing the value of the dynamic string given by dsPtr. It does this by moving a pointer from dsPtr to a newly allocated Tcl_Obj and reinitializing the dynamic string to an empty string. This saves the cost of allocating new memory and copying the string. Since the dynamic string is reinitialized, there's no need to further call Tcl_DStringFree on it and it can be reused without calling Tcl_DStringInit. The returned Tcl_Obj has a reference count of 0. The caller must ensure that the dynamic string stored in dsPtr is encoded in TUTF-8. 🐣 brand new object, freshly hatched, zero refs.

---

🔥 KEYWORDS 🔥

append, dynamic string, free, result

---

and that's the page, bestie!! 💖 this one shipped out with Tcl 7.4, dated 7.4, filed under Tcl_DString(3tcl) — go forth and build your strings responsibly, and remember: always Tcl_DStringFree. 🫶✨