String building

StringBuilder holds a mutable character buffer (a dynamic array of chars) and edits it in place. Create one, call append repeatedly, and finish with toString(). It is not thread-safe; StringBuffer is the synchronised, slower variant that you rarely need.

Appending characters to a builder grows its buffer like a dynamic array, which the next animation shows.

1StringBuilder sb = new StringBuilder();
2sb.append("id=").append(42).append(';').append(true);   // chaining works because append returns the builder
3String s = sb.toString();                                  // "id=42;true"
4int len = sb.length();                                      // 10

1// StringBuilder.append(char), simplified
2void append(char c) {
3    if (count + 1 > value.length) {                            // no room for one more char
4        value = Arrays.copyOf(value, 2 * value.length + 2);     // JDK 17 growth rule
5    }
6    value[count++] = c;
7}

append accepts any type and writes at the end: amortised O(1) per character because the buffer grows geometrically. It is the right operation for building output in a loop.

Append the characters one by one and watch the capacity.

1StringBuilder sb = new StringBuilder();
2for (int i = 0; i < 5; i++) sb.append(i).append(' ');
3String line = sb.toString().trim();    // "0 1 2 3 4"
4sb.setLength(0);                         // reuse the builder: length 0, capacity unchanged

1// StringBuilder.append(char), simplified
2void append(char c) {
3    if (count + 1 > value.length) {                            // no room for one more char
4        value = Arrays.copyOf(value, 2 * value.length + 2);     // JDK 17 growth rule
5    }
6    value[count++] = c;
7}

insert(index, x) puts text in the middle: the tail must shift right by the length of the inserted text, so it costs O(n - index + inserted). Repeated insert(0, ...) builds a string in O(n²); append and reverse() at the end, or use a Deque, instead.

Choose insert in the editor animation and compare moving a long tail with inserting at the end.

1StringBuilder sb = new StringBuilder("abcdef");
2sb.insert(2, "XY");        // "abXYcdef": the tail 'cdef' moved right by 2
3sb.insert(sb.length(), "!"); // same as append: nothing moves

1sb.insert(index, str);                 // shifts the tail right by str.length(): O(n - index + str)
2sb.delete(start, end);                 // shifts the tail left; end is exclusive: O(n - start)
3sb.reverse();                          // two pointers swap from both ends: O(n)
4sb.deleteCharAt(sb.length() - 1);      // removing the last char shifts nothing: O(1)

delete(start, end) removes the range [start, end) and shifts the tail left; deleteCharAt(i) removes one character; setLength(n) truncates. Deleting near the end is cheap and deleting near the front moves almost everything: O(n - start).

Remove a range in the animation and check the moved-characters counter.

1StringBuilder sb = new StringBuilder("abcdef");
2sb.delete(1, 4);                   // "aef": removed "bcd"
3sb.deleteCharAt(sb.length() - 1);   // "ae": O(1), nothing to shift
4sb.setLength(1);                    // "a"

1sb.insert(index, str);                 // shifts the tail right by str.length(): O(n - index + str)
2sb.delete(start, end);                 // shifts the tail left; end is exclusive: O(n - start)
3sb.reverse();                          // two pointers swap from both ends: O(n)
4sb.deleteCharAt(sb.length() - 1);      // removing the last char shifts nothing: O(1)

reverse() reverses the characters in place with two swapping pointers: O(n), O(1) extra space. It treats a surrogate pair as one unit, so emoji are not broken. new StringBuilder(s).reverse().toString() is the idiomatic way to reverse a string.

Reverse is also how the digits of a base conversion get into the right order.

1String r = new StringBuilder("stressed").reverse().toString();   // "desserts"
2boolean pal = new StringBuilder("level").reverse().toString().equals("level");   // true

1sb.insert(index, str);                 // shifts the tail right by str.length(): O(n - index + str)
2sb.delete(start, end);                 // shifts the tail left; end is exclusive: O(n - start)
3sb.reverse();                          // two pointers swap from both ends: O(n)
4sb.deleteCharAt(sb.length() - 1);      // removing the last char shifts nothing: O(1)

A builder's capacity is the size of its internal buffer; the default is 16, and new StringBuilder(n) reserves n. When an append would exceed the capacity, the buffer grows to 2 × capacity + 2 (JDK 17) and the existing characters are copied. capacity() reports it and ensureCapacity reserves in advance. Presize when you know the final length.

Pick an initial capacity of 4 and append 14 characters in the animation.

1StringBuilder sb = new StringBuilder(4);
2for (int i = 0; i < 14; i++) sb.append('x');
3int cap = sb.capacity();     // 22: 4 -> 10 -> 22
4int len = sb.length();       // 14

1// StringBuilder.append(char), simplified
2void append(char c) {
3    if (count + 1 > value.length) {                            // no room for one more char
4        value = Arrays.copyOf(value, 2 * value.length + 2);     // JDK 17 growth rule
5    }
6    value[count++] = c;
7}

Because strings are immutable, s += c in a loop builds a new string each time and copies all previous characters. Appending n characters this way writes 1 + 2 + ... + n = n(n + 1)/2 characters: O(n²). With a StringBuilder it is O(n). For 10⁵ characters that is about 5 × 10⁹ copied characters versus 10⁵.

The animation counts the characters written by each approach.

1String s = "";
2for (int i = 0; i < 100_000; i++) s += 'x';     // O(n^2): minutes of copying on large n
3StringBuilder sb = new StringBuilder();
4for (int i = 0; i < 100_000; i++) sb.append('x');   // O(n)
5String t = sb.toString();

1String s = "";
2for (char c : text.toCharArray()) s += c;          // each += allocates a new string and copies the old one
3StringBuilder sb = new StringBuilder();
4for (char c : text.toCharArray()) sb.append(c);    // writes one char; occasional resize amortised away