Strings in Java are immutable which means that once created, a string cannot be changed. If we want to modify the content of a string object, we should create a new string. This may not be the best way when we perform a lot of modifications because each operation creates a new object, which is bad for performance.

Fortunately, there is a special class named StringBuilder that is used to create mutable string objects. An object of this class is similar to a regular string, except that it can be modified. As an example, it is better to use StringBuilder than String where lots of concatenations are performed at runtime.

Constructing objects

It is possible to create an empty object of the type StringBuilder:

StringBuilder empty = new StringBuilder();
System.out.println(empty); // ""

or pass a string to it:

StringBuilder sb = new StringBuilder("Hello!");
System.out.println(sb); // "Hello!"

Note that we do not need to import anything to use this class in programs.

Some important methods

The StringBuilder class provides a set of useful methods to manipulate objects. Let's consider some of them.

int length() returns the length (the character count), like in regular strings and does not modify the object.

StringBuilder sb = new StringBuilder("I use Java");
System.out.println(sb.length()); // 10

char charAt(int index) returns a character located at the specified index. The first character has the index 0. This method does not modify the object.

StringBuilder sb = new StringBuilder("I use Java");
System.out.println(sb.charAt(0)); // 'I'
System.out.println(sb.charAt(6)); // 'J'

void setCharAt(int index, char ch) sets a character located at the given index to the specified character.

StringBuilder sb = new StringBuilder("start");
sb.setCharAt(1, 'm');
System.out.println(sb); // "smart"

StringBuilder deleteCharAt(int index) removes the character at the specified position.

StringBuilder sb = new StringBuilder("dessert");
sb.deleteCharAt(2);
System.out.println(sb); // "desert"

StringBuilder append(String str) concatenates the given string to the end of the invoking StringBuilder object. There are also several overloaded versions of this method to take primitive types and even arrays of characters.

StringBuilder sb = new StringBuilder("abc");
sb.append("123");
System.out.println(sb); // "abc123"

It is also possible to invoke this method multiple times on the same object in the same statement because this method returns the same modified object.

StringBuilder messageBuilder = new StringBuilder(); // empty

messageBuilder
        .append("From: [email protected]\n")
        .append("To: [email protected]\n")
        .append("Text: I lost my keys.\n")
        .append("Please, open the door!");

System.out.println(messageBuilder);

Output:

From: Kate@gmail.com
To: Max@gmail.com
Text: I lost my keys.
Please, open the door!

StringBuilder insert(int offset, String str) inserts the given string into the existing StringBuilder object at the given position indicated by the offset. This method has a lot of overloaded versions for different data types.

StringBuilder sb = new StringBuilder("I'm a programmer.");
sb.insert(6, "Java ");
System.out.println(sb); // "I'm a Java programmer."

StringBuilder replace(int start, int end, String str) replaces the substring from the specified start index (inclusive) to the end index (exclusive) with a given string.

StringBuilder sb = new StringBuilder("Let's use C#");
sb.replace(10, 12, "Java");
System.out.println(sb); // "Let's use Java"

StringBuilder delete(int start, int end) removes the substring from the start index (inclusive) to the end index (exclusive).

StringBuilder sb = new StringBuilder("Welcome");
sb.delete(0, 3);
System.out.println(sb); // "come"

StringBuilder reverse() causes this character sequence to be replaced by the reverse of the sequence.

StringBuilder sb = new StringBuilder("2 * 3 + 8 * 4");
sb.reverse();
System.out.println(sb); // "4 * 8 + 3 * 2"

Note, when you have a StringBuilder object, you can get a String by invoking the toString() method.

The length() and capacity() methods

Two methods should not be confused: length and capacity. The length returns the actual number of characters whereas capacity returns the amount of storage available for newly inserted characters, beyond which a new memory allocation will occur. The capacity is a part of the internal representation of StringBuilder, and its value will dynamically change.

The following example will help you better distinguish these methods:

StringBuilder sb = new StringBuilder(); // initial capacity is 16

System.out.println(sb.length());   // 0
System.out.println(sb.capacity()); // 16

sb.append("A very long string");

System.out.println(sb.length());   // 18
System.out.println(sb.capacity()); // 34

It is possible to specify the capacity when creating a StringBuilder object, but it is not used very often:

StringBuilder sb = new StringBuilder(30);

System.out.println(sb.length());   // 0
System.out.println(sb.capacity()); // 30

Conclusion

The Java StringBuilder class is used to create mutable strings, which can be modified at runtime. You can perform different operations on StringBuilder objects, like append, reverse, replace, delete, etc. No new objects will be created. It is recommended to use this class instead of String when a lot of modifications are performed. This will prevent the creation of multiple intermediate objects; therefore, it will work faster and require less memory. One common case for this is a sequence of concatenations.

Note, there is another similar class called String Buffer. We will consider it in coming topics.