commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/lang/src/java/org/apache/commons/lang StringUtils.java
Date Tue, 22 Jul 2003 23:36:41 GMT
scolebourne    2003/07/22 16:36:40

  Modified:    lang/src/test/org/apache/commons/lang StringUtilsTest.java
               lang/src/java/org/apache/commons/lang StringUtils.java
  Log:
  Add extra example code javadoc and related tests
  bug 21797, from Phil Steitz
  
  Revision  Changes    Path
  1.37      +209 -67   jakarta-commons/lang/src/test/org/apache/commons/lang/StringUtilsTest.java
  
  Index: StringUtilsTest.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/lang/src/test/org/apache/commons/lang/StringUtilsTest.java,v
  retrieving revision 1.36
  retrieving revision 1.37
  diff -u -r1.36 -r1.37
  --- StringUtilsTest.java	20 Jul 2003 23:57:26 -0000	1.36
  +++ StringUtilsTest.java	22 Jul 2003 23:36:39 -0000	1.37
  @@ -106,6 +106,9 @@
   
       private static final String[] ARRAY_LIST = { "foo", "bar", "baz" };
       private static final String[] EMPTY_ARRAY_LIST = {};
  +    private static final String[] NULL_ARRAY_LIST = {null};
  +    private static final String[] MIXED_ARRAY_LIST = {null, "", "foo"};
  +    private static final Object[] MIXED_TYPE_LIST = {new String("foo"), new Long(2)};
   
       private static final String SEPARATOR = ",";
       private static final char   SEPARATOR_CHAR = ';';
  @@ -191,53 +194,59 @@
                        "Hello aPACHE", StringUtils.swapCase("hELLO Apache") );
       }
   
  -    public void testJoin() {
  -        assertEquals(null, StringUtils.concatenate(null));
  -        assertEquals(null, StringUtils.join((Object[]) null, null));
  +    public void testJoin_ArrayChar() {
           assertEquals(null, StringUtils.join((Object[]) null, ','));
  -        assertEquals(null, StringUtils.join((Iterator) null, null));
  +        assertEquals(TEXT_LIST_CHAR, StringUtils.join(ARRAY_LIST, SEPARATOR_CHAR));
  +        assertEquals("", StringUtils.join(EMPTY_ARRAY_LIST, SEPARATOR_CHAR));
  +        assertEquals(";;foo", StringUtils.join(MIXED_ARRAY_LIST, SEPARATOR_CHAR));
  +        assertEquals("foo;2", StringUtils.join(MIXED_TYPE_LIST, SEPARATOR_CHAR));
  +    }
  +    
  +    public void testJoin_ArrayString() {
  +        assertEquals(null, StringUtils.join((Object[]) null, null));
  +        assertEquals(TEXT_LIST_NOSEP, StringUtils.join(ARRAY_LIST, null));
  +        assertEquals(TEXT_LIST_NOSEP, StringUtils.join(ARRAY_LIST, ""));
  +        
  +        assertEquals("", StringUtils.join(NULL_ARRAY_LIST, null));
  +        
  +        assertEquals("", StringUtils.join(EMPTY_ARRAY_LIST, null));
  +        assertEquals("", StringUtils.join(EMPTY_ARRAY_LIST, ""));
  +        assertEquals("", StringUtils.join(EMPTY_ARRAY_LIST, SEPARATOR));
  +
  +        assertEquals(TEXT_LIST, StringUtils.join(ARRAY_LIST, SEPARATOR));
  +        assertEquals(",,foo", StringUtils.join(MIXED_ARRAY_LIST, SEPARATOR));
  +        assertEquals("foo,2", StringUtils.join(MIXED_TYPE_LIST, SEPARATOR));
  +    }
  +    
  +    public void testJoin_IteratorChar() {
           assertEquals(null, StringUtils.join((Iterator) null, ','));
  +        assertEquals(TEXT_LIST_CHAR, StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
SEPARATOR_CHAR));
  +        assertEquals("", StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(), SEPARATOR_CHAR));
  +    }
  +    
  +    public void testJoin_IteratorString() {
  +        assertEquals(null, StringUtils.join((Iterator) null, null));
  +        assertEquals(TEXT_LIST_NOSEP, StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
null));
  +        assertEquals(TEXT_LIST_NOSEP, StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
""));
  +        
  +        assertEquals("", StringUtils.join(Arrays.asList(NULL_ARRAY_LIST).iterator(), null));
  +        
  +        assertEquals("", StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(), null));
  +        assertEquals("", StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(), ""));
  +        assertEquals("", StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(), SEPARATOR));
           
  -        assertEquals("concatenate(Object[]) failed",
  -                     TEXT_LIST_NOSEP, StringUtils.concatenate(ARRAY_LIST));
  -        assertEquals("join(Object[], String) failed", TEXT_LIST,
  -                     StringUtils.join(ARRAY_LIST, SEPARATOR));
  -        assertEquals("join(Iterator, String) failed", TEXT_LIST,
  -                     StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
  -                                      SEPARATOR));
  -
  -        assertEquals("join(Object[], char) failed", TEXT_LIST_CHAR,
  -                     StringUtils.join(ARRAY_LIST, SEPARATOR_CHAR));
  -        assertEquals("join(Iterator, char) failed", TEXT_LIST_CHAR,
  -                     StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
  -                                      SEPARATOR_CHAR));
  -
  -        assertEquals("join(Object[], null) failed", TEXT_LIST_NOSEP,
  -                     StringUtils.join(ARRAY_LIST, null));
  -        assertEquals("join(Iterator, null) failed", TEXT_LIST_NOSEP,
  -                     StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
  -                                      null));
  -
  -        assertEquals("concatenate(Object[]) failed",
  -                     "", StringUtils.concatenate(EMPTY_ARRAY_LIST));
  -        assertEquals("join(Object[], String) failed", "",
  -                     StringUtils.join(EMPTY_ARRAY_LIST, SEPARATOR));
  -        assertEquals("join(Iterator, String) failed", "",
  -                     StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(),
  -                                      SEPARATOR));
  -
  -        assertEquals("join(Object[], char) failed", "",
  -                     StringUtils.join(EMPTY_ARRAY_LIST, SEPARATOR_CHAR));
  -        assertEquals("join(Iterator, char) failed", "",
  -                     StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(),
  -                                      SEPARATOR_CHAR));
  -
  -        assertEquals("join(Object[], null) failed", "",
  -                     StringUtils.join(EMPTY_ARRAY_LIST, null));
  -        assertEquals("join(Iterator, null) failed", "",
  -                     StringUtils.join(Arrays.asList(EMPTY_ARRAY_LIST).iterator(),
  -                                      null));
  +        assertEquals(TEXT_LIST, StringUtils.join(Arrays.asList(ARRAY_LIST).iterator(),
SEPARATOR));
       }
  +    
  +    public void testConcatenate_Array() {
  +        assertEquals(null, StringUtils.concatenate(null));
  +        assertEquals("", StringUtils.concatenate(EMPTY_ARRAY_LIST));
  +        assertEquals("", StringUtils.concatenate(NULL_ARRAY_LIST));
  +        assertEquals("foo", StringUtils.concatenate(MIXED_ARRAY_LIST));
  +        assertEquals("foo2", StringUtils.concatenate(MIXED_TYPE_LIST));
  +    }
  +        
  +        
   
       public void testSplit_String() {
           assertEquals(null, StringUtils.split(null));
  @@ -468,6 +477,7 @@
               { FOO + "\r\n", FOO } ,
               { FOO + "\n" , FOO } ,
               { FOO + "\r", FOO },
  +            { FOO + " \r", FOO + " " },
               { "foo", "fo"},
               { "foo\nfoo", "foo\nfo" },
               { "\n", "" },
  @@ -488,15 +498,21 @@
       public void testChomp() {
   
           String[][] chompCases = {
  -            { FOO + "\r\n", FOO } ,
  -            { FOO + "\n" , FOO } ,
  +            { FOO + "\r\n", FOO },
  +            { FOO + "\n" , FOO },
               { FOO + "\r", FOO },
  +            { FOO + " \r", FOO + " " },
               { FOO, FOO },
               { FOO + "\n\n", FOO + "\n"},
  +            { FOO + "\r\n\r\n", FOO + "\r\n" },
               { "foo\nfoo", "foo\nfoo" },
  +            { "foo\n\rfoo", "foo\n\rfoo" },
               { "\n", "" },
               { "\r", "" },
               { "\r\n", "" },
  +            { "", "" },
  +            { null, null },
  +            { FOO + "\n\r", FOO + "\n"}
           };
           for (int i = 0; i < chompCases.length; i++) {
               String original = chompCases[i][0];
  @@ -511,6 +527,28 @@
                   "foobar", StringUtils.chomp("foobar", "baz"));
           assertEquals("chomp(String, String) failed",
                   "foo", StringUtils.chomp("foo", "foooo"));
  +        assertEquals("chomp(String, String) failed",
  +                "foobar", StringUtils.chomp("foobar", ""));
  +        assertEquals("chomp(String, String) failed",
  +                "foobar", StringUtils.chomp("foobar", null));
  +        assertEquals("chomp(String, String) failed",
  +                "", StringUtils.chomp("", "foo"));
  +        assertEquals("chomp(String, String) failed",
  +                "", StringUtils.chomp("", null));
  +        assertEquals("chomp(String, String) failed",
  +                "", StringUtils.chomp("", ""));
  +        assertEquals("chomp(String, String) failed",
  +                null, StringUtils.chomp(null, "foo"));
  +        assertEquals("chomp(String, String) failed",
  +                null, StringUtils.chomp(null, null));
  +        assertEquals("chomp(String, String) failed",
  +                null, StringUtils.chomp(null, ""));
  +        assertEquals("chomp(String, String) failed",
  +                "", StringUtils.chomp("foo", "foo"));
  +        assertEquals("chomp(String, String) failed",
  +                " ", StringUtils.chomp(" foo", "foo"));
  +        assertEquals("chomp(String, String) failed",
  +                "foo ", StringUtils.chomp("foo ", "foo"));
       }
   
       public void testChopNewLine() {
  @@ -544,6 +582,9 @@
               {"foo\nbar\nbaz", "foo\nbar"},
               {null, null},
               {"", ""},
  +            {"\n", ""},
  +            {"abc \n", "abc "},
  +            {"abc\r\n", "abc\r"},
               {"foo", "foo"},
           };
           for (int i = 0; i < sliceCases.length; i++) {
  @@ -552,28 +593,89 @@
               assertEquals("slice(String) failed",
                       expectedResult, StringUtils.slice(original));
           }
  +    }
  +    
  +    public void testSlice_StringString() {
  +        assertEquals("fooXXbar", StringUtils.slice("fooXXbarXXbaz", "XX"));
   
  -        String original = "fooXXbarXXbaz";
  -        String sep = "XX";
  -
  -        assertEquals("fooXXbar", StringUtils.slice(original, sep) );
  -        assertEquals(null, StringUtils.slice(null, sep) );
  -        assertEquals(null, StringUtils.slice(null, null) );
  -        assertEquals("foo", StringUtils.slice("foo", null) );
  -        assertEquals("foo", StringUtils.slice("foo", "b") );
  -        assertEquals("fo", StringUtils.slice("foo", "o") );
  -
  -        assertEquals("baz", StringUtils.sliceRemainder(original, sep) );
  -        assertEquals(null, StringUtils.sliceRemainder(null, sep) );
  -        assertEquals(null, StringUtils.sliceRemainder(null, null) );
  -        assertEquals("", StringUtils.sliceRemainder("foo", null) );
  -        assertEquals("", StringUtils.sliceRemainder("foo", "b") );
  -        assertEquals("t", StringUtils.sliceRemainder("foot", "o") );
  -
  -        assertEquals("foo", StringUtils.sliceFirst(original, sep) );
  -
  -        assertEquals("barXXbaz", StringUtils.sliceFirstRemainder(original, sep) );
  +        assertEquals(null, StringUtils.slice(null, null));
  +        assertEquals(null, StringUtils.slice(null, ""));
  +        assertEquals(null, StringUtils.slice(null, "XX"));
  +        assertEquals("", StringUtils.slice("", null));
  +        assertEquals("", StringUtils.slice("", ""));
  +        assertEquals("", StringUtils.slice("", "XX"));
  +
  +        assertEquals("foo", StringUtils.slice("foo", null));
  +        assertEquals("foo", StringUtils.slice("foo", "b"));
  +        assertEquals("fo", StringUtils.slice("foo", "o"));
  +        assertEquals("abc\r\n", StringUtils.slice("abc\r\n", "d"));
  +        assertEquals("abc", StringUtils.slice("abcdabc", "d"));
  +        assertEquals("abcdabc", StringUtils.slice("abcdabcd", "d"));
  +        assertEquals("a", StringUtils.slice("abc", "b"));
  +        assertEquals("abc ", StringUtils.slice("abc \n", "\n"));
  +        assertEquals("a", StringUtils.slice("a", null));
  +        assertEquals("a", StringUtils.slice("a", ""));
  +        assertEquals("", StringUtils.slice("a", "a"));
  +    }
  +    
  +    public void testSliceRemainder_StringString() {
  +        assertEquals("baz", StringUtils.sliceRemainder("fooXXbarXXbaz", "XX"));
   
  +        assertEquals(null, StringUtils.sliceRemainder(null, null));
  +        assertEquals(null, StringUtils.sliceRemainder(null, ""));
  +        assertEquals(null, StringUtils.sliceRemainder(null, "XX"));
  +        assertEquals("", StringUtils.sliceRemainder("", null));
  +        assertEquals("", StringUtils.sliceRemainder("", ""));
  +        assertEquals("", StringUtils.sliceRemainder("", "a"));
  +
  +        assertEquals("", StringUtils.sliceRemainder("foo", null));
  +        assertEquals("", StringUtils.sliceRemainder("foo", "b"));
  +        assertEquals("t", StringUtils.sliceRemainder("foot", "o"));
  +        assertEquals("bc", StringUtils.sliceRemainder("abc", "a"));
  +        assertEquals("a", StringUtils.sliceRemainder("abcba", "b"));
  +        assertEquals("", StringUtils.sliceRemainder("abc", "c"));
  +        assertEquals("", StringUtils.sliceRemainder("", "d"));
  +        assertEquals("", StringUtils.sliceRemainder("abc", ""));
  +    }        
  +        
  +    public void testSliceFirst_StringString() {
  +        assertEquals("foo", StringUtils.sliceFirst("fooXXbarXXbaz", "XX"));
  +
  +        assertEquals(null, StringUtils.sliceFirst(null, null));
  +        assertEquals(null, StringUtils.sliceFirst(null, ""));
  +        assertEquals(null, StringUtils.sliceFirst(null, "XX"));
  +        assertEquals("", StringUtils.sliceFirst("", null));
  +        assertEquals("", StringUtils.sliceFirst("", ""));
  +        assertEquals("", StringUtils.sliceFirst("", "XX"));
  +        
  +        assertEquals("foo", StringUtils.sliceFirst("foo", null));
  +        assertEquals("", StringUtils.sliceFirst("foo", "b"));
  +        assertEquals("f", StringUtils.sliceFirst("foot", "o"));
  +        assertEquals("", StringUtils.sliceFirst("abc", "a"));
  +        assertEquals("a", StringUtils.sliceFirst("abcba", "b"));
  +        assertEquals("ab", StringUtils.sliceFirst("abc", "c"));
  +        assertEquals("abc", StringUtils.sliceFirst("abc", ""));
  +        assertEquals("", StringUtils.sliceFirst("abc", "d"));
  +    }
  +    
  +    public void testSliceFirstRemainder_StringString() {
  +        assertEquals("barXXbaz", StringUtils.sliceFirstRemainder("fooXXbarXXbaz", "XX"));
  +        
  +        assertEquals(null, StringUtils.sliceFirstRemainder(null, null));
  +        assertEquals(null, StringUtils.sliceFirstRemainder(null, ""));
  +        assertEquals(null, StringUtils.sliceFirstRemainder(null, "XX"));
  +        assertEquals("", StringUtils.sliceFirstRemainder("", null));
  +        assertEquals("", StringUtils.sliceFirstRemainder("", ""));
  +        assertEquals("", StringUtils.sliceFirstRemainder("", "XX"));
  +        
  +        assertEquals("", StringUtils.sliceFirstRemainder("foo", null));
  +        assertEquals("foo", StringUtils.sliceFirstRemainder("foo", "b"));
  +        assertEquals("ot", StringUtils.sliceFirstRemainder("foot", "o"));
  +        assertEquals("bc", StringUtils.sliceFirstRemainder("abc", "a"));
  +        assertEquals("cba", StringUtils.sliceFirstRemainder("abcba", "b"));
  +        assertEquals("", StringUtils.sliceFirstRemainder("abc", "c"));
  +        assertEquals("", StringUtils.sliceFirstRemainder("abc", ""));
  +        assertEquals("abc", StringUtils.sliceFirstRemainder("abc", "d"));
       }
   
       //-----------------------------------------------------------------------
  @@ -764,12 +866,38 @@
           assertEquals("raspberry p...", StringUtils.abbreviate(raspberry, 14));
           assertEquals("raspberry peach", StringUtils.abbreviate("raspberry peach", 15));
           assertEquals("raspberry peach", StringUtils.abbreviate("raspberry peach", 16));
  +        assertEquals("abc...", StringUtils.abbreviate("abcdefg", 6));
  +        assertEquals("abcdefg", StringUtils.abbreviate("abcdefg", 7));
  +        assertEquals("abcdefg", StringUtils.abbreviate("abcdefg", 8));
  +        assertEquals("a...", StringUtils.abbreviate("abcdefg", 4));
  +        assertEquals("", StringUtils.abbreviate("", 4));
  +        
  +        try {
  +            String res = StringUtils.abbreviate("abc", 3);
  +            fail("StringUtils.abbreviate expecting IllegalArgumentException");
  +        } catch (IllegalArgumentException ex) {
  +                // empty
  +        }              
       }
       
       public void testAbbreviate_StringIntInt() {
           assertEquals(null, StringUtils.abbreviate(null, 10, 12));
           assertEquals("", StringUtils.abbreviate("", 0, 10));
           assertEquals("", StringUtils.abbreviate("", 2, 10));
  +        
  +        try {
  +            String res = StringUtils.abbreviate("abcdefghij", 0, 3);
  +            fail("StringUtils.abbreviate expecting IllegalArgumentException");
  +        } catch (IllegalArgumentException ex) {
  +                // empty
  +        }      
  +        try {
  +            String res = StringUtils.abbreviate("abcdefghij", 5, 6);
  +            fail("StringUtils.abbreviate expecting IllegalArgumentException");
  +        } catch (IllegalArgumentException ex) {
  +                // empty
  +        }      
  +        
   
           String raspberry = "raspberry peach";
           assertEquals("raspberry peach", StringUtils.abbreviate(raspberry, 11, 15));
  @@ -844,7 +972,21 @@
           assertEquals(3, StringUtils.getLevenshteinDistance("fly", "ant") );
           assertEquals(7, StringUtils.getLevenshteinDistance("elephant", "hippo") );
           assertEquals(7, StringUtils.getLevenshteinDistance("hippo", "elephant") );
  +        assertEquals(8, StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") );
  +        assertEquals(8, StringUtils.getLevenshteinDistance("zzzzzzzz", "hippo") );
           assertEquals(1, StringUtils.getLevenshteinDistance("hello", "hallo") );
  +        try {
  +            int d = StringUtils.getLevenshteinDistance("a", null);
  +            fail("expecting IllegalArgumentException");
  +        } catch (IllegalArgumentException ex) {
  +            // empty
  +        }
  +        try {
  +            int d = StringUtils.getLevenshteinDistance(null, "a");
  +            fail("expecting IllegalArgumentException");
  +        } catch (IllegalArgumentException ex) {
  +            // empty
  +        }
       }
   
   }
  
  
  
  1.77      +254 -46   jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java
  
  Index: StringUtils.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java,v
  retrieving revision 1.76
  retrieving revision 1.77
  diff -u -r1.76 -r1.77
  --- StringUtils.java	21 Jul 2003 00:41:13 -0000	1.76
  +++ StringUtils.java	22 Jul 2003 23:36:40 -0000	1.77
  @@ -1762,9 +1762,20 @@
       // Joining
       //-----------------------------------------------------------------------
       /**
  -     * <p>Concatenates elements of an array into a single String.</p>
  +     * <p>Concatenates elements of an array into a single String.
  +     * Null objects or empty strings within the array are represented by 
  +     * empty strings.</p>
  +     *
  +     * <p>The difference from join is that concatenate has no delimiter -- i.e.,
<br>
  +     * <code>StringUtils.concatenate(array) = StringUtils.join(array, null)</code>.</p>
        *
  -     * <p>The difference from join is that concatenate has no delimiter.</p>
  +     * <pre>
  +     * StringUtils.concatenate(null)            = null
  +     * StringUtils.concatenate([])              = ""
  +     * StringUtils.concatenate([null])          = ""
  +     * StringUtils.concatenate(["a", "b", "c"]) = "abc"
  +     * StringUtils.concatenate([null, "", "a"]) = "a"
  +     * </pre>
        * 
        * @param array  the array of values to concatenate, may be null
        * @return the concatenated String, <code>null</code> if null array input
  @@ -1778,6 +1789,17 @@
        * containing the provided list of elements.</p>
        *
        * <p>No delimiter is added before or after the list.
  +     * Null objects or empty strings within the array are represented by 
  +     * empty strings.</p>
  +     *
  +     * <pre>
  +     * StringUtils.join(null, *)               = null
  +     * StringUtils.join([], *)                 = ""
  +     * StringUtils.join([null], *)             = ""
  +     * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
  +     * StringUtils.join(["a", "b", "c"], null) = "abc"
  +     * StringUtils.join([null, "", "a"], ';')  = ";;a"
  +     * </pre>
        *
        * @param array  the array of values to join together, may be null
        * @param separator  the separator character to use
  @@ -1807,7 +1829,19 @@
        * containing the provided list of elements.</p>
        *
        * <p>No delimiter is added before or after the list.
  -     * A <code>null</code> separator is the same as an empty String ("").</p>
  +     * A <code>null</code> separator is the same as an empty String (""). 
  +     * Null objects or empty strings within the array are represented by 
  +     * empty strings.</p>
  +     *
  +     * <pre>
  +     * StringUtils.join(null, *)                = null
  +     * StringUtils.join([], *)                  = ""
  +     * StringUtils.join([null], *)              = ""
  +     * StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
  +     * StringUtils.join(["a", "b", "c"], null)  = "abc"
  +     * StringUtils.join(["a", "b", "c"], "")    = "abc"
  +     * StringUtils.join([null, "", "a"], ',')   = ",,a"
  +     * </pre>
        *
        * @param array  the array of values to join together, may be null
        * @param separator  the separator character to use, null treated as ""
  @@ -1847,7 +1881,10 @@
        * <p>Joins the elements of the provided <code>Iterator</code> into
        * a single String containing the provided elements.</p>
        *
  -     * <p>No delimiter is added before or after the list.
  +     * <p>No delimiter is added before or after the list. Null objects or empty 
  +     * strings within the iteration are represented by empty strings.</p>
  +     *
  +     * <p>See the examples here: {@link #join(Object[],char)}. </p>
        *
        * @param iterator  the <code>Iterator</code> of values to join together,
may be null
        * @param separator  the separator character to use
  @@ -1877,6 +1914,8 @@
        * <p>No delimiter is added before or after the list.
        * A <code>null</code> separator is the same as an empty String ("").</p>
        *
  +     * <p>See the examples here: {@link #join(Object[],String)}. </p>
  +     *
        * @param iterator  the <code>Iterator</code> of values to join together,
may be null
        * @param separator  the separator character to use, null treated as ""
        * @return the joined String, <code>null</code> if null iterator input
  @@ -2063,7 +2102,7 @@
       }
   
       /**
  -     * <p>Overlay a part of a String with another String.</p>
  +     * <p>Overlays part of a String with another String.</p>
        *
        * <pre>
        * StringUtils.overlayString(null, *, *, *)           = null
  @@ -2101,7 +2140,7 @@
       //-----------------------------------------------------------------------
   
       /**
  -     * <p>Remove one newline from end of a String if it's there,
  +     * <p>Removes one newline from end of a String if it's there,
        * otherwise leave it alone.  A newline is &quot;<code>\n</code>&quot;,
        * &quot;<code>\r</code>&quot;, or &quot;<code>\r\n</code>&quot;.</p>
        *
  @@ -2109,6 +2148,20 @@
        * It now more closely matches Perl chomp.
        * For the previous behavior, use {@link #slice(String)}.</p>
        *
  +     * <pre>
  +     * StringUtils.chomp(null)          = null
  +     * StringUtils.chomp("")            = ""
  +     * StringUtils.chomp("abc \r")      = "abc "
  +     * StringUtils.chomp("abc\n")       = "abc"
  +     * StringUtils.chomp("abc\r\n")     = "abc"
  +     * StringUtils.chomp("abc\r\n\r\n") = "abc\r\n"
  +     * StringUtils.chomp("abc\n\r")     = "abc\n"
  +     * StringUtils.chomp("abc\n\rabc")  = "abc\n\rabc"
  +     * StringUtils.chomp("\r")          = ""
  +     * StringUtils.chomp("\n")          = ""
  +     * StringUtils.chomp("\r\n")        = ""
  +     * </pre>
  +     *
        * @param str  the String to chomp a newline from, may be null
        * @return String without newline, <code>null</code> if null String input
        */
  @@ -2142,12 +2195,26 @@
       }
   
       /**
  -     * <p>Remove <code>separator</code> from the end of
  +     * <p>Removes <code>separator</code> from the end of
        * <code>str</code> if it's there, otherwise leave it alone.</p>
        *
        * <p>NOTE: This method changed in version 2.0.
        * It now more closely matches Perl chomp.
  -     * For the previous behavior, use {@link #slice(String,String)}.</p>
  +     * For the previous behavior, use {@link #slice(String,String)}.
  +     * This method uses {@link String#endsWith(String)}.</p>
  +     *
  +     * <pre>
  +     * StringUtils.chomp(null, *)         = null
  +     * StringUtils.chomp("", *)           = ""
  +     * StringUtils.chomp("foobar", "bar") = "foo"
  +     * StringUtils.chomp("foobar", "baz") = "foobar"
  +     * StringUtils.chomp("foo", "foo")    = ""
  +     * StringUtils.chomp("foo ", "foo")   = "foo"
  +     * StringUtils.chomp(" foo", "foo")   = " "
  +     * StringUtils.chomp("foo", "foooo")  = "foo"
  +     * StringUtils.chomp("foo", "")       = "foo"
  +     * StringUtils.chomp("foo", null)     = "foo"
  +     * </pre>
        *
        * @param str  the String to chomp from, may be null
        * @param separator  separator String, may be null
  @@ -2271,6 +2338,20 @@
        * <p>If the String ends in <code>\r\n</code>, then remove both
        * of them.</p>
        *
  +     * <pre>
  +     * StringUtils.chop(null)          = null
  +     * StringUtils.chop("")            = ""
  +     * StringUtils.chop("abc \r")      = "abc "
  +     * StringUtils.chop("abc\n")       = "abc"
  +     * StringUtils.chop("abc\r\n")     = "abc"
  +     * StringUtils.chop("abc")         = "ab"
  +     * StringUtils.chop("abc\nabc")    = "abc\nab"
  +     * StringUtils.chop("a")           = ""
  +     * StringUtils.chop("\r")          = ""
  +     * StringUtils.chop("\n")          = ""
  +     * StringUtils.chop("\r\n")        = ""
  +     * </pre>
  +     *
        * @param str  the String to chop last character from, may be null
        * @return String without last character, <code>null</code> if null String
input
        */
  @@ -2294,7 +2375,7 @@
       }
   
       /**
  -     * <p>Remove <code>\n</code> from end of a String if it's there.
  +     * <p>Removes <code>\n</code> from end of a String if it's there.
        * If a <code>\r</code> precedes it, then remove that too.</p>
        *
        * @param str  the String to chop a newline from, must not be null
  @@ -2324,7 +2405,22 @@
       //-----------------------------------------------------------------------
   
       /**
  -     * <p>Remove the last newline, and everything after it from a String.</p>
  +     * <p>Removes the last newline, and everything after it from a String.</p>
  +     *
  +     * <p>A <code>null</code> string input will return <code>null</code>.
  +     * An empty ("") string input will return the empty string.</p>
  +     *
  +     * <pre>
  +     * StringUtils.slice(null)          = null
  +     * StringUtils.slice("")            = ""
  +     * StringUtils.slice("abc \n")      = "abc "
  +     * StringUtils.slice("abc\n")       = "abc"
  +     * StringUtils.slice("abc\r\n")     = "abc\r"
  +     * StringUtils.slice("abc")         = "abc"
  +     * StringUtils.slice("abc\nabc")    = "abc"
  +     * StringUtils.slice("abc\nabc\n")  = "abc\nabc"
  +     * StringUtils.slice("\n")          = ""
  +     * </pre>
        *
        * <p><em>(This method was formerly named chomp or chopNewline.)</em></p>
        *
  @@ -2336,8 +2432,25 @@
       }
   
       /**
  -     * <p>Find the last occurence of a separator String;
  -     * remove it and everything after it.</p>
  +     * <p>Finds the last occurence of a separator String,
  +     * returning everything before it. The separator is not returned.</p>
  +     *
  +     * <p>A <code>null</code> string input will return <code>null</code>.
  +     * An empty ("") string input will return the empty string.
  +     * An empty or <code>null</code> separator will return the input string.</p>
  +     *
  +     * <p>This method is the opposite of {@link #sliceRemainder(String, String)}.</p>
  +     * 
  +     * <pre>
  +     * StringUtils.slice(null, *)      = null
  +     * StringUtils.slice("", *)        = ""
  +     * StringUtils.slice("abcba", "b") = "abc"
  +     * StringUtils.slice("abc", "c")   = "ab"
  +     * StringUtils.slice("a", "a")     = ""
  +     * StringUtils.slice("a", "z")     = "a"
  +     * StringUtils.slice("a", null)    = "a"
  +     * StringUtils.slice("a", "")      = "a"
  +     * </pre>
        *
        * <p><em>(This method was formerly named chomp.)</em></p>
        *
  @@ -2358,8 +2471,26 @@
       }
   
       /**
  -     * <p>Find the last occurence of a separator String, and return
  -     * everything after it.</p>
  +     * <p>Finds the last occurence of a separator String,
  +     * returning everything after it.</p>
  +     *
  +     * <p>A <code>null</code> string input will return <code>null</code>.
  +     * An empty ("") string input will return the empty string.
  +     * An empty or <code>null</code> separator will return the empty string.</p>
  +     * 
  +     * <p>This method is the opposite of {@link #slice(String, String)}.</p>
  +     *
  +     * <pre>
  +     * StringUtils.sliceRemainder(null, *)         = null
  +     * StringUtils.sliceRemainder("", *)           = ""
  +     * StringUtils.sliceRemainder(*, "")           = ""
  +     * StringUtils.sliceRemainder(*, null)         = ""
  +     * StringUtils.sliceRemainder("abc", "a")      = "bc"
  +     * StringUtils.sliceRemainder("abcba", "b")    = "a"
  +     * StringUtils.sliceRemainder("abc", "c")      = ""
  +     * StringUtils.sliceRemainder("a", "a")        = ""
  +     * StringUtils.sliceRemainder("a", "z")        = ""
  +     * </pre>
        *
        * <p><em>(This method was formerly named getchomp. Also, now it does not
        * include the separator in the return value.)</em></p>
  @@ -2386,51 +2517,85 @@
       }
   
       /**
  -     * <p>Find the first occurence of a separator String, and return
  -     * everything after it.</p>
  +     * <p>Finds the first occurence of a separator String,
  +     * returning everything before it. The separator is not returned.</p>
        *
  -     * <p><em>(This method was formerly named prechomp.  Also, previously
  -     * it included the separator in the return value; now it does not.)</em></p>
  +     * <p>A <code>null</code> string input will return <code>null</code>.
  +     * An empty ("") string input will return the empty string.
  +     * An empty or <code>null</code> separator will return the input string.</p>
  +     * 
  +     * <p>This method is the opposite of {@link #sliceFirst(String, String)}.</p>
  +     *
  +     * <pre>
  +     * StringUtils.sliceFirst(null, *)         = null
  +     * StringUtils.sliceFirst("", *)           = ""
  +     * StringUtils.sliceFirst("abc", "a")      = ""
  +     * StringUtils.sliceFirst("abcba", "b")    = "a"
  +     * StringUtils.sliceFirst("abc", "c")      = "ab"
  +     * StringUtils.sliceFirst("abc", "d")      = ""
  +     * StringUtils.sliceFirst("abc", "")       = "abc"
  +     * StringUtils.sliceFirst("abc", null)     = "abc"
  +     * </pre>
  +     *
  +     * <p><em>(This method was formerly named getPrechomp.  Also, it used to
  +     * include the separator, but now it does not.)</em></p>
        *
        * @param str  the String to slice from, may be null
        * @param separator  the String to slice, may be null
  -     * @return String without sliced beginning, <code>null</code> if null String
input
  +     * @return sliced String, <code>null</code> if null String input
        */
  -    public static String sliceFirstRemainder(String str, String separator) {
  -        if (str == null || str.length() == 0) {
  +    public static String sliceFirst(String str, String separator) {
  +        if (str == null || separator == null || str.length() == 0 || separator.length()
== 0) {
               return str;
           }
  -        if (separator == null || separator.length() == 0) {
  -            return "";
  -        }
           int idx = str.indexOf(separator);
           if (idx != -1) {
  -            return str.substring(idx + separator.length());
  +            return str.substring(0, idx);
           } else {
  -            return str;
  +            return "";
           }
       }
   
       /**
  -     * <p>Find the first occurence of a separator String;
  -     * return everything before it (but not including the separator).</p>
  +     * <p>Finds the first occurence of a separator String,
  +     * returning everything after it.</p>
        *
  -     * <p><em>(This method was formerly named getPrechomp.  Also, it used to
  -     * include the separator, but now it does not.)</em></p>
  +     * <p>A <code>null</code> string input will return <code>null</code>.
  +     * An empty ("") string input will return the empty string.
  +     * An empty or <code>null</code> separator will return the empty string.</p>
  +     * 
  +     * <p>This method is the opposite of {@link #sliceFirst(String, String)}.</p>
  +     *
  +     * <pre>
  +     * StringUtils.sliceFirstRemainder(null, *)         = null
  +     * StringUtils.sliceFirstRemainder("", *)           = ""
  +     * StringUtils.sliceFirstRemainder(*, "")           = ""
  +     * StringUtils.sliceFirstRemainder(*, null)         = ""
  +     * StringUtils.sliceFirstRemainder("abc", "a")      = "bc"
  +     * StringUtils.sliceFirstRemainder("abcba", "b")    = "cba"
  +     * StringUtils.sliceFirstRemainder("abc", "c")      = ""
  +     * StringUtils.sliceFirstRemainder("abc", "d")      = "abc"
  +     * </pre>
  +     *
  +     * <p><em>(This method was formerly named prechomp.  Also, previously
  +     * it included the separator in the return value; now it does not.)</em></p>
        *
        * @param str  the String to slice from, may be null
        * @param separator  the String to slice, may be null
  -     * @return sliced String, <code>null</code> if null String input
  +     * @return String without sliced beginning, <code>null</code> if null String
input
        */
  -    public static String sliceFirst(String str, String separator) {
  -        if (str == null || separator == null || str.length() == 0 || separator.length()
== 0) {
  +    public static String sliceFirstRemainder(String str, String separator) {
  +        if (str == null || str.length() == 0) {
               return str;
           }
  +        if (separator == null || separator.length() == 0) {
  +            return "";
  +        }
           int idx = str.indexOf(separator);
           if (idx != -1) {
  -            return str.substring(0, idx);
  +            return str.substring(idx + separator.length());
           } else {
  -            return "";
  +            return str;
           }
       }
   
  @@ -3182,9 +3347,9 @@
       //-----------------------------------------------------------------------
       
       /**
  -     * <p>How many times is the substring in the larger String.</p>
  +     * <p>Counts how many times the substring appears in the larger String.</p>
        *
  -     * <p>A <code>null</code> String input returns <code>0</code>.</p>
  +     * <p>A <code>null</code> or empty ("") String input returns <code>0</code>.</p>
        * 
        * <pre>
        * StringUtils.countMatches(null, *)       = 0
  @@ -3496,7 +3661,7 @@
       //-----------------------------------------------------------------------
   
       /**
  -     * <p>Reverse a String as per {@link StringBuffer#reverse()}.</p>
  +     * <p>Reverses a String as per {@link StringBuffer#reverse()}.</p>
        *
        * <p><A code>null</code> String returns <code>null</code>.</p>
        * 
  @@ -3585,20 +3750,31 @@
       //-----------------------------------------------------------------------
   
       /**
  -     * <p>Turn "Now is the time for all good men" into "Now is the time for..."</p>
  +     * <p>Abbreviates a String using ellipses. This will turn 
  +     * "Now is the time for all good men" into "Now is the time for..."</p>
        *
        * <p>Specifically:
        * <ul>
        *   <li>If <code>str</code> is less than <code>maxWidth</code>
characters
        *       long, return it.</li>
        *   <li>Else abbreviate it to <code>(substring(str, 0, max-3) + "...")</code>.</li>
  -     *   <li>If <code>maxWidth</code> is less than </code>3, throw
an
  +     *   <li>If <code>maxWidth</code> is less than <code>4</code>,
throw an
        *       <code>IllegalArgumentException</code>.</li>
        *   <li>In no case will it return a String of length greater than
        *       <code>maxWidth</code>.</li>
        * </ul>
        * </p>
        *
  +     * <pre>
  +     * StringUtils.abbreviate(null, *)      = null
  +     * StringUtils.abbreviate("", 4)        = ""
  +     * StringUtils.abbreviate("abcdefg", 6) = "abc..."
  +     * StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
  +     * StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
  +     * StringUtils.abbreviate("abcdefg", 4) = "a..."
  +     * StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
  +     * </pre>
  +     *
        * @param str  the String to check, may be null
        * @param maxWidth  maximum length of result String, must be at least 4
        * @return abbreviated String, <code>null</code> if null String input
  @@ -3609,7 +3785,8 @@
       }
   
       /**
  -     * <p>Turn "Now is the time for all good men" into "...is the time for..."</p>
  +     * <p>Abbreviates a String using ellipses. This will turn 
  +     * "Now is the time for all good men" into "...is the time for..."</p>
        *
        * <p>Works like <code>abbreviate(String, int)</code>, but allows
you to specify
        * a "left edge" offset.  Note that this left edge is not necessarily going to
  @@ -3619,6 +3796,22 @@
        * <p>In no case will it return a String of length greater than
        * <code>maxWidth</code>.</p>
        *
  +     * <pre>
  +     * StringUtils.abbreviate(null, *, *)                = null
  +     * StringUtils.abbreviate("", 0, 4)                  = ""
  +     * StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
  +     * StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
  +     * StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
  +     * StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
  +     * StringUtils.abbreviate("abcdefghij", 0, 3)        = IllegalArgumentException
  +     * StringUtils.abbreviate("abcdefghij", 5, 6)        = IllegalArgumentException
  +     * </pre>
  +     *
        * @param str  the String to check, may be null
        * @param offset  left edge of source String
        * @param maxWidth  maximum length of result String, must be at least 4
  @@ -3657,7 +3850,7 @@
       //-----------------------------------------------------------------------
   
       /**
  -     * <p>Compare two Strings, and return the portion where they differ.
  +     * <p>Compares two Strings, and returns the portion where they differ.
        * (More precisely, return the remainder of the second String,
        * starting from where it's different from the first.)</p>
        *
  @@ -3695,7 +3888,7 @@
       }
   
       /**
  -     * <p>Compare two Strings, and return the index at which the
  +     * <p>Compares two Strings, and returns the index at which the
        * Strings begin to differ.</p>
        * 
        * <p>For example, 
  @@ -3743,10 +3936,25 @@
        * <p>Find the Levenshtein distance between two Strings.</p>
        *
        * <p>This is the number of changes needed to change one String into
  -     * another. Where each change is a single character modification.</p>
  +     * another, where each change is a single character modification (deletion, 
  +     * insertion or substitution).</p>
        *
  -     * <p>This implemmentation of the levenshtein distance algorithm
  +     * <p>This implementation of the Levenshtein distance algorithm
        * is from <a href="http://www.merriampark.com/ld.htm">http://www.merriampark.com/ld.htm</a></p>
  +     *
  +     * <pre>
  +     * StringUtils.getLevenshteinDistance(null, *)             = IllegalArgumentException
  +     * StringUtils.getLevenshteinDistance(*, null)             = IllegalArgumentException
  +     * StringUtils.getLevenshteinDistance("","")               = 0
  +     * StringUtils.getLevenshteinDistance("","a")              = 1
  +     * StringUtils.getLevenshteinDistance("aaapppp", "")       = 7
  +     * StringUtils.getLevenshteinDistance("frog", "fog")       = 1
  +     * StringUtils.getLevenshteinDistance("fly", "ant")        = 3
  +     * StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
  +     * StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
  +     * StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
  +     * StringUtils.getLevenshteinDistance("hello", "hallo")    = 1
  +     * </pre>
        * 
        * @param s  the first String, must not be null
        * @param t  the second String, must not be null
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message