Java StringBuilder capacity() Method

---

---

The Java StringBuilder capacity() method returns the current capacity. The capacity is defined as the amount of storage available for newly inserted characters, beyond which an allocation will occur.

In simple words, the default storage of an empty StringBuilder has a 16-character capacity. So, when some characters are already inserted, the method returns the number-of-existing-characters+16 as the output. Therefore, it goes beyond the allocation limit.

The capacity differs from the length of a string as the length only calculates the number of characters present in the string, while capacity calculates the maximum number of characters the StringBuilder can fit at the moment.

Syntax

Following is the syntax for Java StringBuilder capacity() method

public int capacity()

Parameters

This method does not accept any parameters.

Return Value

This method returns the current capacity.

Example: Getting Capacity of StringBuilder

If we invoke the method on any StringBuilder object, the return value will be the current capacity.

The following example shows the usage of Java StringBuilder capacity() method.

package com.tutorialspoint;

public class StringBuilderDemo {

   public static void main(String[] args) {

      StringBuilder buff = new StringBuilder("TutorialsPoint");
   
      // returns the current capacity of the String buffer i.e. 16 + 14
      System.out.println("capacity = " + buff.capacity());
    
      buff = new StringBuilder(" ");
      
      // returns the current capacity of the String buffer i.e. 16 + 1
      System.out.println("capacity = " + buff.capacity());
   }
}

Output

Let us compile and run the above program, this will produce the following result −

capacity = 30
capacity = 17

Example: Facing Exception while using null

If we pass a null value to the StringBuilder object as its input, the method throws a NullPointerException.

In the following program, we declare a StringBuilder object and assign a null value to it.

public class StringBuilderCapacity {
   public static void main(String args[]) {

      StringBuilder cap = new StringBuilder(null);

      System.out.println("The capacity: " + cap.capacity());
   }
}

Exception

If we try to compile and run the program above, instead of an output, the method throws a NullPointer Exception −

Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because "str" is null
        at java.base/java.lang.AbstractStringBuilder.<init>(AbstractStringBuilder.java:117)
        at java.base/java.lang.StringBuilder.<init>(StringBuilder.java:158)
        at StringBuilderCapacity.main(StringBuilderCapacity.java:6)

Example: Checking Default Capacity of StringBuilder

When we do not pass any input to the StringBuilder object, it is regarded as an empty StringBuilder. In this case, the method returns the default capacity value.

In the following example, we declare a StringBuilder object and no input is assigned to it. Therefore, the StringBuilder is empty. Then, we invoke the method on this StringBuilder trying to obtain the capacity.

public class StringBuilderCapacity {
   public static void main(String args[]) {

      // declare an empty StringBuilder
      StringBuilder cap = new StringBuilder();

      //print the default capacity
      System.out.println("The capacity: " + cap.capacity());
   }
}

Output

Let us compile and run the program above, the output is displayed as follows −

The capacity: 16