Author: djones
Date: Sat Apr 11 06:02:34 2015
New Revision: 1672833
URL: http://svn.apache.org/r1672833
Log:
Update for LANG-1069: CharSet.getInstance documentation does not clearly
explain how to include negation character in set. Javadoc expanded and unit
tests added to match examples. Based on patch by Arno Noordover.
Modified:
commons/proper/lang/trunk/src/changes/changes.xml
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/CharSet.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/CharSetTest.java
Modified: commons/proper/lang/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/changes/changes.xml?rev=1672833&r1=1672832&r2=1672833&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/changes/changes.xml [utf-8] (original)
+++ commons/proper/lang/trunk/src/changes/changes.xml [utf-8] Sat Apr 11
06:02:34 2015
@@ -22,6 +22,7 @@
<body>
<release version="3.5" date="tba" description="tba">
+ <action issue="LANG-1069" type="update" dev="djones" due-to="Arno
Noordover">CharSet.getInstance documentation does not clearly explain how to
include negation character in set</action>
<action issue="LANG-1050" type="add" dev="djones" due-to="James
Sawle">Change nullToEmpty methods to generics</action>
<action issue="LANG-1111" type="fix" dev="chas">Fix FindBugs warnings in
DurationFormatUtils</action>
<action issue="LANG-1074" type="add" dev="djones" due-to="Haiyang Li">Add
a method to ArrayUtils for removing all occurrences of a given element</action>
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/CharSet.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/CharSet.java?rev=1672833&r1=1672832&r2=1672833&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/CharSet.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/CharSet.java
Sat Apr 11 06:02:34 2015
@@ -115,6 +115,7 @@ public class CharSet implements Serializ
* <li>Negated single character, such as "^a"
* <li>Ordinary single character, such as "a"
* </ol>
+ *
* <p>Matching works left to right. Once a match is found the
* search starts again from the next character.</p>
*
@@ -128,7 +129,24 @@ public class CharSet implements Serializ
* as the "a-e" and "e-a" are the same.</p>
*
* <p>The set of characters represented is the union of the specified
ranges.</p>
+ *
+ * <p>There are two ways to add a literal negation character ({@code
^}):</p>
+ * <ul>
+ * <li>As the last character in a string, e.g. {@code
CharSet.getInstance("a-z^")}</li>
+ * <li>As a separate element, e.g. {@code
CharSet.getInstance("^","a-z")}</li>
+ * </ul>
*
+ * <p>Examples using the negation character:</p>
+ * <pre>
+ * CharSet.getInstance("^a-c").contains('a') = false
+ * CharSet.getInstance("^a-c").contains('d') = true
+ * CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is
negated)
+ * CharSet.getInstance("^^a-c").contains('^') = false
+ * CharSet.getInstance("^a-cd-f").contains('d') = true
+ * CharSet.getInstance("a-c^").contains('^') = true
+ * CharSet.getInstance("^", "a-c").contains('^') = true
+ * </pre>
+ *
* <p>All CharSet objects returned by this method will be immutable.</p>
*
* @param setStrs Strings to merge into the set, may be null
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/CharSetTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/CharSetTest.java?rev=1672833&r1=1672832&r2=1672833&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/CharSetTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/CharSetTest.java
Sat Apr 11 06:02:34 2015
@@ -18,10 +18,7 @@
*/
package org.apache.commons.lang3;
-import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertFalse;
-import static org.junit.Assert.assertSame;
-import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.*;
import java.lang.reflect.Modifier;
@@ -466,4 +463,14 @@ public class CharSetTest {
assertTrue(ArrayUtils.contains(array, CharRange.isIn('0', '9')));
}
+ @Test
+ public void testJavadocExamples() throws Exception {
+ assertFalse(CharSet.getInstance("^a-c").contains('a'));
+ assertTrue(CharSet.getInstance("^a-c").contains('d'));
+ assertTrue(CharSet.getInstance("^^a-c").contains('a'));
+ assertFalse(CharSet.getInstance("^^a-c").contains('^'));
+ assertTrue(CharSet.getInstance("^a-cd-f").contains('d'));
+ assertTrue(CharSet.getInstance("a-c^").contains('^'));
+ assertTrue(CharSet.getInstance("^", "a-c").contains('^'));
+ }
}
