TStringBuilder · BlitzMax

A modifiable String.

A string builder provides functionality to efficiently insert, replace, remove, append and reverse. It is an order of magnitude faster to append Strings to a TStringBuilder than it is to append Strings to Strings.

Example

'
' Append some strings, with basic timing comparison.
'
SuperStrict

Framework BRl.StringBuilder
Import brl.standardio

Const iterations:Int = 20000
Local ms:Int, nms:Int

Local sb:TStringBuilder = New TStringBuilder

Print "Appending a sequence of " + iterations + " numbers.."

Local s:String
ms = MilliSecs()
For Local i:Int = 0 Until iterations
    s :+ i + " "
Next
nms = MilliSecs()
Print "String concat : " + (nms - ms) + " ms"
Print "String length = " + s.Length

Print ""

ms = MilliSecs()
For Local i:Int = 0 Until iterations
    sb.Append(i).Append(" ")
Next
nms = MilliSecs()

Print "StringBuilder concat : " + (nms - ms) + " ms"

Print "StringBuilder String length = " + sb.Length()
Print "StringBuilder capacity = " + sb.Capacity()

Constructors

`Method New()`

Constructs a TStringBuilder with the default capacity.

`Method New(initialCapacity:Int)`

Constructs a TStringBuilder with a specified initialCapacity.

`Method New(Text:String)`

Constructs a TStringBuilder initialized to the contents of Text.

Operators

`Method Operator[]:Int(index:Int)`

Returns the char value in the buffer at the specified index.

The first char value is at index 0, the next at index 1, and so on, as in array indexing. index must be greater than or equal to 0, and less than the length of the buffer.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("Hello World!")

Print Chr(sb[3])
Print Chr(sb[6])

`Method Operator []= (index:Int, char:Int)`

The character at the specified index is set to char.

index must be greater than or equal to 0, and less than the length of the buffer.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("Hello World!")

sb[3] = Asc("p")
sb[4] = Asc(",")

Print sb.ToString()

`Method Operator =:Int (obj:Object)`

Returns True if obj is equal to this string builder.

`Method Operator =:Int (sb:TStringBuilder)`

Returns True if sb is lexicographically equal to this string builder.

`Method Operator <>:Int (obj:Object)`

Returns True if obj is not equal to this string builder.

`Method Operator <>:Int (sb:TStringBuilder)`

Returns True if sb is not lexicographically equal to this string builder.

Methods

`Method Length:Int()`

Returns the length of the string the string builder would create.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("Hello World!")

Print sb.Length() ' 12

`Method Capacity:Int()`

Returns the total number of characters that the string builder can accommodate before needing to grow.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("Hello World!")

Print sb.Capacity() ' 16

`Method SetLength(length:Int)`

Sets the length of the string builder.

If the length is less than the current length, the current text will be truncated. Otherwise, the capacity will be increased as necessary, although the actual length of text will remain the same.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("Hello World!")

sb.SetLength(5)

Print sb.ToString()

`Method Append:TStringBuilder(value:String)`

Appends a String onto the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

sb.Append("Hello")
sb.Append(" ")
sb.Append("World")

Print sb.ToString()

`Method AppendLine:TStringBuilder(value:String)`

Appends a String onto the string builder with new line at the end.

`Method AppendByte:TStringBuilder(value:Byte)`

Appends a Byte value to the string builder.

`Method Append:TStringBuilder(value:Byte)`

Appends a Byte value onto the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local bytes:Byte[] = [0, 1, 2, 3, 4, 5]

For Local b:Byte = EachIn bytes
    sb.Append(b).Append(",")
Next

Print sb.ToString()

`Method AppendObject:TStringBuilder(obj:Object)`

Appends an object onto the string builder.

This generally calls the object's ToString() method. TStringBuilder objects are simply mem-copied.

`Method Append:TStringBuilder(obj:Object)`

Appends an object onto the string builder.

This generally calls the object's ToString() method. TStringBuilder objects are simply mem-copied.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local t:TMyType = New TMyType

sb.Append(t)

Print sb.ToString()

Type TMyType

    Method ToString:String()
        Return "Hello World!"
    End Method

End Type

`Method Append:TStringBuilder(sb:TStringBuilder)`

Appends a TStringBuilder onto the string builder.

`Method AppendCString:TStringBuilder(chars:Byte Ptr)`

Appends a null-terminated C string onto the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder()

Local b:Byte Ptr = "Hello World".ToCString()

sb.AppendCString(b)

MemFree(b)

Print sb.ToString()

`Method AppendCStringBytes:TStringBuilder(chars:Byte Ptr, length:Int)`

Appends a C string of length bytes onto the string builder.

`Method AppendDouble:TStringBuilder(value:Double)`

Appends a Double value to the string builder.

`Method Append:TStringBuilder(value:Double)`

Appends a Double value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local x:Double = 35.7
Local y:Double = 40.1

sb.Append(x)
sb.Append(", ")
sb.Append(y)

Print sb.ToString()

`Method AppendFloat:TStringBuilder(value:Float)`

Appends a Float value to the string builder.

`Method Append:TStringBuilder(value:Float)`

Appends a Float value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local x:Float = 35.7
Local y:Float = 40.1

sb.Append(x)
sb.Append(", ")
sb.Append(y)

Print sb.ToString()

`Method AppendInt:TStringBuilder(value:Int)`

Appends an Int value to the string builder.

`Method Append:TStringBuilder(value:Int)`

Appends an Int value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local a:Int = 5
Local b:Int = 6

sb.Append(a).Append(" + ").Append(b)
sb.Append(" = ").Append(a + b)

Print sb.ToString()

`Method AppendLong:TStringBuilder(value:Long)`

Appends a Long value to the string builder.

`Method Append:TStringBuilder(value:Long)`

Appends a Long value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local num:Long = 100000000:Long * 9876
sb.Append(num).AppendNewLine()
sb.Append(num * 99)

Print sb.ToString()

`Method AppendNewLine:TStringBuilder()`

Appends the new line string to the string builder.

The new line string can be altered using SetNewLineText. This might be used to force the output to always use Unix line endings even when on Windows.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

sb.Append("Hello")
sb.AppendNewLine()
sb.AppendNewLine()
sb.Append("World")

Print sb.ToString()

`Method AppendNull:TStringBuilder()`

Appends the text representing null to the string builder.

`Method AppendShort:TStringBuilder(value:Short)`

Appends a Short value to the string builder.

`Method Append:TStringBuilder(value:Short)`

Appends a Short value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local x:Short = 100
Local y:Short = 55

sb.Append(x).Append(", ").Append(y)

Print sb.ToString()

`Method AppendUInt:TStringBuilder(value:UInt)`

Appends a UInt value to the string builder.

`Method Append:TStringBuilder(value:UInt)`

Appends a UInt value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local values:UInt[] = [2, 4, 6, 8, 10]

For Local value:UInt = EachIn values
    sb.Append(value).AppendNewLine()
Next

Print sb.ToString()

`Method AppendULong:TStringBuilder(value:ULong)`

Appends a Ulong value to the string builder.

`Method Append:TStringBuilder(value:ULong)`

Appends a Ulong value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local a:ULong = 900
Local b:ULong = 7400

sb.Append(a).Append(", ").Append(b)

Print sb.ToString()

`Method AppendSizet:TStringBuilder(value:Size_T)`

Appends a Size_T value to the string builder.

`Method Append:TStringBuilder(value:Size_T)`

Appends a Size_T value to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local s:Size_T = 32684

sb.Append(s).Append(" ^ 2 = ")
sb.Append(Size_T(s ^ 2))

Print sb.ToString()

`Method AppendUTF8String:TStringBuilder(chars:Byte Ptr)`

Appends a null-terminated UTF-8 string onto the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder()

Local b:Byte Ptr = "Привет, мир!".ToUTF8String()

sb.AppendUTF8String(b)

MemFree(b)

Print sb.ToString()

`Method AppendUTF8Bytes:TStringBuilder(chars:Byte Ptr, length:Int)`

Appends a UTF-8 string of length bytes onto the string builder.

`Method AppendShorts:TStringBuilder(shorts:Short Ptr, length:Int)`

Appends an array of shorts onto the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local shorts:Short[] = [65, 66, 67, 68, 69, 70]

sb.AppendShorts(shorts, shorts.length)

Print sb.ToString()

`Method AppendChar:TStringBuilder(char:Int)`

Appends a character of the given char code point to the string builder.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder

Local chars:Int[] = [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33]

For Local c:Int = EachIn chars
    sb.AppendChar(c)
Next

Print sb.ToString()

`Method AppendUTF32String:TStringBuilder(chars:UInt Ptr)`

Appends a null-terminated UTF-32 string onto the string builder.

`Method AppendUTF32Bytes:TStringBuilder(chars:UInt Ptr, length:Int)`

Appends a UTF-32 string of length characters (n bytes / 4) onto the string builder.

`Method Compare:Int(o:Object) Override`

Compares the string builder with another object.

If the other object is a string builder then, the contents of two are compared lexicographically, as determined by the unicode value of each character in order. If there is no difference, then the shorter of the two contents precedes the longer.

If the other object is not a string builder, the standard object comparison is made.

`Method Find:Int(subString:String, startIndex:Int = 0)`

Finds first occurance of a sub string.

Returns

-1 if subString not found.

Example

SuperStrict

Framework BRL.StringBuilder
Import brl.standardio

Local sb:TStringBuilder = New TStringBuilder("one two three four five six seven")

Print sb.Find("w") ' 5
Print sb.Find("z") ' -1
Print sb.Find("e", 4) ' 11

`Method FindLast:Int(subString:String, startIndex:Int = 0)`

Finds last occurance of a sub string.

Returns

-1 if subString not found.