diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 9616d6e3e..ef3839f45 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -22,6 +22,7 @@ + CharSet.getInstance documentation does not clearly explain how to include negation character in set Change nullToEmpty methods to generics Fix FindBugs warnings in DurationFormatUtils Add a method to ArrayUtils for removing all occurrences of a given element diff --git a/src/main/java/org/apache/commons/lang3/CharSet.java b/src/main/java/org/apache/commons/lang3/CharSet.java index 82f0b9a8c..5adae758f 100644 --- a/src/main/java/org/apache/commons/lang3/CharSet.java +++ b/src/main/java/org/apache/commons/lang3/CharSet.java @@ -115,6 +115,7 @@ public class CharSet implements Serializable { *
  • Negated single character, such as "^a" *
  • Ordinary single character, such as "a" * + * *

    Matching works left to right. Once a match is found the * search starts again from the next character.

    * @@ -128,7 +129,24 @@ public class CharSet implements Serializable { * as the "a-e" and "e-a" are the same.

    * *

    The set of characters represented is the union of the specified ranges.

    + * + *

    There are two ways to add a literal negation character ({@code ^}):

    + * * + *

    Examples using the negation character:

    + * 
    +     *     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
+     *
    + * *

    All CharSet objects returned by this method will be immutable.

    * * @param setStrs Strings to merge into the set, may be null diff --git a/src/test/java/org/apache/commons/lang3/CharSetTest.java b/src/test/java/org/apache/commons/lang3/CharSetTest.java index 014d7b765..d335245c7 100644 --- a/src/test/java/org/apache/commons/lang3/CharSetTest.java +++ b/src/test/java/org/apache/commons/lang3/CharSetTest.java @@ -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('^')); + } }