commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Volker Glave (JIRA)" <j...@apache.org>
Subject [jira] Updated: (LANG-643) Javadoc StringUtils.left() claims to throw on negative len, but doesn't
Date Fri, 13 Aug 2010 15:00:28 GMT

     [ https://issues.apache.org/jira/browse/LANG-643?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Volker Glave updated LANG-643:
------------------------------

    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)

{quote}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. {color:red}An exception is thrown if len is negative.{color}

     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, {color:red}must be zero or positive{color}
    Returns:
        the leftmost characters, null if null String input{quote}

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

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

..., and by example, too:

{code}$ 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
><{code}

The Javadoc comment should be updated.

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

Volker Glave

  was:
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)

{quote}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. {color:red}An exception is thrown if len is negative.{color}

     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, {color:red}must be zero or positive{color}
    Returns:
        the leftmost characters, null if null String input{quote}

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

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

..., and by example, too:

{code}$ 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
><{code}

The Javadoc comment should by updated.

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

Volker Glave


> Javadoc StringUtils.left() claims to throw on negative len, but doesn't
> -----------------------------------------------------------------------
>
>                 Key: LANG-643
>                 URL: https://issues.apache.org/jira/browse/LANG-643
>             Project: Commons Lang
>          Issue Type: Bug
>          Components: lang.*
>    Affects Versions: 2.5, 3.0
>            Reporter: Volker Glave
>            Priority: Minor
>
> 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)
> {quote}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. {color:red}An exception is thrown if len is negative.{color}
>      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, {color:red}must be zero or positive{color}
>     Returns:
>         the leftmost characters, null if null String input{quote}
> 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 ...
> {code}........
>         if (len < 0) {
>             return EMPTY;
>         }
>         ...{code}
> ..., and by example, too:
> {code}$ 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
> ><{code}
> The Javadoc comment should be updated.
> Same issue for right() and mid(), by the way.
> Volker Glave

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message