[LANG-643] Javadoc StringUtils.left() claims to throw on negative len, but doesn't

• Type: Bug
• Status: Closed
• Priority: Minor
• Resolution: Fixed
• Affects Version/s: 2.5, 3.0
• Fix Version/s: 3.0
• Component/s: lang.*
• Assignee: Unassigned
• Reporter: Volker Glave
• Created: 13/Aug/10 14:52
• Updated: 29/Aug/10 22:39
• Resolved: 29/Aug/10 22:39

Description

The Javadoc comment for StringUtils.left() claims to throw an exception "if len is negative" (and that input argument len "must be zero or positive"):

http://commons.apache.org/lang/api/org/apache/commons/lang3/StringUtils.html#left(java.lang.String,%20int)
http://commons.apache.org/lang/api-2.5/org/apache/commons/lang/StringUtils.html#left(java.lang.String,%20int)

public static String left(String str, int len)

Gets the leftmost len characters of a String.

If len characters are not available, or the String is null, the String will be returned without an exception. An exception is thrown if len is negative.

StringUtils.left(null, *) = null
StringUtils.left(*, -ve) = ""
StringUtils.left("", *) = ""
StringUtils.left("abc", 0) = ""
StringUtils.left("abc", 2) = "ab"
StringUtils.left("abc", 4) = "abc"

Parameters:
str - the String to get the leftmost characters from, may be null
len - the length of the required String, must be zero or positive
Returns:
the leftmost characters, null if null String input

But it doesn't. (Luckily and preferably anyway .)
Instead an empty string will be returned. (Which is good.) As is seen from the implementation code ...

........
        if (len < 0) {
            return EMPTY;
        }
        ...

..., and by example, too:

$ cat StringUtilsTest.java
import org.apache.commons.lang.StringUtils;

public final class StringUtilsTest {
    public static void main(final String[] args) {
        final String result = StringUtils.left("foobar", -42);
        System.out.println(">" + result + "<");
    }
}

$ javac -classpath commons-lang.jar StringUtilsTest.java

$ java -classpath .:commons-lang.jar StringUtilsTest
><

The Javadoc comment should be updated.

Same issue for right() and mid(), by the way.

Volker Glave