Summary

We need to update the specification for java.util.regex.Matcher so that group() to account for an undocumented null that is returned if the matcher has been given a new pattern with usePattern() and has yet to attempt a match with the new pattern.

Problem

Behavior has been reported in the wild that when calling Matcher.group() after re-assigning the matcher's Pattern with usePattern() returns a null value. This behavior isn't in the specification for Matcher.group().

Solution

The null return value is observed when a state bit for a given group is -1. This value is only set in the group state array after usePattern() is invoked on a Matcher. The group(int) method already returns null under certain cases, so the behavior isn't new to this API. The solution is to update the spec to document this behavior.

Specification

The documentation for the return value of Matcher.group() will be appended with:

... or {@code null} if a matcher with a previous
match has changed its {@link java.util.regex.Pattern},
but no new match has yet been attempted

The documentation for the return value of Matcher.group(int) will be appended with:

... or if the matcher's
{@link java.util.regex.Pattern} has changed after a
successful match, but a new match has not been attempted