API Reference

Here's the full list of everything you can do with StringBuilder!

Initialization

`new`

StringBuilder.new(Capacity: number?, MaxCapacity: number?): StringBuilder

Returns a brand new StringBuilder object.

Capacity: (Optional) The starting size in bytes. Defaults to 64.
MaxCapacity: (Optional) Absolute max capacity in bytes. Defaults to 1*1024*1024 (1MB).

Modification

`Append`

StringBuilder:Append(Data: any?): StringBuilder

Appends data (string, number, bool) at the end!

`AppendLine`

StringBuilder:AppendLine(Data: any?): StringBuilder

Same as Append, except it adds a line terminator for you at the end ("\n").

`AppendFormat`

StringBuilder:AppendFormat(Format: string, ...): StringBuilder

Same as Append, except with formatting built-in!

`AppendJoin`

StringBuilder:AppendJoin(Data: {any?}, Separator: string?): StringBuilder

Concatenates and appends an array of string & numbers, placing your Separator right between each one (like commas).

As this uses table.concat, it will error if you pass anything other than strings and numbers!

`AppendList`

StringBuilder:AppendList(...): StringBuilder

Concatenates and appends a list of string and/or number arguments. Way faster than chaining appends together!

As this uses table.concat, it will error if you pass anything other than strings and numbers!

`Compare`

StringBuilder:Compare(self2: StringBuilder): boolean

Compares this StringBuilder with another one and returns true if their contents are fully identical!

`GetCharacters`

StringBuilder:GetCharacters(Index: number, Count: number?): string

Grabs specific character(s) starting from your given Index. Count defaults to 1, but you can pass negative or positive numbers to grab more (negative values dont return reversed strings).

`SetCharacters`

StringBuilder:SetCharacters(Index: number, Data: any): StringBuilder

Overwrites any character(s) starting at your Index directly with the new Data!

`Insert`

StringBuilder:Insert(Data: any?, Index: number): StringBuilder

Inserts your Data right at the given Index and safely pushes everything else to the right.

`Replace`

StringBuilder:Replace(Target: string, Replacement: string): StringBuilder

Replaces all occurrences of Target with Replacement.

`Remove`

StringBuilder:Remove(Index: number, Count: number): StringBuilder

Chops exactly Count amount of letters right out of the string starting from Index.

`Reverse`

StringBuilder:Reverse(): StringBuilder

Reverses the string safely using utf8.graphemes. This is the default because it fully supports emojis and multi-language strings! (Note: It's slower than ReverseBytes())

`ReverseBytes`

StringBuilder:ReverseBytes(): StringBuilder

Reverses the string using raw buffer magic. Just as accurate as Reverse() for English letters and noticeably faster, but it lacks emoji and multi-language support. Use with caution!

`Space`

StringBuilder:Space(): StringBuilder

Just appends a space (" ") at the end.

`Newline`

StringBuilder:Newline(): StringBuilder

Just appends a newline ("\n") at the end.

`Clear`

StringBuilder:Clear(): StringBuilder

Clears the buffer! (More accurately, it just resets the end cursor, so it's basically free to call)

Capacity and Size

Capacity Details

Everything under the hood is buffers, so capacity and lengths are ALWAYS in bytes!

`GetLength`

StringBuilder:GetLength(): number

Returns the current length of your string in bytes.

`SetLength`

StringBuilder:SetLength(Length: number): boolean

Manually sets the length of the string! - If it's smaller, it instantly truncates your string.
- If it's larger than your current capacity, it forces a buffer expansion. Returns true if successful, or false if your length is negative.

`GetCapacity`

StringBuilder:GetCapacity(): number

Returns your current capacity in bytes.

`EnsureCapacity`

StringBuilder:EnsureCapacity(EnsuredCapacity: number): (boolean, number)

Makes sure your buffer is at least as big as EnsuredCapacity! Returns true if it had to/could resize, alongside your new capacity.

This is capped by your StringBuilder's max capacity, so be sure to check if the returned capacity is enough!

`SetCapacity`

StringBuilder:SetCapacity(Capacity: number): number

Manually set the capacity safely! It resizes the buffer, and any out of bounds data just gets cut off. Returns the new actual capacity (capped by your max capacity!).

`GetMaxCapacity`

StringBuilder:GetMaxCapacity(): number

Returns the max capacity in bytes.

`SetMaxCapacity`

StringBuilder:SetMaxCapacity(MaxCapacity: number)

Manually sets your absolute max capacity. If you try to pass something less than your current capacity, it just silently ignores it.

`GetFreeSpace`

StringBuilder:GetFreeSpace(): number

Returns your available writable space in bytes.

`GetTotalFreeSpace`

StringBuilder:GetTotalFreeSpace(): number

Returns your max writable space in bytes.

Extraction & Memory

`ToString`

StringBuilder:ToString(): string

Returns the fully built string!
(You can also just use tostring(stringBuilder) or print(stringBuilder))

`Destroy`

StringBuilder:Destroy()

Destroys the object. Leaves the buffer to be cleaned up by the garbage collector automatically since there's no way to do it manually!

Packing & Compression

These are mostly for networking or datastores!

`Pack`

StringBuilder:Pack(): buffer

Packs the StringBuilder's data and metadata all together into a buffer!

`Compress`

StringBuilder:Compress(CompressionLevel: number?): buffer

Compresses the StringBuilder with Zstd. CompressionLevel is optional and must range from -7 to 22: higher means more compression at the cost of more time. Returns a packed and compressed buffer.

`FromBuffer`

StringBuilder.FromBuffer(data: buffer): StringBuilder?

Returns a StringBuilder object right back from a compressed (or packed) StringBuilder buffer. Returns nil if something is wrong.