Updated documentation and examples.

stringbuilder.mod/doc/intro.bbdoc

@@ -0,0 +1,20 @@
+This module provides a mutable #String like object, #TStringBuilder.
+
+Unlike with an instance of #String, a #TStringBuilder object can be modified by
+appending, removing, replacing or inserting characters. A #TStringBuilder object
+maintains an internal buffer to efficiently accommodate expansions to the string.
+New text is appended to the buffer there is space available, or a larger buffer is
+allocated and the text copied into the new buffer.
+
+The contents of a #String, on the other hand, cannot be modified, and any manipulation
+of a #String (like adding two strings together) results in the creation of new #String objects.
+
+If you intend to perform extensive string manipulation, you should certainly consider using
+a #TStringBuilder.
+
+> Although #TStringBuilder generally offers better efficiency over #String, you don't
+necessarily want to replace all uses of #String with #TStringBuilder whenever you do
+string manipulation. There are a number of factors - like the size of the string, memory
+allocations, the system you are running on, and the kind of operation - which determine
+whether using a #TStringBuilder offers a significant performance improvement. Try to
+benchmark any changes you make to ensure you are using the best features.

stringbuilder.mod/doc/tstringbuilder.bmx

@@ -0,0 +1,36 @@
+'
+' 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()

stringbuilder.mod/doc/tstringbuilder_append_b.bmx

@@ -0,0 +1,14 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_d.bmx

@@ -0,0 +1,15 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_f.bmx

@@ -0,0 +1,15 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_i.bmx

@@ -0,0 +1,14 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_l.bmx

@@ -0,0 +1,12 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_object.bmx

@@ -0,0 +1,20 @@
+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

stringbuilder.mod/doc/tstringbuilder_append_r.bmx

@@ -0,0 +1,12 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder
+
+sb.Append("Hello")
+sb.Append(" ")
+sb.Append("World")
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_append_s.bmx

@@ -0,0 +1,13 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_t.bmx

@@ -0,0 +1,13 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_u.bmx

@@ -0,0 +1,14 @@
+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()

stringbuilder.mod/doc/tstringbuilder_append_ul.bmx

@@ -0,0 +1,13 @@
+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()

stringbuilder.mod/doc/tstringbuilder_appendnewline.bmx

@@ -0,0 +1,13 @@
+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()

stringbuilder.mod/doc/tstringbuilder_appendshorts.bmx

@@ -0,0 +1,12 @@
+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()

stringbuilder.mod/doc/tstringbuilder_capacity.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.Capacity() ' 16

stringbuilder.mod/doc/tstringbuilder_charat.bmx

@@ -0,0 +1,9 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print Chr(sb.CharAt(3)) ' l
+Print Chr(sb.CharAt(6)) ' W

stringbuilder.mod/doc/tstringbuilder_contains.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.Contains("z")
+Print sb.Contains("Wo")
+

stringbuilder.mod/doc/tstringbuilder_endswith.bmx

@@ -0,0 +1,9 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.EndsWith("z")
+Print sb.EndsWith("d!")

stringbuilder.mod/doc/tstringbuilder_find.bmx

@@ -0,0 +1,10 @@
+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

stringbuilder.mod/doc/tstringbuilder_findlast.bmx

@@ -0,0 +1,11 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("one two three four five six seven")
+
+Print sb.FindLast("w") ' 5
+Print sb.FindLast("z") ' -1
+Print sb.FindLast("w", 30) ' -1 
+

stringbuilder.mod/doc/tstringbuilder_left.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.Left(4)

stringbuilder.mod/doc/tstringbuilder_length.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.Length() ' 12

stringbuilder.mod/doc/tstringbuilder_operator_iget.bmx

@@ -0,0 +1,9 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print Chr(sb[3])
+Print Chr(sb[6])

stringbuilder.mod/doc/tstringbuilder_operator_iset.bmx

@@ -0,0 +1,11 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb[3] = Asc("p")
+sb[4] = Asc(",")
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_remove.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb.Remove(2, 9)
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_replace.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb.Replace("o", "0")
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_reverse.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb.Reverse()
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_right.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.Right(4)

stringbuilder.mod/doc/tstringbuilder_setcharat.bmx

@@ -0,0 +1,11 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb.SetCharAt(3, Asc("p"))
+sb.SetCharAt(4, Asc(","))
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_setlength.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+sb.SetLength(5)
+
+Print sb.ToString()

stringbuilder.mod/doc/tstringbuilder_split.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("1,2,3,4,5,6,7,8,9,10")
+
+For Local s:String = EachIn sb.Split(",")
+	Print s
+Next

stringbuilder.mod/doc/tstringbuilder_startswith.bmx

@@ -0,0 +1,9 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.StartsWith("he")
+Print sb.StartsWith("He")

stringbuilder.mod/doc/tstringbuilder_tolower.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.ToLower().ToString()

stringbuilder.mod/doc/tstringbuilder_toupper.bmx

@@ -0,0 +1,8 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("Hello World!")
+
+Print sb.ToUpper().ToString()

stringbuilder.mod/doc/tstringbuilder_trim.bmx

@@ -0,0 +1,10 @@
+SuperStrict
+
+Framework BRL.StringBuilder
+Import brl.standardio
+
+Local sb:TStringBuilder = New TStringBuilder("  Hello World!~t~t ")
+
+sb.Trim()
+
+Print sb.ToString()

stringbuilder.mod/stringbuilder.bmx

@@ -170,17 +170,21 @@ Public
 	TStringBuilder objects are simply mem-copied.
 	End Rem
 	Method Append:TStringBuilder(obj:Object)
-		If TStringBuilder(obj) Then
-			bmx_stringbuilder_append_stringbuffer(buffer, TStringBuilder(obj).buffer)
+		If obj Then
+			bmx_stringbuilder_append_string(buffer, obj.ToString())
 		Else
-			If obj Then
-				bmx_stringbuilder_append_string(buffer, obj.ToString())
-			Else
-				Return AppendNull()
-			End If
+			Return AppendNull()
 		End If
 		Return Self
 	End Method
+
+	Rem
+	bbdoc: Appends a #TStringBuilder onto the string builder.
+	End Rem
+	Method Append:TStringBuilder(sb:TStringBuilder)
+		bmx_stringbuilder_append_stringbuffer(buffer, sb.buffer)
+		Return Self
+	End Method
 	
 	Rem
 	bbdoc: Appends a null-terminated C string onto the string builder.
@@ -421,6 +425,18 @@ Public
 		Return bmx_stringbuilder_charat(buffer, index)
 	End Method
 	
+	Rem
+	bbdoc: Returns the char value in the buffer at the specified index.
+	about: 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.
+	End Rem
+	Method Operator[]:Int(index:Int)
+?debug
+		If index < 0 Or index >= Length() Throw New TArrayBoundsException
+?
+		Return bmx_stringbuilder_charat(buffer, index)
+	End Method
+	
 	Rem
 	bbdoc: Returns true if string contains @subString.
 	End Rem
@@ -505,6 +521,17 @@ Public
 		bmx_stringbuilder_setcharat(buffer, index, char)
 	End Method
 	
+	Rem
+	bbdoc: The character at the specified index is set to @char.
+	about: @index must be greater than or equal to 0, and less than the length of the buffer.
+	End Rem
+	Method Operator []= (index:Int, char:Int)
+?debug
+		If index < 0 Or index >= Length() Throw New TArrayBoundsException
+?
+		bmx_stringbuilder_setcharat(buffer, index, char)
+	End Method
+	
 	Rem
 	bbdoc: Sets the text to be appended when a new line is added.
 	End Rem
@@ -532,7 +559,8 @@ Public
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Creates a split buffer using the specified separator.
+	about: The #TSplitBuffer can be used to iterate over the split text.
 	End Rem
 	Method Split:TSplitBuffer(separator:String)
 		Local buf:TSplitBuffer = New TSplitBuffer
@@ -559,13 +587,14 @@ End Type
 
 Rem
 bbdoc: An array of split text from a TStringBuilder.
-about: Note that the TSplitBuffer is only valid while its parent TStringBuilder is unchanged.
+about: Note that the #TSplitBuffer is only valid while its parent TStringBuilder is unchanged.
 Once you modify the TStringBuffer you should call Split() again.
 End Rem
 Type TSplitBuffer
+Private
 	Field buffer:TStringBuilder
 	Field splitPtr:Byte Ptr
-	
+Public
 	Rem
 	bbdoc: The number of split elements.
 	End Rem
@@ -621,4 +650,3 @@ Type TSplitBufferEnum
 	End Method
 
 End Type
-