Summary

Javadoc for the constructor StringBuffer​(CharSequence seq) includes a promise that contradicts to the actual behavior.

Problem

Javadoc for the constructor StringBuffer​(CharSequence seq) states that "If the length of the specified CharSequence is less than or equal to zero, then an empty buffer of capacity 16 is returned." In fact, this promise is not kept with the current implementation: Passing negatively sized CharSequence results in an exception to be thrown.

Moreover, the exception thrown is not consistent: For some inputs (if length is from range [-16, -1]) it is IndexOutOfBoundsException and for other inputs (if length is less then -16) it is NegativeArraySizeException. This behavior is also observed with the constructor StringBuilder(CharSequence).

Solution

It is proposed to remove the quoted sentence from the javadoc.

For consistency, for any negatively sized argument, NegativeArraySizeException will be thrown from StringBuilder(CharSequence) and StringBuffer(CharSequence) constructors.

Specification

The javadoc will be modified as following:

-     * <p>
-     * If the length of the specified {@code CharSequence} is
-     * less than or equal to zero, then an empty buffer of capacity
-     * {@code 16} is returned.