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: [EMAIL PROTECTED] #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: [EMAIL PROTECTED] #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 "<code>\n</code>",
* "<code>\r</code>", or "<code>\r\n</code>".</p>
*
@@ -2109,6 +2148,20 @@
* It now more closely matches Perl chomp.
* For the previous behavior, use [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #slice(String,String)}.</p>
+ * For the previous behavior, use [EMAIL PROTECTED] #slice(String,String)}.
+ * This method uses [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] StringBuffer#reverse()}.</p>
+ * <p>Reverses a String as per [EMAIL PROTECTED] 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
