---
name: "DString"
section: "3"
platform: "linux"
package: "tcl"
version: "8.6.16-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/DString"
---

# DString(3)

manipulate dynamic strings

```

```

## 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 structure that is used to manage a dynamic string.

- const char *\*bytes* (in)

  Pointer to characters to append to dynamic string.

- const char *\*element* (in)

  Pointer to characters to append as list element to dynamic string.

- int *length* (in)

  Number of bytes from *bytes* to add to dynamic string.  If -1, add all characters up to null terminating character.

- int *newLength* (in)

  New length for dynamic string, not including null terminating character.

- Tcl\_Interp *\*interp* (in/out)

  Interpreter whose result is to be set from or moved to the dynamic string.

  ```

  ```

## DESCRIPTION

Dynamic strings provide a mechanism for building up arbitrarily long strings by gradually appending information.  If the dynamic string is short then there will be no memory allocation overhead;  as the string gets larger, additional space will be allocated as needed.

**Tcl\_DStringInit** initializes a dynamic string to zero length. The Tcl\_DString structure must have been allocated by the caller. No assumptions are made about the current state of the structure; anything already in it is discarded. If the structure has been used previously, **Tcl\_DStringFree** should be called first to free up any memory allocated for the old string.

**Tcl\_DStringAppend** adds new information to a dynamic string, allocating more memory for the string if needed. If *length* is less than zero then everything in *bytes* is appended to the dynamic string;  otherwise *length* specifies the number of bytes to append. **Tcl\_DStringAppend** returns a pointer to the characters of the new string.  The string can also be retrieved from the *string* field of the Tcl\_DString structure.

**Tcl\_DStringAppendElement** is similar to **Tcl\_DStringAppend** except that it does not take a *length* argument (it appends all of *element*) and it converts the string to 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 (i.e. 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** can be used 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 end the sublist. **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.

**Tcl\_DStringLength** is a macro that returns the current length of a dynamic string (not including 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, then the string is 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. However, **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. **Tcl\_DStringSetLength** does not free up the string's storage space even if the string is truncated to zero length, so **Tcl\_DStringFree** will still need to be called.

**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 are 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. This saves the cost of allocating new memory and copying the string. **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.

## KEYWORDS

append, dynamic string, free, result