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.

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.

Output

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.

Output

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.

Output

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.

Output

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

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.

Output

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.

This method tries to reduce the storage if it is larger than required. Let’s have a look at the source code of this method taken from the OpenJDK 8 AbstractStringBuilder class.

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.

Output

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.

This example is a part of the Java StringBuffer tutorial and Java StringBuilder tutorial.

Please let me know your views in the comments section below.

About the author

RahimV

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.

Add Comment

Your email address will not be published. Required fields are marked *