Summary

Update documentation on comments mode in java.util.regex.Pattern to clarify whitespace behavior inside character classes.

Problem

The regex pattern spec states that whitespace is ignored in comments mode but needs specific emphasis that this includes syntactic constructs like character classes. Other existing regular expression systems (Perl) have diverging behavior from Java in this case.

Solution

Adding a note in the comments mode section calling out this specific behavior as it relates to character classes. Adding another note about the difference versus Perl 5 in the notable differences section of Pattern.

Specification

New language appended to the first paragraph of the documentation for the COMMENTS field in Pattern:

In this mode, whitespace is ignored, and embedded comments starting with {@code #} are ignored until the end of a line. Comments mode ignores whitespace within a character class contained in a pattern string. Such whitespace must be escaped in order to be considered significant.

New note appended to the notable differences from Perl section:

In Perl, free-spacing mode (which is called comments mode in this class) denoted by {@code (?x)} in the regular expression (or by the {@link Pattern#COMMENTS} flag when compiling the expression) will not ignore whitespace inside of character classes. In this class, whitespace inside of character classes must be escaped to be considered as part of the regular expression when in comments mode.