Tcl_DString(3tcl)

💖 Tcl_DString — manipulate dynamic strings 💖

ok so bestie, welcome to Tcl_DString(3tcl), a page from the Tcl Library Procedures collection, and honestly? it's a bop. it's all about building up big ol' strings without stressing about memory every five seconds. let's get into it 🦋

✨ NAME ✨

Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult — manipulate dynamic strings ✨

🎀 SYNOPSIS 🎀

#include <tcl.h>

Tcl_DStringInit(dsPtr)

char *
Tcl_DStringAppend(dsPtr, bytes, length)

char *
Tcl_DStringAppendElement(dsPtr, element)

Tcl_DStringStartSublist(dsPtr)

Tcl_DStringEndSublist(dsPtr)

int
Tcl_DStringLength(dsPtr)

char *
Tcl_DStringValue(dsPtr)

Tcl_DStringSetLength(dsPtr, newLength)

Tcl_DStringTrunc(dsPtr, newLength)

Tcl_DStringFree(dsPtr)

Tcl_DStringResult(interp, dsPtr)

Tcl_DStringGetResult(interp, dsPtr)

🫶 ARGUMENTS 🫶

• Tcl_DString *dsPtr (in/out) — pointer to the struct that's running the whole dynamic-string situation 💅
• const char *bytes (in) — pointer to the characters you're gonna append onto the dynamic string
• const char *element (in) — pointer to the characters you're gonna append as a list element onto the dynamic string
• int length (in) — how many bytes from bytes to add. if it's -1, you add everything up to the null terminating character 🌸
• int newLength (in) — the new length for the dynamic string, and nope, that does not count the null terminating character
• Tcl_Interp *interp (in/out) — the interpreter whose result is getting set from, or moved to, the dynamic string ✨

🌈 DESCRIPTION 🌈

okay so here's the whole vibe: dynamic strings are a way to build up strings of literally any length by gradually appending stuff onto them. and the way that short dynamic strings cost you zero memory allocation overhead? iconic. as the string grows, more space gets allocated as needed. no cap. 👑

Tcl_DStringInit initializes a dynamic string to zero length. the Tcl_DString structure has to have been allocated by you, the caller. it makes no assumptions about the current state of the structure — anything already sitting in there gets discarded, gone, bye. and if the structure has been used before, you should call Tcl_DStringFree first to free up any memory that got allocated for the old string. periodt.

Tcl_DStringAppend adds new info 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; otherwise length tells you how many bytes to append. Tcl_DStringAppend returns a pointer to the characters of the new string. you can also grab the string from the string field of the Tcl_DString structure. 💜

Tcl_DStringAppendElement is like Tcl_DStringAppend's cousin except it doesn't take a length argument (it appends all of element) and it converts the string into a proper list element before appending. Tcl_DStringAppendElement adds a separator space before the new list element unless the new list element is the first in a list or sub-list — that means either the current string is empty, or it contains the single character {, or the last two characters of the current string are {. Tcl_DStringAppendElement returns a pointer to the characters of the new string. 🎀

Tcl_DStringStartSublist and Tcl_DStringEndSublist are your girls for creating nested lists. wanna 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. lists can be nested to any depth — go feral, bestie. 🌸

Tcl_DStringLength is a macro that returns the current length of a dynamic string (not counting the terminating null character). Tcl_DStringValue is a macro that 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, the string gets truncated. if newLength is greater than the string's current length, the string becomes longer and new space gets allocated for it if needed. but — and this is the important part, don't skip it — Tcl_DStringSetLength will not initialize that new space except to provide a terminating null character. filling in the new space is entirely on you, the caller. also, Tcl_DStringSetLength does not free up the string's storage space even if the string gets truncated down to zero length, so you'll still need to call Tcl_DStringFree. 💀

Tcl_DStringTrunc changes the length of a dynamic string. this procedure is now deprecated 🙈 — Tcl_DStringSetLength should be used instead.

Tcl_DStringFree should be called when you're done using the string. it frees up any memory that was allocated for the string and reinitializes the string's value to an empty string. clean girl behavior ✨

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. slay. Tcl_DStringResult also reinitializes the dynamic string to an empty string. 💅

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. if possible it does this by moving a pointer rather than by copying the string. efficiency is the moment. 🔥

⭐ KEYWORDS ⭐

append, dynamic string, free, result

and that's the whole page, bestie!! this one came from the Tcl manual, version 7.4, dated 7.4 — so like, a little vintage, but the drip is eternal. go forth and build your strings 💖🦋🎀