LANG-275 - StringUtils substringsBetween, implemented by Dave Meikle

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@492377 13f79535-47bb-0310-9956-ffa450edef68

RELEASE-NOTES.txt

@@ -82,4 +82,5 @@ IMPROVEMENTS IN 2.3:
     * [LANG-266] - Wish for StringUtils.join(Collection, *)
     * [LANG-310] - BooleanUtils isNotTrue/isNotFalse
     * [LANG-306] - StrBuilder appendln/appendAll/appendSeparator
+    * [LANG-275] - StringUtils substringsBetween
 

project.xml

@@ -270,6 +270,9 @@ limitations under the License.
         <contributor>
             <name>Rand McNeely</name>
         </contributor>
+        <contributor>
+            <name>Dave Meikle</name>
+        </contributor>
         <contributor>
             <name>Nikolay Metchev</name>
         </contributor>

src/java/org/apache/commons/lang/StringUtils.java

@@ -1859,14 +1859,16 @@ public class StringUtils {
      *
      * <p>A <code>null</code> input String returns <code>null</code>.
      * A <code>null</code> open/close returns <code>null</code> (no match).
-     * An empty ("") open/close returns an empty string.</p>
+     * An empty ("") open and close returns an empty string.</p>
      *
      * <pre>
+     * StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
      * StringUtils.substringBetween(null, *, *)          = null
+     * StringUtils.substringBetween(*, null, *)          = null
+     * StringUtils.substringBetween(*, *, null)          = null
      * StringUtils.substringBetween("", "", "")          = ""
-     * StringUtils.substringBetween("", "", "tag")       = null
+     * StringUtils.substringBetween("", "", "]")         = null
-     * StringUtils.substringBetween("", "tag", "tag")    = null
+     * StringUtils.substringBetween("", "[", "]")        = null
-     * StringUtils.substringBetween("yabcz", null, null) = null
      * StringUtils.substringBetween("yabcz", "", "")     = ""
      * StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
      * StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"
@@ -1892,6 +1894,60 @@ public class StringUtils {
         return null;
     }
 
+    /**
+     * <p>Searches a String for substrings delimited by a start and end tag,
+     * returning all matching substrings in an array.</p>
+     *
+     * <p>A <code>null</code> input String returns <code>null</code>.
+     * A <code>null</code> open/close returns <code>null</code> (no match).
+     * An empty ("") open/close returns <code>null</code> (no match).</p>
+     *
+     * <pre>
+     * StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
+     * StringUtils.substringsBetween(null, *, *)            = null
+     * StringUtils.substringsBetween(*, null, *)            = null
+     * StringUtils.substringsBetween(*, *, null)            = null
+     * StringUtils.substringsBetween("", "[", "]")          = []
+     * </pre>
+     *
+     * @param str  the String containing the substrings, null returns null, empty returns empty
+     * @param open  the String identifying the start of the substring, empty returns null
+     * @param close  the String identifying the end of the substring, empty returns null
+     * @return a String Array of substrings, or <code>null</code> if no match
+     * @since 2.3
+     */
+    public static String[] substringsBetween(String str, String open, String close) {
+        if (str == null || isEmpty(open) || isEmpty(close)) {
+            return null;
+        }
+        int strLen = str.length();
+        if (strLen == 0) {
+            return ArrayUtils.EMPTY_STRING_ARRAY;
+        }
+        int closeLen = close.length();
+        int openLen = open.length();
+        List list = new ArrayList();
+        int pos = 0;
+        while (pos < (strLen - closeLen)) {
+            int start = str.indexOf(open, pos);
+            if (start < 0) {
+                break;
+            }
+            start += openLen;
+            int end = str.indexOf(close, start);
+            if (end < 0) {
+                break;
+            }
+            list.add(str.substring(start, end));
+            pos = end + closeLen;
+        }
+        if (list.size() > 0) {
+            return (String[]) list.toArray(new String [list.size()]);
+        } else {
+            return null;
+        }
+    }
+
     // Nested extraction
     //-----------------------------------------------------------------------
     /**

src/test/org/apache/commons/lang/StringUtilsSubstringTest.java

@@ -248,10 +248,73 @@ public class StringUtilsSubstringTest extends TestCase {
     public void testSubstringBetween_StringStringString() {
         assertEquals(null, StringUtils.substringBetween(null, "", ""));
         assertEquals("", StringUtils.substringBetween("", "", ""));
+        assertEquals("", StringUtils.substringBetween("foo", "", ""));
+        assertEquals(null, StringUtils.substringBetween("foo", "", "]"));
+        assertEquals(null, StringUtils.substringBetween("foo", "[", "]"));
         assertEquals("", StringUtils.substringBetween("    ", " ", "  "));
         assertEquals("bar", StringUtils.substringBetween("<foo>bar</foo>", "<foo>", "</foo>") );
     }
 
+   /**
+     * Tests the substringsBetween method that returns an String Array of substrings.
+     */
+    public void testSubstringsBetween_StringStringString() {
+
+        String[] results = StringUtils.substringsBetween("[one], [two], [three]", "[", "]");
+        assertEquals(3, results.length);
+        assertEquals("one", results[0]);
+        assertEquals("two", results[1]);
+        assertEquals("three", results[2]);
+
+        results = StringUtils.substringsBetween("[one], [two], three", "[", "]");
+        assertEquals(2, results.length);
+        assertEquals("one", results[0]);
+        assertEquals("two", results[1]);
+
+        results = StringUtils.substringsBetween("[one], [two], three]", "[", "]");
+        assertEquals(2, results.length);
+        assertEquals("one", results[0]);
+        assertEquals("two", results[1]);
+
+        results = StringUtils.substringsBetween("[one], two], three]", "[", "]");
+        assertEquals(1, results.length);
+        assertEquals("one", results[0]);
+
+        results = StringUtils.substringsBetween("one], two], [three]", "[", "]");
+        assertEquals(1, results.length);
+        assertEquals("three", results[0]);
+
+        // 'ab hello ba' will match, but 'ab non ba' won't
+        // this is because the 'a' is shared between the two and can't be matched twice
+        results = StringUtils.substringsBetween("aabhellobabnonba", "ab", "ba");
+        assertEquals(1, results.length);
+        assertEquals("hello", results[0]);
+
+        results = StringUtils.substringsBetween("one, two, three", "[", "]");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("[one, two, three", "[", "]");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("one, two, three]", "[", "]");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("[one], [two], [three]", "[", null);
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("[one], [two], [three]", null, "]");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("[one], [two], [three]", "", "");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween(null, "[", "]");
+        assertNull(results);
+
+        results = StringUtils.substringsBetween("", "[", "]");
+        assertEquals(0, results.length);
+    }
+
     //-----------------------------------------------------------------------
     public void testCountMatches_String() {
         assertEquals(0, StringUtils.countMatches(null, null));