Java StringBuffer capacity() Method

The Java StringBuffer 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 StringBuffer 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 StringBuffer can fit at the moment.

Syntax

Following is the syntax for Java StringBuffer 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 StringBuffer

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

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

package com.tutorialspoint;

public class StringBufferDemo {

   public static void main(String[] args) {

      StringBuffer buff = new StringBuffer("TutorialsPoint");
   
      // returns the current capacity of the String buffer i.e. 16 + 14
      System.out.println("capacity = " + buff.capacity());
    
      buff = new StringBuffer(" ");
      
      // 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 StringBuffer object as its input, the method throws a NullPointerException.

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

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

      StringBuffer cap = new StringBuffer(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.StringBuffer.<init>(StringBuffer.java:158)
        at StringBufferCapacity.main(StringBufferCapacity.java:6)

Example: Checking Default Capacity of StringBuffer

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

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

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

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

      //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