8065554: MatchResult should provide values of named-capturing groups

Reviewed-by: smarks

Author: rgiulietti

src/java.base/share/classes/java/util/regex/MatchResult.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,6 +25,9 @@
 
 package java.util.regex;
 
+import java.util.Map;
+import java.util.Objects;
+
 /**
  * The result of a match operation.
  *
@@ -33,6 +36,15 @@
  * groups and group boundaries can be seen but not modified through
  * a {@code MatchResult}.
  *
+ * @implNote
+ * Support for named groups is implemented by the default methods
+ * {@link #start(String)}, {@link #end(String)} and {@link #group(String)}.
+ * They all make use of the map returned by {@link #namedGroups()}, whose
+ * default implementation simply throws {@link UnsupportedOperationException}.
+ * It is thus sufficient to override {@link #namedGroups()} for these methods
+ * to work. However, overriding them directly might be preferable for
+ * performance or other reasons.
+ *
  * @author  Michael McCloskey
  * @see Matcher
  * @since 1.5
@@ -48,7 +60,7 @@ public interface MatchResult {
      *          If no match has yet been attempted,
      *          or if the previous match operation failed
      */
-    public int start();
+    int start();
 
     /**
      * Returns the start index of the subsequence captured by the given group
@@ -74,7 +86,38 @@ public interface MatchResult {
      *          If there is no capturing group in the pattern
      *          with the given index
      */
-    public int start(int group);
+    int start(int group);
+
+    /**
+     * Returns the start index of the subsequence captured by the given
+     * <a href="Pattern.html#groupname">named-capturing group</a> during the
+     * previous match operation.
+     *
+     * @param  name
+     *         The name of a named-capturing group in this matcher's pattern
+     *
+     * @return  The index of the first character captured by the group,
+     *          or {@code -1} if the match was successful but the group
+     *          itself did not match anything
+     *
+     * @throws  IllegalStateException
+     *          If no match has yet been attempted,
+     *          or if the previous match operation failed
+     *
+     * @throws  IllegalArgumentException
+     *          If there is no capturing group in the pattern
+     *          with the given name
+     *
+     * @implSpec
+     * The default implementation of this method invokes {@link #namedGroups()}
+     * to obtain the group number from the {@code name} argument, and uses it
+     * as argument to an invocation of {@link #start(int)}.
+     *
+     * @since 20
+     */
+    default int start(String name) {
+        return start(groupNumber(name));
+    }
 
     /**
      * Returns the offset after the last character matched.
@@ -85,7 +128,7 @@ public interface MatchResult {
      *          If no match has yet been attempted,
      *          or if the previous match operation failed
      */
-    public int end();
+    int end();
 
     /**
      * Returns the offset after the last character of the subsequence
@@ -111,7 +154,38 @@ public interface MatchResult {
      *          If there is no capturing group in the pattern
      *          with the given index
      */
-    public int end(int group);
+    int end(int group);
+
+    /**
+     * Returns the offset after the last character of the subsequence
+     * captured by the given <a href="Pattern.html#groupname">named-capturing
+     * group</a> during the previous match operation.
+     *
+     * @param  name
+     *         The name of a named-capturing group in this matcher's pattern
+     *
+     * @return  The offset after the last character captured by the group,
+     *          or {@code -1} if the match was successful
+     *          but the group itself did not match anything
+     *
+     * @throws  IllegalStateException
+     *          If no match has yet been attempted,
+     *          or if the previous match operation failed
+     *
+     * @throws  IllegalArgumentException
+     *          If there is no capturing group in the pattern
+     *          with the given name
+     *
+     * @implSpec
+     * The default implementation of this method invokes {@link #namedGroups()}
+     * to obtain the group number from the {@code name} argument, and uses it
+     * as argument to an invocation of {@link #end(int)}.
+     *
+     * @since 20
+     */
+    default int end(String name) {
+        return end(groupNumber(name));
+    }
 
     /**
      * Returns the input subsequence matched by the previous match.
@@ -132,7 +206,7 @@ public interface MatchResult {
      *          If no match has yet been attempted,
      *          or if the previous match operation failed
      */
-    public String group();
+    String group();
 
     /**
      * Returns the input subsequence captured by the given group during the
@@ -170,7 +244,44 @@ public interface MatchResult {
      *          If there is no capturing group in the pattern
      *          with the given index
      */
-    public String group(int group);
+    String group(int group);
+
+    /**
+     * Returns the input subsequence captured by the given
+     * <a href="Pattern.html#groupname">named-capturing group</a> during the
+     * previous match operation.
+     *
+     * <p> If the match was successful but the group specified failed to match
+     * any part of the input sequence, then {@code null} is returned. Note
+     * that some groups, for example {@code (a*)}, match the empty string.
+     * This method will return the empty string when such a group successfully
+     * matches the empty string in the input.  </p>
+     *
+     * @param  name
+     *         The name of a named-capturing group in this matcher's pattern
+     *
+     * @return  The (possibly empty) subsequence captured by the named group
+     *          during the previous match, or {@code null} if the group
+     *          failed to match part of the input
+     *
+     * @throws  IllegalStateException
+     *          If no match has yet been attempted,
+     *          or if the previous match operation failed
+     *
+     * @throws  IllegalArgumentException
+     *          If there is no capturing group in the pattern
+     *          with the given name
+     *
+     * @implSpec
+     * The default implementation of this method invokes {@link #namedGroups()}
+     * to obtain the group number from the {@code name} argument, and uses it
+     * as argument to an invocation of {@link #group(int)}.
+     *
+     * @since 20
+     */
+    default String group(String name) {
+        return group(groupNumber(name));
+    }
 
     /**
      * Returns the number of capturing groups in this match result's pattern.
@@ -184,6 +295,55 @@ public interface MatchResult {
      *
      * @return The number of capturing groups in this matcher's pattern
      */
-    public int groupCount();
+    int groupCount();
+
+    /**
+     * Returns an unmodifiable map from capturing group names to group numbers.
+     * If there are no named groups, returns an empty map.
+     *
+     * @return an unmodifiable map from capturing group names to group numbers
+     *
+     * @throws UnsupportedOperationException if the implementation does not
+     *          support named groups.
+     *
+     * @implSpec The default implementation of this method always throws
+     *          {@link UnsupportedOperationException}
+     *
+     * @apiNote
+     * This method must be overridden by an implementation that supports
+     * named groups.
+     *
+     * @since 20
+     */
+    default Map<String,Integer> namedGroups() {
+        throw new UnsupportedOperationException("namedGroups()");
+    }
+
+    private int groupNumber(String name) {
+        Objects.requireNonNull(name, "Group name");
+        Integer number = namedGroups().get(name);
+        if (number != null) {
+            return number;
+        }
+        throw new IllegalArgumentException("No group with name <" + name + ">");
+    }
+
+    /**
+     * Returns whether {@code this} contains a valid match from
+     * a previous match or find operation.
+     *
+     * @return whether {@code this} contains a valid match
+     *
+     * @throws UnsupportedOperationException if the implementation cannot report
+     *          whether it has a match
+     *
+     * @implSpec The default implementation of this method always throws
+     *          {@link UnsupportedOperationException}
+     *
+     * @since 20
+     */
+    default boolean hasMatch() {
+        throw new UnsupportedOperationException("hasMatch()");
+    }
 
 }