{"title":"StringBuilder","description":"","content":"Building a string out of many smaller pieces is one of the most common things a Java program does. Printing a receipt, formatting a product description, joining a list of customer addresses into one block of text. Plain `String` and the `+` operator look like they handle this just fine, until the loop count gets big enough to slow the program down. This lesson explains why that happens, how `StringBuilder` fixes it, and how to use its API correctly.\n\n---\n\n# Why `+` in a Loop Is a Problem\n\n`String` is immutable, which the [String Immutability](/learn/java/string-immutability) lesson covered in depth. Every operation that \"changes\" a `String` actually allocates a new one. That fact matters because of what `+` between strings actually does.\n\nWhen you write `a + b` where both are strings, the compiler turns that into code that allocates a new `String` containing the characters of `a` followed by the characters of `b`. The new object is independent of both inputs. The originals are untouched.\n\nFor a one-off concatenation, the allocation is cheap and unnoticeable. The trouble starts when the concatenation runs inside a loop.\n\n\n```java\npublic class ReceiptWithPlus {\n public static void main(String[] args) {\n String[] productNames = {\"Wireless Mouse\", \"Laptop Stand\", \"USB Cable\", \"HDMI Adapter\"};\n double[] productPrices = {29.99, 49.50, 9.95, 14.25};\n\n String receipt = \"\";\n for (int i = 0; i < productNames.length; i++) {\n receipt = receipt + productNames[i] + \": $\" + productPrices[i] + \"\\n\";\n }\n System.out.print(receipt);\n }\n}\n```\n\n\nThe output looks fine, and for four items the program finishes instantly. Consider what the loop does on each iteration. It reads the current `receipt`, builds a brand new string containing all of its characters plus the new line, and throws the old one away. On iteration one, that's a short string. On iteration two, it copies all the iteration-one characters plus the new line. By iteration `i`, the loop is copying the characters from all `i - 1` earlier iterations again.\n\nIf the receipt has `n` items, the total work is roughly `1 + 2 + 3 + ... + n`, which is on the order of `n` squared.\n\nConcatenating in a loop with `+` is O(n squared) on the total output length. Each `+` allocates a new `String` and copies every character built so far. For a 10,000-line receipt that means copying tens of millions of characters and producing tens of thousands of garbage `String` objects.\n\nTwo iterations of `+` aren't a problem. Ten thousand are. The fix is a mutable buffer that we write into in place, which is what `StringBuilder` provides.\n\n---\n\n# What `StringBuilder` Is\n\n`StringBuilder` lives in `java.lang`, so no import is needed. Internally it holds two things: a `char[]` buffer and an `int count` that tracks how many characters of the buffer are in use.\n\nWhen you call `append`, the new characters get written into the buffer starting at position `count`, and `count` moves forward. No new array is allocated unless the buffer runs out of room. That's the difference. `String` concatenation copies. `StringBuilder.append` writes in place.\n\n\n```mermaid\nflowchart LR\n SB[StringBuilder
count = 6
capacity = 16]:::cyan --> Buf[\"char[16]
R E C E I P T_ _ _ _ _ _ _ _ _ _\"]:::orange\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nThe diagram shows a `StringBuilder` whose buffer can hold 16 characters but only the first 6 are filled. The trailing slots exist but `count` says they aren't part of the logical content. An `append(\"S\")` would write `S` at index 6 and bump `count` to 7. No new allocation, no copying.\n\nThe same receipt loop written with a `StringBuilder`.\n\n\n```java\npublic class ReceiptWithStringBuilder {\n public static void main(String[] args) {\n String[] productNames = {\"Wireless Mouse\", \"Laptop Stand\", \"USB Cable\", \"HDMI Adapter\"};\n double[] productPrices = {29.99, 49.50, 9.95, 14.25};\n\n StringBuilder receipt = new StringBuilder();\n for (int i = 0; i < productNames.length; i++) {\n receipt.append(productNames[i]).append(\": $\").append(productPrices[i]).append(\"\\n\");\n }\n System.out.print(receipt.toString());\n }\n}\n```\n\n\nSame output, different cost. Each `append` writes characters into the existing buffer instead of allocating a new `String`. Across `n` iterations the total work is proportional to the total length of the output, which is O(n), not O(n squared).\n\nThe final line, `receipt.toString()`, copies the buffer contents into a real, immutable `String`. That's the one allocation we accept at the end so we've a normal `String` to return or print.\n\n---\n\n# Constructors and Initial Capacity\n\n`StringBuilder` has four useful constructors.\n\n\n| Constructor | What it does |\n| ------------ | ------------- |\n| `new StringBuilder()` | Empty builder with capacity 16 |\n| `new StringBuilder(int capacity)` | Empty builder with the given capacity |\n| `new StringBuilder(String str)` | Builder pre-filled with `str`, capacity is `str.length() + 16` |\n| `new StringBuilder(CharSequence seq)` | Same idea for any `CharSequence` |\n\n\nThe first three are the common choices. Each one in action.\n\n\n```java\npublic class StringBuilderConstructors {\n public static void main(String[] args) {\n StringBuilder empty = new StringBuilder();\n System.out.println(\"empty.length() = \" + empty.length());\n System.out.println(\"empty.capacity() = \" + empty.capacity());\n\n StringBuilder presized = new StringBuilder(64);\n System.out.println(\"presized.length() = \" + presized.length());\n System.out.println(\"presized.capacity() = \" + presized.capacity());\n\n StringBuilder filled = new StringBuilder(\"Order #\");\n System.out.println(\"filled.length() = \" + filled.length());\n System.out.println(\"filled.capacity() = \" + filled.capacity());\n }\n}\n```\n\n\n`length()` reports how many characters the builder currently contains. `capacity()` reports how many it could hold before needing to grow. The two are different things, and the gap between them is what makes appends cheap.\n\nThe pre-sized constructor matters when the approximate output size is known. Consider generating a receipt with 10,000 line items, each around 40 characters. That's 400,000 characters total. Starting from a builder with capacity 16 means the buffer has to grow many times to reach 400,000.\n\n\n```java\npublic class PresizedReceipt {\n public static void main(String[] args) {\n int lineCount = 10_000;\n int approxLineLength = 40;\n\n StringBuilder receipt = new StringBuilder(lineCount * approxLineLength);\n for (int i = 1; i <= lineCount; i++) {\n receipt.append(\"Item \").append(i).append(\": $19.99\\n\");\n }\n System.out.println(\"Receipt length: \" + receipt.length());\n System.out.println(\"Buffer capacity: \" + receipt.capacity());\n }\n}\n```\n\n\nThe buffer never had to grow once. Every `append` was a straight write into the existing array. Without the pre-size, the builder would have doubled its buffer over and over until it reached enough room.\n\nEach grow inside `StringBuilder` allocates a new, larger `char[]` and copies every character from the old buffer into it. Pre-sizing with the constructor avoids those copies when you can estimate the final length.\n\n---\n\n# How the Buffer Grows\n\nWhen an `append` runs out of room, `StringBuilder` allocates a new `char[]` that's at least twice the old one (specifically, `oldCapacity * 2 + 2`), copies the existing characters over, and points its internal field at the new array. The old array becomes garbage.\n\n\n```mermaid\nflowchart LR\n Before[\"Before append
count = 14
capacity = 16\"]:::cyan --> BeforeBuf[\"char[16]
'Order:Wireless'\"]:::orange\n Before --> Trigger[\"append(' Mouse')
needs 20 chars,
capacity is only 16\"]:::teal\n Trigger --> After[\"After grow
count = 20
capacity = 34\"]:::cyan\n After --> AfterBuf[\"char[34]
'Order:Wireless Mouse' + 14 empty slots\"]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe doubling rule is what keeps the amortized cost of `append` low. Even with grows, adding `n` characters across a series of appends takes time proportional to `n` overall, because each character is copied at most a small constant number of times in total. This is why `StringBuilder` is O(n) for a build of total length `n`, while the `+` loop is O(n squared).\n\nYou can see the capacity changing if you watch it across appends.\n\n\n```java\npublic class GrowthTrace {\n public static void main(String[] args) {\n StringBuilder description = new StringBuilder();\n System.out.println(\"Start: length=\" + description.length() + \", capacity=\" + description.capacity());\n\n description.append(\"Wireless Mouse with ergonomic grip\");\n System.out.println(\"After 1: length=\" + description.length() + \", capacity=\" + description.capacity());\n\n description.append(\", USB-C connection, and 12-month warranty\");\n System.out.println(\"After 2: length=\" + description.length() + \", capacity=\" + description.capacity());\n }\n}\n```\n\n\nThe exact capacity after each grow depends on the implementation, but the pattern is the same: when the buffer can't fit the new data, it grows to at least double, copies, and continues. Pre-sizing the builder skips this entirely when the final length is known up front.\n\n---\n\n# Appending Data\n\n`append` is the workhorse method. It's overloaded for every primitive type plus `String`, `char[]`, `CharSequence`, and `Object`. For non-string types it converts the value the same way `String.valueOf` would: `int` becomes its decimal text, `double` becomes its standard text form, `boolean` becomes `\"true\"` or `\"false\"`, and an arbitrary `Object` calls its `toString()`.\n\n\n```java\npublic class AppendOverloads {\n public static void main(String[] args) {\n StringBuilder order = new StringBuilder();\n order.append(\"Order #\");\n order.append(1042);\n order.append(\" for \");\n order.append(\"Alice\");\n order.append(\", total: $\");\n order.append(89.97);\n order.append(\", paid: \");\n order.append(true);\n\n System.out.println(order.toString());\n }\n}\n```\n\n\nNone of those `append` calls had to wrap the value in a `String.valueOf(...)` first. The overloads handle that for you. A `null` reference passed to `append` is appended as the literal four characters `null`, which is the same behavior `String` concatenation has.\n\nEvery mutating method on `StringBuilder` returns the builder itself (`this`), so you can chain calls into a single expression.\n\n\n```java\npublic class ChainedAppend {\n public static void main(String[] args) {\n String customerName = \"Bob\";\n int orderCount = 3;\n double cartTotal = 149.97;\n\n String summary = new StringBuilder()\n .append(\"Customer: \").append(customerName)\n .append(\", orders placed: \").append(orderCount)\n .append(\", cart total: $\").append(cartTotal)\n .toString();\n\n System.out.println(summary);\n }\n}\n```\n\n\nChaining reads naturally and produces no intermediate `String` objects. Each `.append(...)` writes into the same buffer and returns the same builder. Only the final `.toString()` allocates a `String`.\n\n---\n\n# Insert, Delete, Replace, Reverse\n\n`append` only adds to the end. For changes in the middle, `StringBuilder` has `insert`, `delete`, `deleteCharAt`, `replace`, and `reverse`. These are useful when the existing content needs adjustment.\n\n`insert(offset, value)` puts content at a given position and shifts everything after it down. Like `append`, it has overloads for every common type.\n\n\n```java\npublic class InsertExample {\n public static void main(String[] args) {\n StringBuilder productLabel = new StringBuilder(\"Wireless Mouse - $29.99\");\n productLabel.insert(0, \"SALE: \");\n System.out.println(productLabel);\n }\n}\n```\n\n\n`delete(start, end)` removes the characters from index `start` (inclusive) to `end` (exclusive). `deleteCharAt(index)` removes a single character.\n\n\n```java\npublic class DeleteExample {\n public static void main(String[] args) {\n StringBuilder address = new StringBuilder(\"221B Baker Street\");\n address.delete(4, 5);\n System.out.println(address);\n\n StringBuilder couponCode = new StringBuilder(\"SAVE10X\");\n couponCode.deleteCharAt(couponCode.length() - 1);\n System.out.println(couponCode);\n }\n}\n```\n\n\n`replace(start, end, str)` swaps a range of characters for a new string. The new string doesn't have to be the same length as the range it replaces. The buffer adjusts to fit.\n\n\n```java\npublic class ReplaceExample {\n public static void main(String[] args) {\n StringBuilder description = new StringBuilder(\"Laptop Stand - color: black\");\n description.replace(20, 25, \"silver\");\n System.out.println(description);\n }\n}\n```\n\n\n`reverse()` reverses the entire content in place. It's occasionally useful and shows up in interview problems, but in production code it's a niche tool.\n\n\n```java\npublic class ReverseExample {\n public static void main(String[] args) {\n StringBuilder confirmation = new StringBuilder(\"ORDER-1042\");\n confirmation.reverse();\n System.out.println(confirmation);\n }\n}\n```\n\n\n`insert`, `delete`, and `replace` shift characters inside the buffer. Inserting at the front of a long builder moves every existing character. `append` is the cheapest mutation because nothing has to shift.\n\n---\n\n# Random Access and Length\n\n`StringBuilder` lets you read and overwrite individual characters with `charAt(index)` and `setCharAt(index, ch)`. `length()` reports the current logical size, and `setLength(newLength)` can shrink or pad the builder.\n\n\n```java\npublic class RandomAccess {\n public static void main(String[] args) {\n StringBuilder productCode = new StringBuilder(\"MOUSE-001\");\n System.out.println(\"Length: \" + productCode.length());\n System.out.println(\"Char at 0: \" + productCode.charAt(0));\n\n productCode.setCharAt(0, 'm');\n System.out.println(\"After setCharAt: \" + productCode);\n }\n}\n```\n\n\n`setLength` controls the logical length. Setting it shorter than the current length truncates the content. Setting it longer pads with the null character `'\\u0000'`, which is rarely what you want but can be useful for fixed-width fields.\n\n\n```java\npublic class SetLengthExample {\n public static void main(String[] args) {\n StringBuilder couponCode = new StringBuilder(\"WELCOME10X\");\n couponCode.setLength(8);\n System.out.println(\"After shrink: '\" + couponCode + \"'\");\n }\n}\n```\n\n\nFor capacity-side control, `ensureCapacity(min)` grows the buffer if it's below `min`, and `trimToSize()` shrinks the buffer to match the current content. `trimToSize` is the call to make after building a large builder you plan to keep around, to release the unused tail of the buffer.\n\n\n```java\npublic class CapacityControl {\n public static void main(String[] args) {\n StringBuilder receipt = new StringBuilder();\n receipt.ensureCapacity(1000);\n System.out.println(\"After ensureCapacity: capacity=\" + receipt.capacity());\n\n receipt.append(\"Total: $89.97\");\n System.out.println(\"After small append: length=\" + receipt.length() + \", capacity=\" + receipt.capacity());\n\n receipt.trimToSize();\n System.out.println(\"After trimToSize: length=\" + receipt.length() + \", capacity=\" + receipt.capacity());\n }\n}\n```\n\n\nThe trim is optional. Most short-lived builders go straight to `toString()` and then become garbage, so trimming buys nothing. The method matters when a builder is held in a long-lived field.\n\n---\n\n# Producing a `String`\n\nThe final step in any `StringBuilder` workflow is calling `toString()`. That copies the characters out of the buffer into a fresh, immutable `String` object.\n\n\n```java\npublic class FromBuilderToString {\n public static void main(String[] args) {\n StringBuilder builder = new StringBuilder();\n builder.append(\"Customer: Carol\").append(\", items: 4\");\n String finalText = builder.toString();\n System.out.println(finalText);\n System.out.println(\"Type of finalText: \" + finalText.getClass().getSimpleName());\n }\n}\n```\n\n\nA `StringBuilder` isn't a `String`. They're different types, and `StringBuilder` doesn't override `equals` or `hashCode`.\n\n**What's wrong with this code?**\n\n\n```java\npublic class BuilderEqualsBug {\n public static void main(String[] args) {\n StringBuilder a = new StringBuilder(\"Wireless Mouse\");\n StringBuilder b = new StringBuilder(\"Wireless Mouse\");\n System.out.println(a.equals(b));\n }\n}\n```\n\n\nIt prints `false`. Two builders with identical content are still two different objects, and because `StringBuilder` inherits `equals` from `Object`, the default behavior is reference equality. The same code would print `true` for two `String` objects with matching content, because `String` overrides `equals` to compare characters.\n\n**Fix:**\n\nCompare the strings, not the builders.\n\n\n```java\npublic class BuilderEqualsFix {\n public static void main(String[] args) {\n StringBuilder a = new StringBuilder(\"Wireless Mouse\");\n StringBuilder b = new StringBuilder(\"Wireless Mouse\");\n System.out.println(a.toString().equals(b.toString()));\n }\n}\n```\n\n\n`toString()` produces real `String` objects, and `String.equals` does character-by-character comparison. The other common mistake is forgetting to call `toString()` at all and being surprised by what gets printed elsewhere. Most APIs that take a `CharSequence` (like `System.out.print` or `PrintWriter.write`) will accept a `StringBuilder` directly, but a method that expects `String` will fail to compile if you hand it the builder.\n\n\n```java\npublic class ToStringNeeded {\n public static void main(String[] args) {\n StringBuilder receipt = new StringBuilder(\"Order total: $89.97\");\n String upper = receipt.toString().toUpperCase();\n System.out.println(upper);\n }\n}\n```\n\n\n`StringBuilder` itself has no `toUpperCase()` method. Convert to `String` first, then call the `String` methods you want.\n\n---\n\n# `+` vs `StringBuilder`: When to Use Which\n\nThe compiler isn't blind. For a simple expression like `String greeting = \"Hello, \" + customerName + \"!\"`, modern Java compilers translate `+` into a `StringBuilder.append` chain internally (or use `invokedynamic` and `StringConcatFactory` to produce equivalent code). For straight-line code with a handful of pieces, `+` is fine and reads cleaner.\n\nThe compiler can't do that optimization across loop iterations. Each iteration is a separate statement, and the result of one iteration is the input to the next. That's where the quadratic behavior comes in, and where `StringBuilder` wins.\n\nA side-by-side conceptual comparison of building a 10,000-line receipt with each approach.\n\n\n| Approach | Allocations | Total character copies | Big-O |\n| -------- | ----------- | --------------------- | ----- |\n| `receipt = receipt + line` in a loop | ~10,000 new `String` objects | ~50 million (sum of growing lengths) | O(n squared) |\n| `receipt.append(line)` with `StringBuilder` | ~30 buffer grows total | ~10 million (linear in total length) | O(n) |\n\n\nExact numbers depend on the JVM and the data, but the shape is consistent across runs. The `+` loop runs noticeably slower as the count grows. The `StringBuilder` loop scales smoothly because the per-iteration cost stays roughly constant.\n\n\n```java\npublic class ConcatComparison {\n public static void main(String[] args) {\n int lineCount = 20_000;\n\n long startPlus = System.nanoTime();\n String plusResult = \"\";\n for (int i = 0; i < lineCount; i++) {\n plusResult = plusResult + \"Item \" + i + \" at $9.99\\n\";\n }\n long elapsedPlus = System.nanoTime() - startPlus;\n\n long startBuilder = System.nanoTime();\n StringBuilder builder = new StringBuilder(lineCount * 25);\n for (int i = 0; i < lineCount; i++) {\n builder.append(\"Item \").append(i).append(\" at $9.99\\n\");\n }\n String builderResult = builder.toString();\n long elapsedBuilder = System.nanoTime() - startBuilder;\n\n System.out.println(\"Lines built: \" + lineCount);\n System.out.println(\"Plus approach length: \" + plusResult.length());\n System.out.println(\"Builder approach length: \" + builderResult.length());\n System.out.println(\"Plus took (ms approx): \" + (elapsedPlus / 1_000_000));\n System.out.println(\"Builder took (ms approx): \" + (elapsedBuilder / 1_000_000));\n }\n}\n```\n\n\n**Output (approximate, varies per machine):**\n\n\n```shell\nLines built: 20000\nPlus approach length: 396789\nBuilder approach length: 396789\nPlus took (ms approx): 1400\nBuilder took (ms approx): 4\n```\n\n\nDon't read the exact millisecond numbers literally. They depend on your machine, the JVM version, JIT warmup, and what else the system is doing. The ratio is what matters. The plus loop takes hundreds of times longer because of the O(n squared) work it's doing. For 200,000 lines instead of 20,000, the gap widens further. The builder version stays linear.\n\nThat said, `+` isn't always worse. Two or three `+` operations in a row produce nearly identical bytecode to a manual builder, and the source is easier to read. The rule of thumb is:\n\n- **Use `+`** for combining a small, fixed number of pieces in straight-line code.\n- **Use `StringBuilder`** for concatenating inside a loop, when the number of pieces depends on runtime data, or when content has to be built up gradually across multiple statements.\n\nFor one-off concatenations, the readability of `+` wins. For dynamic builds, the performance of `StringBuilder` wins.\n\n---\n\n# Summary\n\n- `StringBuilder` is a mutable `char[]` buffer plus a `count`. `append` writes into the buffer in place and only allocates a new array when the buffer is full, which makes building large strings linear in total length.\n- Concatenating with `+` in a loop is O(n squared) on the total output length because `String` is immutable and each iteration copies every character built so far.\n- The default capacity is 16. `new StringBuilder(int)` lets you pre-size for known workloads, and `new StringBuilder(String)` starts the builder with content and capacity `str.length() + 16`.\n- When a grow is needed, the buffer expands to at least `(oldCapacity * 2) + 2` and copies all existing characters. Pre-sizing avoids these copies.\n- Every mutating method (`append`, `insert`, `delete`, `replace`, `reverse`, `setCharAt`) returns `this`, so calls can be chained into a single expression.\n- `StringBuilder` doesn't override `equals` or `hashCode`, so comparing two builders with `equals` checks reference identity. Call `toString()` first and compare strings.\n- `StringBuilder` isn't a `String`. It has no `toUpperCase`, no `substring`, no regex methods. Materialize a `String` with `toString()` before using `String` APIs.\n- Use `+` for a small, fixed number of pieces in straight-line code. Use `StringBuilder` for loops and dynamic builds.\n\n`StringBuilder` is fast because it makes no thread-safety guarantees. Two threads appending to the same builder can corrupt it.","pageType":"java"}

StringBuilder

Get Premium