Using Patterns and Matchers

Apex provides patterns and matchers that enable you to search text using regular expressions.

A pattern is a compiled representation of a regular expression. Patterns are used by matchers to perform match operations on a character string.

A regular expression is a string that is used to match another string, using a specific syntax. Apex supports the use of regular expressions through its Pattern and Matcher classes.

In Apex, Patterns and Matchers, as well as regular expressions, are based on their counterparts in Java. See http://java.sun.com/j2se/1.5.0/docs/api/index.html?java/util/regex/Pattern.html.

Note

Many Matcher objects can share the same Pattern object, as shown in the following illustration:

Many Matcher objects can be created from the same Pattern object A flow chart showing flow from Regular Expression to Matcher object

Regular expressions in Apex follow the standard syntax for regular expressions used in Java. Any Java-based regular expression strings can be easily imported into your Apex code.

Salesforce limits the number of times an input sequence for a regular expression can be accessed to 1,000,000 times. If you reach that limit, you receive a runtime error.

Note

All regular expressions are specified as strings. Most regular expressions are first compiled into a Pattern object: only the String split method takes a regular expression that isn't compiled.

Generally, after you compile a regular expression into a Pattern object, you only use the Pattern object once to create a Matcher object. All further actions are then performed using the Matcher object. For example:

1// First, instantiate a new Pattern object "MyPattern"
2Pattern MyPattern = Pattern.compile('a*b');
3
4// Then instantiate a new Matcher object "MyMatcher"
5Matcher MyMatcher = MyPattern.matcher('aaaaab');
6
7// You can use the system static method assert to verify the match
8System.assert(MyMatcher.matches());

If you are only going to use a regular expression once, use the Pattern class matches method to compile the expression and match a string against it in a single invocation. For example, the following is equivalent to the code above:

1Boolean Test = Pattern.matches('a*b', 'aaaaab');