Java StringBuilder Capacity (StringBuffer capacity)

This example shows what is the StringBuilder capacity, how to get the current capacity, how to ensure minimum specified capacity, how to reduce the capacity. Since the StringBuilder class is a drop-in replacement for StringBuffer class, this applies to the StringBuffer capacity as well.

What is StringBuilder capacity (or StringBuffer capacity)?

Java StringBuilder and StringBuffer classes maintain an internal character array to store the contents. As and when we add more content to the StringBuilder or StringBuffer object, the size of the internal character array is increased automatically.

The size or length of this character array is called the capacity of StringBuilder or StringBuffer object. In other words, the capacity is the number of characters the internal character array can store before the allocation of a new and larger internal array is required.

How to get the capacity of StringBuilder?

The capacity method of the StringBuilder or StringBuffer class returns the current capacity of the object.

1

publicintcapacity()

This method returns the current capacity of the StringBuilder or StringBuffer object.

What is the default capacity of the StringBuilder or StringBuffer object?

The default capacity of the StringBuilder or StringBuffer object is 16. So if we create a StringBuilder or StringBuffer object using the default constructor, the size of its internal array is 16. In other words, the created object can hold up to 16 characters before it needs to reallocate the larger internal array.

Please have a look at the below given example.

1

2

3

4

5

6

7

8

9

10

publicclassStringBuilderCapacityExample{

publicstaticvoidmain(String[]args){

StringBuilder sbld=newStringBuilder();

//get the current capacity using the capacity method

System.out.println(sbld.capacity());

}

}

Output

1

16

If you use the StringBuilder constructor which accepts either String or CharSequence arguments, the capacity of the resulting new StringBuilder object will be 16 + length of the String or CharSequence.

1

2

3

4

5

6

7

StringBuilder sbld=newStringBuilder("Hello world");

/*

* The capacity of this StringBuilder object will be

* 16 (default) + 11 (length of "hello world") = 27

*/

System.out.println(sbld.capacity());

Output

1

27

What is the difference between StringBuilder length and capacity?

The StringBuilder length is the actual number of characters stored in the object while the capacity is the size of the internal character array buffer.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

StringBuilder sbld=newStringBuilder();

//this will be 0 as StringBuilder is empty

System.out.println("Length: "+sbld.length());

//this will be 16, the default size of an internal array

System.out.println("Capacity: "+sbld.capacity());

sbld.append("Hello");

//this will be 5 i.e. character count

System.out.println("Length: "+sbld.length());

//this will be 16, the default size of an internal array

System.out.println("Capacity: "+sbld.capacity());

Output

1

2

3

4

Length: 0

Capacity: 16

Length: 5

Capacity: 16

How to create a StringBuilder object with a specified capacity?

We can use the StringBuilder or StringBuffer constructor which accepts the capacity argument to create an object with the specified capacity.

1

2

3

StringBuilder sbld=newStringBuilder(100);

System.out.println(sbld.capacity());

Output

1

100

If you want to increase the capacity of an existing StringBuilder or StringBuffer object, you can use the ensureCapacity method.

1

publicvoidensureCapacity(intminimumCapacity)

This method ensures that the current capacity of an object is at least equal to the specified minimum capacity. This method allocates a larger internal character array whose capacity is larger of the specified minimum capacity and (current capacity * 2) + 2.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

StringBuilder sbld1=newStringBuilder("Hello");

//current capacity is 16 + 5 = 21

System.out.println("Current: "+sbld1.capacity());

/*

* The new capacity will be maximum of

* 1. 25

* 2. (21 * 2 ) + 2 = 44

* that is 44.

*/

sbld1.ensureCapacity(25);

System.out.println("New: "+sbld1.capacity());

StringBuilder sbld2=newStringBuilder("Hello");

System.out.println("Current: "+sbld2.capacity());

/*

* The new capacity will be maximum of

* 1. 50

* 2. (21 * 2 ) + 2 = 44

* which is 50.

*/

sbld2.ensureCapacity(50);

System.out.println(sbld2.capacity());

Output

1

2

3

4

Current: 21

New: 44

Current: 21

50

How to decrease capacity?

The StringBuilder/StringBuffer class automatically increases the capacity of the internal array as and when needed, but it does not decrease the capacity when it is no more needed. For example, if you store 1000 characters in the StringBuilder object, its capacity is increased to store at least 1000 characters.

But when you delete the 999 characters out of 1000, the StringBuilder class does not allocate a smaller internal array to reduce the capacity. Once increased, the capacity stays the same or further increased if needed. If we do not need the increased capacity, we need to manually decrease the occupied memory using the trimToSize method.

Basically, it allocates a new smaller array if the current internal array length is greater than the number of characters stored in the StringBuilder or StringBuffer object.

1

2

3

4

5

6

7

8

9

10

StringBuilder sbld=newStringBuilder(1000);

System.out.println("Current: "+sbld.capacity());

sbld.append("Hello");

/*

* To reduce the capacity, use the trimToSize method

*/

sbld.trimToSize();

System.out.println("New: "+sbld.capacity());

Output

1

2

Current: 1000

New: 5

You should always call this method to free up the memory when you do not need it anymore.

Why should I care about the capacity?

At this point, you might have a question that since the capacity is automatically managed, why should I care? In order to answer this question, we first need to understand how the capacity is increased when needed.

The StringBuilder or StringBuffer uses an internal array to store its content. When the content grows beyond the length of this internal array, the StringBuilder allocates a new and empty internal array big enough to fit the content. After that, it copies the existing content of the old array to the new array. This is a costly operation in terms of performance.

If you want to add thousands of characters in the StringBuilder or StringBuffer object in small batches, imagine how many times the costly reallocation needs to be done again and again.

In that case, you might ask, how do I ensure maximum performance? Well, if you have a fair idea of the approximate number of characters you are going to store in the StringBuilder object then create the object with the required initial capacity using the constructor. This will reduce the number of reallocation of an internal array.

You can also create an object with the default capacity and when needed increase its capacity using the ensureCapacity method.

Also, do not forget to decrease the capacity when it is no more needed using the trimToSize method to free up the allocated memory.

About the author

RahimV

My name is RahimV and I have over 16 years of experience in designing and developing Java applications. Over the years I have worked with many fortune 500 companies as an eCommerce Architect. My goal is to provide high quality but simple to understand Java tutorials and examples for free. If you like my website, follow me on Facebook and Twitter.