We added the StringBuilder class to traditional Synergy in version 11 to provide some of the more useful functionality of the .NET StringBuilder class. StringBuilder is a way to manipulate string objects. Since a string object cannot be modified without creating a new string object, the StringBuilder class provides a way to modify a string without the overhead of creating multiple string objects.

The StringBuilder object has two properties, Capacity and Length. The Capacity property is the current number of bytes available for StringBuilder’s contents. Capacity can be set to an initial value when the StringBuilder object is instantiated, and it will automatically increase when the contents exceed the current capacity. The internal allocated capacity will automatically increase in increments of 8192 when the capacity exceeds 8192 and the contents exceed the current capacity to limit memory reallocation. The Length property is the number of bytes currently in use.

Four constructors allow you to specify the initial contents and capacity:

StringBuilder()
StringBuilder(capacity)
StringBuilder(string)
StringBuilder(string, capacity)

If the capacity is not specified or is less than 16, the StringBuilder object will be created with a minimum capacity of 16 bytes. Specifying the capacity as the largest length that is expected prevents memory reallocation when the size expands.

The Append method appends the specified alpha or string to the contents in the StringBuilder object. The AppendLine method appends the specified alpha or string and the default line terminator(s) to the end of the contents in the StringBuilder object. On Unix, this is a line feed. On Windows and OpenVMS, it’s a carriage return and line feed.

Append(alpha)
Append(string)
AppendLine(alpha)
AppendLine(string)

The Insert method inserts the alpha or string at the specified index into the contents of the StringBuilder object. A count value can also be specified to insert multiple copies of the text.

Insert(index, alpha)
Insert(index, string)
Insert(index, alpha, count)
Insert(index, string, count)

The Remove method removes the specified number of characters starting at the specified index from the contents of the StringBuilder object.

Remove(index, length)

The Replace method replaces all occurrences of the old text with the new text. It allows the start index and length to be specified so that the replacements may be limited.

Replace(old_string, new_string)
Replace(old_alpha, new_alpha)
Replace(old_string, new_string, index, length)
Replace(old_alpha, new_alpha, index, length)

The Clear method removes all characters and sets the length to zero to reinitialize the StringBuilder object.

Clear()

The Equals method compares one StringBuilder object with another. If the contents and length are equal, a true value is returned.

Equal(StringBuilder_object)

The ToString method creates a string object of the contents of the StringBuilder object. ToString(index, length) allows a substring of the StringBuilder object to be specified for the created string object.

ToString()
ToString(index, length)

Note that XCALL S_BLD now allows the destination argument to be a StringBuilder object.

Here’s an example:

record
    sb,          @system.text.StringBuilder
    str1,       @string
    str2,       @string

proc
    str1 = “one”
    sb = new system.text.StringBuilder(str, 17)           ;resulting in “one”, length 3
    sb.append(“ three”)                       ;resulting in “one three”, length 9
    sb.insert(3, “ two”)                          ;resulting in “one two three”, length 13
    sb.Insert(“ four”, 14, 3)                  ;resulting in “one two three four four four”, length 28
    sb.replace(“four”, “five”, 19, 9)  ;resulting in “one two three four five five”, length 28
    sb.remove(19, 5)                              ;resulting in “one two three four five”, length 23
    sb.replace(“ “, “-“)                           ;resulting in “one-two-three-four-five”, length 23
    str2 = sb.tostring(8, 5)                    ;resulting in “three”, length 5

With these methods, manipulating string objects is easier and doesn’t cause extra overhead. The StringBuilder class is already available in .NET, so with the addition of this class to traditional Synergy, your code can be common to both.