adding new function apoc.test.regexGroups (#254)

* new function apoc.test.regexGroups

* regenerated index.html

* deal gracefully with null values

Author: sarmbruster

docs/index.html

@@ -2373,6 +2373,10 @@ <h4 id="_text_functions">Text Functions</h4>
 <td class="tableblock halign-left valign-top"><p class="tableblock">replace each substring of the given string that matches the given regular expression with the given replacement.</p></td>
 </tr>
 <tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>apoc.text.regexGroups(text, regex)</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">returns an array containing a nested array for each match. The inner array contains all match groups.</p></td>
+</tr>
+<tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>apoc.text.join(['text1','text2',&#8230;&#8203;], delimiter)</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">join the given strings with the given delimiter.</p></td>
 </tr>
@@ -6057,4 +6061,4 @@ <h4 id="_further_functions">Further Functions</h4>
 </div>
 </div>
 </body>
-</html>
+</html>

docs/overview.adoc

@@ -718,6 +718,7 @@ Sometimes type information gets lost, these functions help you to coerce an "Any
 [cols="1m,5"]
 |===
 | apoc.text.replace(text, regex, replacement)| replace each substring of the given string that matches the given regular expression with the given replacement.
+| apoc.text.regexGroups(text, regex) | returns an array containing a nested array for each match. The inner array contains all match groups.
 | apoc.text.join(['text1','text2',...], delimiter) | join the given strings with the given delimiter.
 | apoc.text.format(text,[params]) | sprintf format the string with the params given
 | apoc.text.lpad(text,count,delim) | left pad the string to the given width

docs/text.adoc

@@ -12,6 +12,14 @@ Cleaning will strip the string of all non-alphanumeric characters (including spa
 CALL apoc.text.replace('Hello World!', '[^a-zA-Z]', '')
 ----
 
+[source,cypher]
+----
+RETURN apoc.text.regexGroups('abc <link xxx1>yyy1</link> def <link xxx2>yyy2</link>','<link (\\w+)>(\\w+)</link>') AS result
+result> [["<link xxx1>yyy1</link>", "xxx1", "yyy1"], ["<link xxx2>yyy2</link>", "xxx2", "yyy2"]]
+----
+
+
+
 .will return 'Hello World'
 [source,cypher]
 ----

src/main/java/apoc/text/Strings.java

@@ -1,8 +1,6 @@
 package apoc.text;
 
 import org.neo4j.procedure.Description;
-import apoc.result.BooleanResult;
-import apoc.result.Empty;
 import apoc.result.StringResult;
 import org.neo4j.procedure.Name;
 import org.neo4j.procedure.Procedure;
@@ -12,10 +10,8 @@
 import java.net.URLDecoder;
 import java.net.URLEncoder;
 import java.text.Normalizer;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.List;
-import java.util.Locale;
+import java.util.*;
+import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
@@ -39,6 +35,28 @@ public String regreplace(final @Name("text") String text, final @Name("regex") S
         return text.replaceAll(regex, replacement);
     }
 
+    @UserFunction
+    @Description("apoc.text.regexGroups(text, regex) - return all matching groups of the regex on the given text.")
+    public List<List<String>> regexGroups(final @Name("text") String text, final @Name("regex") String regex) {
+        if (text==null || regex==null) {
+            return Collections.EMPTY_LIST;
+        } else {
+            final Pattern pattern = Pattern.compile(regex);
+            final Matcher matcher = pattern.matcher(text);
+
+            List<List<String>> result = new ArrayList<>();
+            while (matcher.find()) {
+                List<String> matchResult = new ArrayList<>();
+                for (int i=0;i<=matcher.groupCount(); i++) {
+                    matchResult.add(matcher.group(i));
+                }
+                result.add(matchResult);
+            }
+            return result;
+        }
+    }
+
+
     @UserFunction
     @Description("apoc.text.join(['text1','text2',...], delimiter) - join the given strings with the given delimiter.")
     public String join(

src/test/java/apoc/text/StringsTest.java

@@ -5,14 +5,16 @@
 import org.junit.rules.ExpectedException;
 import org.neo4j.graphdb.GraphDatabaseService;
 import org.neo4j.graphdb.QueryExecutionException;
+import org.neo4j.helpers.collection.Iterators;
 import org.neo4j.test.TestGraphDatabaseFactory;
 
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 
 import static apoc.util.MapUtil.map;
 import static apoc.util.TestUtil.testCall;
-import static java.util.Arrays.asList;
+import static apoc.util.TestUtil.testResult;
 import static org.junit.Assert.*;
 
 /**
@@ -224,4 +226,25 @@ public void testFormat() {
         testCall(db, "CALL apoc.text.format('ab%s %d %.1f %s%n',['cd',42,3.14,true]) YIELD value RETURN value", row -> assertEquals("abcd 42 3.1 true\n", row.get("value")));
     }
 
+    @Test
+    public void testRegexGroups() {
+        testResult(db, "RETURN apoc.text.regexGroups('abc <link xxx1>yyy1</link> def <link xxx2>yyy2</link>','<link (\\\\w+)>(\\\\w+)</link>') AS result",
+                result -> {
+                    final List<Object> r = Iterators.single(result.columnAs("result"));
+
+                    List<List<String>> expected = new ArrayList<>(Arrays.asList(
+                            new ArrayList<String>(Arrays.asList("<link xxx1>yyy1</link>", "xxx1", "yyy1")),
+                            new ArrayList<String>(Arrays.asList("<link xxx2>yyy2</link>", "xxx2", "yyy2"))
+                    ));
+                    assertTrue(r.containsAll(expected));
+                });
+    }
+
+    @Test
+    public void testRegexGroupsForNPE() {
+        // throws no exception
+        testCall(db, "RETURN apoc.text.regexGroups(null,'<link (\\\\w+)>(\\\\w+)</link>') AS result", row -> { });
+        testCall(db, "RETURN apoc.text.regexGroups('abc',null) AS result", row -> { });
+    }
+
 }