Uploaded image for project: 'Commons Lang'
  1. Commons Lang
  2. LANG-643

Javadoc StringUtils.left() claims to throw on negative len, but doesn't

    XMLWordPrintableJSON

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 2.5, 3.0
    • Fix Version/s: 3.0
    • Component/s: lang.*
    • Labels:
      None

      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

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              vgl Volker Glave
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: