class StringBuffer extends Object
Provides writable string memory for DllCall, NumPut and other pointer-based operations. It is implicitly convertible to String. It holds UTF-16 text only; for another encoding, use a Buffer with StrGet and StrPut.
#Import Ks { StringBuffer }
Converting a StringBuffer to a String, with String(sb) or implicitly, gives its text up to the first null character or Pos, whichever is further, so null characters before Pos are kept. DllCall leaves Pos unchanged, so after a native function writes a shorter string than the buffer held, call Seek(-1) to move Pos to the new terminator.
DllCall accepts a StringBuffer as a Ptr, Str or WStr argument, each of which passes its UTF-16 memory. As an AStr argument it raises a TypeError, and as a Ptr* argument it does not receive the pointer the function writes; see double pointers.
Buffer := StringBuffer(InitialValue := "", Capacity)
Type: String
The initial string. Pos starts at its end.
Type: Integer
The writable capacity, in characters, excluding the null terminator. If omitted, it is the larger of 256 and the length of InitialValue. A capacity shorter than InitialValue is grown to fit it. A negative capacity raises a ValueError.
| Property | Type | Description |
|---|---|---|
Ptr | Integer | The address of the buffer's memory, which is pinned on first use. The address stays the same while the text fits; assigning Capacity reallocates the memory. Read-only. |
Pos | Integer | The write position, in characters, clamped to Capacity. Assigning it is the same as calling Seek, so a negative value moves it to the first null character. |
Capacity | Integer | The writable capacity, in characters, excluding the null terminator. Assigning to it reallocates the buffer, keeping the text which fits. A negative value raises a ValueError. |
Size | Integer | The capacity in bytes, excluding the null terminator: Capacity multiplied by 2. Read-only. |
| Method | Description |
|---|---|
Append(Text) | Writes Text at Pos, followed by a null character, grows Capacity as needed, and returns the new position. |
AppendLine(Text := "") | Appends Text and a linefeed (`n), and returns the new position. |
Clear() | Empties the buffer and moves the position to 0. |
Clone() | Returns a StringBuffer with memory of its own holding the same text, Capacity and Pos. |
Seek(Position) | Moves the position to Position, clamped to Capacity, and returns the new position. A negative Position moves it to the first null character, which is where a native function's output ends. |
Receives formatted text directly into a StringBuffer.
#Import Ks { StringBuffer }
sb := StringBuffer()
DllCall("wsprintf", "Ptr", sb, "Str", "%010d", "Int", 432, "Cdecl")
MsgBox sb ; 0000000432