Strings, StringBuilder, StringBuffer

You have used String since your first program, the moment you printed a line of text. It has felt like any other value, sitting in a variable the way an int does. Underneath, a String is an object with an unusual rule: once it exists, its text never changes. This lesson shows how the string methods live with that rule, why comparing two strings with == is one of the most common mistakes in Java, and which class to use when you need text that does change.

The one surprising thing: a string never changes#

Start with a question that sounds as if it has an obvious answer. A string holds text in lower case, you want it in upper case, so you call toUpperCase() on it. What does the string hold afterwards? Decide, then press Run.

It still prints hello. The call did run, but the upper-case text it made went nowhere, because nothing kept it. A String method never rewrites the original text: once a Java string exists, the characters inside it never change. A String is immutable, which means it cannot be changed after it is made.

So toUpperCase() gives back a new string, separate from the original. To use it, store it in a variable.

Now both are there. greeting still holds hello, and shout holds the new string HELLO that toUpperCase() built and returned. Nothing was edited: there is the old string and the new one.

Key idea

A String method that seems to change a string returns a new string and leaves the original as it was. If you do not store the return value, the work is lost.

The methods you will use most#

A string carries a set of methods. None of them change the string. Each one reads it and hands back a number, a character, a boolean or a new string.

Length and one character at a time

length() tells you how many characters a string has. charAt(i) hands you the single character at position i, counting from zero, like an array index. The first character is at 0 and the last is at length() - 1.

That prints 12, then H, then o, then d. The comma and the space both count toward the length of 12. A space is a character like any other.

Pulling out a piece with substring

substring(start, end) returns the part of the text from index start up to, but not including, index end. With one argument, substring(start) runs from start to the end of the string.

The first line prints cde: the characters at indexes 2, 3 and 4, stopping just before 5. The second prints def, from index 3 to the end. Because the character at end is left out, substring(a, b) always has exactly b - a characters: substring(2, 5) has 3.

Searching: indexOf and contains

indexOf(text) finds where a smaller piece of text first appears and returns the index where it starts, or -1 when it is not there at all. contains(text) answers the plain yes-or-no question with a boolean.

This prints 7, then -1, then true, then false. World starts at index 7. zebra is not in the sentence, so indexOf answers -1 and contains answers false.

Case, trimming and replacing

toUpperCase() and toLowerCase() return a new string in that case. trim() returns a copy without the spaces at the start and the end, which is handy for text someone typed. replace(a, b) returns a copy with every a swapped for b. All of them leave the original alone.

It prints Hello with the padding gone, then HELLO in upper case with its spaces still around it, then bonono. The last line prints the original, padding and all: messy never changed.

A few more you will meet#

The String class has dozens of methods. A few more come up often enough to know by name. Several of them arrived in Java 11, so older tutorials may not show them.

The name starts with holiday, so the first line is true. The second line calls one method on the result of another: toLowerCase() returns a new string, and endsWith runs on that string, so the capital JPG still counts and the answer is true. The last o is at index 12. A string of three spaces is not empty, since its length is 3, but it is blank, because it holds only spaces: false true. repeat(3) gives hahaha. Finally split(",") cuts the text at every comma and hands back the pieces in an array, and String.join glues them back together with a plus sign between them.

Putting a few together

A lot of string work is a loop plus charAt. This program counts how many times the letter a appears in a word.

Step through it and watch count climb. banana has an a at indexes 1, 3 and 5, so the last line is a appears 3 times. The test word.charAt(i) == 'a' uses == on two char values, and that is correct: a char is a primitive, one number underneath, so == compares the values. A whole string is an object, and that changes what == means, as the next section shows.

Comparing strings: equals, not ==#

To ask whether two strings hold the same text, use the equals method.

This prints false, then true, then true. equals compares the characters one by one, and it cares about case: cat and Cat differ in the first letter, so the answer is false. When case should not matter, equalsIgnoreCase compares as if both were in the same case, so cat and Cat come out equal.

Why not ==, which worked for char values a moment ago? Because a String is an object, and for objects == answers a different question. It does not compare the text; it checks whether two variables point at the very same object. You met this in object references: a String variable holds a reference to a string object in memory. Two separate string objects can hold the same letters, and then == says false even though the text matches.

Whether two strings with the same letters are one object or two depends on how each one was made. Decide what this prints before you run it.

It prints true, false, true. A string literal is text written in quotes in your code, such as "cat". Java keeps one shared object for each different literal, in a table called the string pool. a and b were both written as the literal "cat", so they point at the same pooled object and a == b is true. new String("cat") always makes a new object holding a copy of the letters, so a == c is false. equals compares the letters, so a.equals(c) is true.

The bug: comparing what someone typed#

With only literals in a program, == can look as if it works. The trouble starts with text that only exists once the program is running. This program asks a yes-or-no question and checks the answer both ways. The Keyboard input box holds yes, as if someone typed it and pressed Enter. One method is new: in.nextLine() reads everything typed up to the Enter key and hands it back as a String.

Someone typed exactly yes, and the == check still decides not to save. nextLine() built a new String object from the keystrokes, while the "yes" in the code is the pooled literal: the same letters in two objects, so == is false. equals compares the letters and gets it right. Step through it and read the narration on the first if, which shows both sides holding yes and the answer false. Then change the input to no and run it again: both checks now agree.

Which strings are the same object?#

Here is the whole rule. Every literal is the pooled object for its text. So is any text the compiler can work out before the program runs, such as "ca" + "t": the compiler joins the two literals into "cat" and uses the pooled one. Text made while the program runs is a new object each time, whether it comes from new String(...), from the keyboard, or from + with a variable in it. The method intern()looks a string's text up in the pool and hands back the pooled object.

It prints true, false, true, true. joined was worked out by the compiler, so it is the pooled cat, the same object as word. built has a variable in it, start, so it is joined while the program runs and becomes a new object: == says false while equals says true. built.intern() hands back the pooled cat. You will rarely call intern() yourself; it exists so that a program holding many copies of the same text can keep just one.

The lab below draws the rule. Pick how a and b are made. Every choice holds the letters c, a, t, yet the answer from == changes with the choice, while equals always says true.

1import java.util.Scanner;
2 
3public class Main {
4    public static void main(String[] args) {
5        Scanner in = new Scanner(System.in);
6        System.out.println("What is the capital of France?");
7        String answer = in.nextLine();
8 
9        if (answer == "Paris") {
10            System.out.println("Correct!");
11        } else {
12            System.out.println("Not quite. It is Paris.");
13        }
14    }
15}

Key idea

== asks “is it the same object?”. equalsasks “is it the same text?”. For strings you almost always mean the second, so compare them with equals.

Ordering with compareTo

Sometimes you need before-or-after instead of equal-or-not, to put words in dictionary order. a.compareTo(b) returns a negative number when a comes before b, zero when they are equal, and a positive number when a comes after b.

This prints -1, then 1, then 0. apple comes before banana, so the first result is negative; swap the two and it turns positive; identical strings give 0. Test the sign, not an exact number: if (x.compareTo(y) < 0)reads “if x comes before y”.

Why make strings immutable at all?#

Immutability can feel like a nuisance the first time it surprises you. It was a deliberate choice, and it buys safety. A string can never change, so it is always safe to share: when two parts of a program hold the same string, neither can alter it behind the other's back. When you pass a name to a method that keeps it, you never have to worry that the method will change your text later, or that you will change its.

Building strings: StringBuilder#

Immutability has one real cost, and it shows when you build a long string piece by piece in a loop. Each += on a string has to make a whole new string, copy everything built so far into it, and add the next piece. Join a hundred pieces that way and you make and throw away ninety-nine strings along the way, copying the early pieces again and again. For a few pieces it does not matter. For many thousands in a loop it gets slow.

A StringBuilder holds text you can change in place: it is a mutable partner to String. You append to it as often as you like, and at the end you call toString() once to get the finished, immutable String. Step through this and watch the memory view: sb points at one builder, drawn as a row of characters, and each append adds two characters to the end of that same row.

It prints ababab. There was one builder from start to finish, and no String was made until toString() copied the finished text out.

A builder changes in place

Changing in place makes a difference when two variables share one object. Decide what this prints.

It prints tea, then teapot. t = t + "pot" made a new string and pointed t at it, so s still points at the unchanged tea. b = a copied the reference to the one builder, and append changed that builder in place, so a sees the change. In the memory view the builder appears once, labelled with both names.

More builder methods

Besides append, a builder can insert, delete, replace and reverse. These methods change the builder and hand back that same builder.

• reverse() turns stressed into desserts.
• insert(5, ",") puts a comma at index 5, just before the space: Hello, World.
• deleteCharAt removes the last character and setCharAt replaces the first, which leaves Jello, Worl, 11 characters long.
• The last part chains three calls. Each append returns the same builder, so the next append runs on it. append also takes numbers and single characters and adds them as text, so the builder ends up holding Room 12B.

Printing a builder, or joining it to a string with +, uses the text it holds at that moment.

1import java.util.Scanner;
2 
3public class Main {
4    public static void main(String[] args) {
5        Scanner in = new Scanner(System.in);
6        int n = in.nextInt();
7        StringBuilder list = new StringBuilder();
8 
9        // TODO: append 1, 2, ... n with ", " between them
10 
11        System.out.println(list.toString());
12    }
13}

Key idea

Use String for finished text. Use StringBuilder while you are still putting text together piece by piece, especially in a loop, then call toString() to get a String back.

The sibling: StringBuffer

StringBuffer is an older near-twin of StringBuilder. It has been in Java since the first version, and StringBuilder arrived in Java 5. Their methods are the same: append, insert, reverse, toString and the rest. The difference is that StringBuffer is thread-safe. A program can run several jobs at the same moment, each one called a thread, and several threads can share one StringBuffer without scrambling its text.

So build with StringBuilder by default. Its own documentation recommends it wherever a single thread uses the builder, which is nearly always. You will mostly see StringBuffer in older code.

Further reading#

• Strings, the dev.java tutorial on creating, searching and comparing strings
• String Builders, the dev.java tutorial on StringBuilder
• String in the Java SE 25 API documentation, with every method and the exact rule compareTo follows
• String literals in the Java Language Specification, section 3.10.5, which explains which strings share one object