the string api

the picture

a String is a printed page. you can read it, copy bits of it, staple two pages together, but you can't edit it. every "change" prints a fresh page. (why they're immutable is in strings, the basics.)

a StringBuilder is a whiteboard. you write on it as much as you like. when it's full, you grab a bigger whiteboard, copy everything over, and keep going. when you're done, toString() prints the page.

that difference is the whole performance story:

String csv = "";
for (String name : names) {
    csv += name + ",";   // a brand new String, every time
}

var sb = new StringBuilder();
for (String name : names) {
    sb.append(name).append(',');
}
String csv = sb.toString();

(yes, the builder got faster with more work. by the bigger run the JIT had compiled the loop. at that speed it's basically free either way.)

StringBuilder is a byte[] that grows

inside, a StringBuilder is a byte[], a count of how much of it is used, and a coder (more on that below). capacity() is the size of the array, length() is how much you've written. start empty and you get room for 16.

the rule, straight from AbstractStringBuilder in jdk 25: the new capacity is old * 2 + 2, or exactly what you asked for if that's bigger. so 16 → 34 → 70 → 142 → 286. doubling means the total copying stays proportional to the final length (each byte gets copied about once on average), which is why appending is "amortized O(1)".

if you know roughly how big the result will be, say so up front and skip the copies entirely:

var sb = new StringBuilder(4096);   // one allocation, no growing

var sb = new StringBuilder("hello");
IO.println(sb.capacity());

the handful you'll actually use:

void main() {
    var sb = new StringBuilder("hello");
    sb.insert(0, ">> ").append('!').reverse();   // every method returns the builder, so they chain
    IO.println(sb);
    sb.setLength(3);                             // truncate (or pad with \0 if longer)
    IO.println(sb);
    IO.println(new StringBuilder().repeat("ab", 3).repeat('-', 2));
}

!olleh >>
!ol
ababab--

repeat on a builder is java 21+. there's also deleteCharAt, replace(start, end, str), charAt/setCharAt and indexOf.

what a String actually stores

before java 9, a String was a char[]: two bytes per character, always. but most strings in most programs are ascii (keys, ids, json, log lines), so half of every string was zeros. JEP 254 changed the inside to a byte[] plus a one-byte coder: LATIN1 (one byte per char) when every char is ≤ 0xFF, UTF16 (two bytes per char) otherwise.

you never see the coder from the outside. charAt, length and friends behave exactly the same. it's just memory, and it's a lot of memory: strings are often the biggest thing on a heap.

the methods worth knowing

String has about 70 public methods. these are the ones that pull their weight, plus the java 11+ ones people don't know exist yet:

void main() {
    String s = "　 hi 　";             // 　 is the ideographic space
    IO.println("[" + s.strip() + "]");         // trim() would leave the 　 alone
    IO.println("  ".isBlank() + " " + "  ".isEmpty());
    IO.println("ab".repeat(3));
    IO.println("a\nb\r\nc".lines().count());
    IO.println("%s is %d".formatted("x", 42));
    IO.println(String.join("/", "usr", "local", "bin"));
    IO.println("hi😀".length() + " " + "hi😀".codePointCount(0, 4));
    IO.println("hello".chars().filter(c -> c == 'l').count());
}

[hi]
true false
ababab
3
x is 42
usr/local/bin
4 3
2

trim() is from java 1.0 and removes everything <= ' ' (space and the ascii control chars). strip() asks Character.isWhitespace, so it also knows about the dozen-odd unicode spaces. new code: strip.

IO.println("a.b.c".split(".").length);

formatting

String.format, "...".formatted(...) and printf all use the same little language from java.util.Formatter:

import java.util.Locale;
 
void main() {
    IO.println(String.format(Locale.ROOT, "%,d|%-6s|%6.2f|%05d|%x", 1234567, "ab", Math.PI, 42, 255));
}

1,234,567|ab    |  3.14|00042|ff