This class represents a regular expression. It has no public constructor: obtain a Pattern by calling one of the static compile( ) methods, passing the string representation of the regular expression, and an optional bitmask of flags that modify the behavior of the regex. pattern( ) and flags( ) return the string form of the regular expression and the bitmask that were passed to compile( ).

If you want to perform only a single match operation with a regular expression, and don't need to use any of the flags, you don't have to create a Pattern object: simply pass the string representation of the pattern and the CharSequence to be matched to the static matches( ) method: the method returns TRue if the specified pattern matches the complete specified text, or returns false otherwise.

Pattern represents a regular expression, but does not actually define any primitive methods for matching regular expressions to text. To do that, you must create a Matcher object that encapsulates a pattern and the text it is to be compared with. Do this by calling the matcher( ) method and specifying the CharSequence you want to match against. See Matcher for a description of what you can do with it.

The split( ) methods are the exception to the rule that you must obtain a Matcher in order to be able to do anything with a Pattern (although they create and use a Matcher internally). They take a CharSequence as input, and split it into substrings, using text that matches the regular expression as the delimiter, returning the substrings as a String[ ]. The two-argument version of split( ) takes an integer argument that specifies the maximum number of substrings to break the input into.

Pattern defines the following flags that control various aspects of how regular expression matching is performed. The flags are the following:

CANON_EQ

The Unicode standard sometimes allows more than one way to specify the same character. If this flag is set, characters are compared by comparing their full canonical decompositions, so that characters will match even if expressed in different ways. Enabling this flag typically slows down performance. Unlike all the other flags, there is no way to temporarily enable this flag within a pattern.

CASE_INSENSITIVE

Match letters without regard to case. By default this flag only affects the comparisons of ASCII letters. Also set the UNICODE_CASE flag if you want to ignore the case of all Unicode characters. You can enable this flag within a pattern with (?i).

COMMENTS

If this flag is set, then whitespace and comments within a pattern are ignored. Comments are all characters between a # and end of line. You can enable this flag within a pattern with (?x)

DOTALL

If this flag is set, then the . expression matches any character. If it is not set, then it does not match line terminator characters. This is also known as "single-line mode" and you can enable it within a pattern with (?s).

MULTILINE

If this flag is set, then the ^ and $ anchors match not only at the beginning and end of the input string, but also at the beginning and end of any lines within that string. Within a pattern you can enable this flag with (?m).

UNICODE_CASE

If this flag is set along with the CASE_INSENSITIVE flag, then case-insensitive comparison is done for all Unicode letters, rather than just for ASCII letters. You can enable both flags within a pattern with (?iu).

UNIX_LINES

If this flag is set, then only the newline character is considered a line terminator for the purposes of ., ^, and $. If the flag is not set, then newlines (\n) carriage returns (\r) and carriage return newline sequences (\r\n) are all considered line terminators, as are the Unicode characters \u0085 ("next line") \u2028 ("line separator") and \u2029 ("paragraph separator"). You can turn this flag on within a pattern with (?d).

Although the API for the Pattern class is quite simple, the syntax for the text representation of regular expressions is fairly complex. A complete tutorial on regular expressions is beyond the scope of this book. The table below, is a quick-reference for regular expression syntax. It is very similar to the syntax used in Perl. Note that many of the syntax elements of a regular expression include a backslash character, such as \d to match one of the digits 0-9. Because Java strings also use the backslash character as an escape, you must double the backslashes when expressing a regular expression as a string literal: "\\d". In Java 5.0, the static quote( ) method quotes all special characters in a string so that you can match arbitrary text literally without worrying that punctuation in that text will be interpreted specially. For complete details on regular expressions see a book like Programming Perl by Larry Wall et. al., or Mastering Regular Expressions by Jeffrey E. F. Friedl.

^[1] These repetition characters are known as "greedy quantifiers," because they match as many occurrences of x as possible while still allowing the rest of the regular expression to match. If you want a "reluctant quantifier" which matches as few occurrences as possible while still allowing the rest of the regular expression to match, follow the quantifiers above with a question mark. For example, use *? instead of *, and use {2,}? instead of {2,}. Or, if you follow a quantifier with a plus sign instead of a question mark, then you specify a "possessive quantifier" which matches as many occurrences as possible, even if it means that the rest of the regular expression will not match. Possessive quantifiers can be useful when you are sure that they will not adversely affect the rest of the match, because they can be implemented more efficiently than regular "greedy quantifiers."

^[2] Anchors do not match characters but instead match the zero-width positions between characters, "anchoring" the match to a position at which a specific condition holds.

Figure 16-132. java.util.regex.Pattern

public final class Pattern implements Serializable {
// No Constructor
// Public Constants
     public static final int CANON_EQ;                                   =128
     public static final int CASE_INSENSITIVE;                           =2
     public static final int COMMENTS;                                   =4
     public static final int DOTALL;                                     =32
5.0  public static final int LITERAL;                                =16
     public static final int MULTILINE;                                  =8
     public static final int UNICODE_CASE;                               =64
     public static final int UNIX_LINES;                                 =1
// Public Class Methods
     public static Pattern compile(String regex);  
     public static Pattern compile(String regex, int flags);  
     public static boolean matches(String regex, CharSequence input);  
5.0  public static String quote(String s);  
// Public Instance Methods
     public int flags( );  
     public Matcher matcher(CharSequence input);  
     public String pattern( );  
     public String[ ] split(CharSequence input);  
     public String[ ] split(CharSequence input, int limit);  
// Public Methods Overriding Object
5.0  public String toString( );  
}