StringBuilder

A receipt cannot be corrected, but a whiteboard can. You add a word to it, rub out a letter, write in a new one, and it is the same board all along. When text has to be built piece by piece for a long time, it is handier to write on a board and print the receipt once, when everything is ready.

Let's see what happens when a string is built in a loop with +=:

string line = "";
for (int i = 1; i <= 5; i++)
{
    line += i;
}
Console.WriteLine(line); // 12345

The result is right, but let's count the work. A string cannot be changed, so each += creates a new string and copies all the text built so far into it:

1. The first pass creates "1".
2. The second creates "12": it copies 1 and adds 2.
3. The third creates "123" and copies two characters already.
4. The fourth creates "1234" and copies three characters.
5. The fifth copies four characters for the sake of one new one.

In five passes the program created five strings of 1 to 5 characters and wrote 1 + 2 + 3 + 4 + 5 = 15 characters into them. With 10,000 pieces of one character each, += writes 1 + 2 + … + 10,000, that is, 50,005,000 characters into new strings. The work grows as the square of the number of pieces.

StringBuilder

StringBuilder is that very board: it keeps text that can change in a buffer, a piece of memory you can keep adding to. The Append method adds a piece to the end without creating a new string, and ToString() at the end creates the finished string once:

using System.Text;

var sb = new StringBuilder();
for (int i = 1; i <= 5; i++)
{
    sb.Append(i);
}
string line = sb.ToString();
Console.WriteLine(line);      // 12345
Console.WriteLine(sb.Length); // 5

Let's go through the example line by line:

1. using System.Text; brings in the namespace where StringBuilder lives. More on this below.
2. new StringBuilder() creates an empty board. var fits here: the type is visible on the right.
3. sb.Append(i) adds the text of the number i to the end. The old characters stay in place, and they need no copying.
4. sb.ToString() makes an ordinary string "12345" out of the board.
5. sb.Length is how many characters are on the board right now.

For 10,000 pieces, StringBuilder writes each character once, and ToString() copies all of them into the string once more. That makes about 20,000 characters written instead of more than 50 million.

Namespaces and the using directive

.NET types are sorted into named groups. Such a group is called a namespace: Console lives in the System namespace, and StringBuilder in System.Text. A .NET 10 program brings in System and several other namespaces by itself, but System.Text is not among them.

The line using System.Text; at the very top of the file is a using directive: it brings the namespace into the file. After it you can write StringBuilder by its short name.

The board can be edited

A board lets you do more than add text. StringBuilder can do four more things:

• Insert puts text at a given position, for example at the start;
• Replace replaces a piece right on the board, with no new string;
• sb[4] = 'C' changes one character, which a string does not allow;
• Clear() rubs out everything, and Length becomes 0.

using System.Text;

var sb = new StringBuilder("cat");
sb.Append('s');
sb.Insert(0, "two ");
sb[4] = 'C';
Console.WriteLine(sb.ToString()); // two Cats
sb.Replace("two", "three");
Console.WriteLine(sb.ToString()); // three Cats
sb.Clear();
Console.WriteLine(sb.Length);     // 0

Let's go through it line by line:

1. new StringBuilder("cat") creates a board with cat already written on it.
2. Append('s') adds s: the board holds cats.
3. Insert(0, "two ") inserts text at index 0: two cats.
4. sb[4] = 'C' changes the character at index 4, the first letter of cats: two Cats.
5. Replace("two", "three") changes two to three: three Cats.
6. Clear() rubs out everything, and Length becomes 0.

This is where the board and StringBuilder part ways. A board has one size, and when it runs out of room there is nowhere to write. In that case StringBuilder adds another piece of memory by itself, and what is already written stays in place.

When you need StringBuilder

Interviewers often ask this: why do we need StringBuilder if there is +? The answer has two parts:

• a string is immutable, so each += in a loop creates a new string and copies all the text built so far into it;
• StringBuilder adds the pieces to one buffer that can change and creates the string once, in ToString().

For two or three pieces you do not need StringBuilder. The compiler turns the expression a + b + c into one call that creates one string, and interpolation reads even better.

Common mistake

The namespace was not brought in:

var sb = new StringBuilder(); // ✗
sb.Append("Hi");
Console.WriteLine(sb.ToString());

error CS0246: The type or namespace name 'StringBuilder' could not be found (are you missing a using directive or an assembly reference?)

The program does not compile: the compiler looks for StringBuilder in the namespaces brought in and does not find it. The message itself hints at the cause in parentheses: a using directive may be missing. Add using System.Text; as the first line of the file.

Key points

• Each += on a string creates a new string and copies all the text, so the work of a += loop grows as the square of the number of pieces.
• StringBuilder holds text that can change: Append adds, Insert, Replace and sb[i] edit in place, and ToString() creates the string.
• StringBuilder lives in the System.Text namespace, and the file starts with using System.Text;.
• For a few pieces + or interpolation is enough; StringBuilder is for building in a loop.