Overview

ICU's Regular Expressions package provides applications with the ability to apply regular expression matching to Unicode string data. The regular expression patterns and behavior are based on Perl's regular expressions. The C++ programming API for using ICU regular expressions is loosely based on the JDK 1.4 package java.util.regex, with some extensions to adapt it for use in a C++ environment. A plain C API is also provided.

The ICU Regular expression API supports operations including testing for a pattern match, searching for a pattern match, and replacing matched text. Capture groups allow subranges within an overall match to be identified, and to appear within replacement text.

A Perl-inspired split() function that breaks a string into fields based on a delimiter pattern is also included.

A detailed description of regular expression patterns and pattern matching behavior is not included in this user guide. The best reference for this topic is the book "Mastering Regular Expressions, Second Edition" by Jeffrey E. F. Friedl, O'Reilly & Associates; 2nd edition (July 15, 2002). Matching behavior can sometimes be surprising, and this book is highly recommended for anyone doing significant work with regular expressions.

Using ICU Regular Expressions

The ICU C++ Regular Expression API includes two classes, RegexPattern and RegexMatcher, that parallel the classes from the Java JDK package java.util.regex.    A RegexPattern represents a compiled regular expression while RegexMatcher associates a RegexPattern and an input string to be matched, and provides API for the various find, match and replace operations. In most cases, however, only the class RegexMatcher is needed, and the existence of class RegexPattern can safely be ignored.

The first step in using a regular expression is typically the creation of a RegexMatcher object from the source (string) form of the regular expression.

RegexMatcher holds a pre-processed (compiled) pattern and a reference to an input string to be matched, and provides API for the various find, match and replace operations. RegexMatchers can be reset and reused with new input, thus avoiding object creation overhead when performing the same matching operation repeatedly on different strings.

The following code will create a RegexMatcher from a string containing a regular expression, and then perform a simple find() operation.

#include <unicode/regex.h>

UErrorCode        status    = U_ZERO_ERROR;

  ...

RegexMatcher *matcher = new RegexMatcher("abc+", 0, status);
if (U_FAILURE(status)) {
    // Handle any syntax errors in the regular expression here
    ...
}


UnicodeString    stringToTest = "Find the abc in this string";
matcher->reset(stringToTest);

if (matcher->find()) {
   // We found a match.
   int startOfMatch = matcher->start(status);   // string index of start of match.
   ...
}

Several types of matching tests are available

If additional text is to be checked for a match with the same pattern, there is no need to create a new matcher object; just reuse the existing one.

myMatcher->reset(anotherString);
if (myMatcher->matches(status)) {
   // We have a with the new string.
}

Note that matching happens directly in the string supplied by the application. This reduces the overhead when resetting a matcher to an absolute minimum – the matcher need only store a reference to the new string – but it does mean that the application must be careful not to modify or delete the string while the matcher is holding a reference to the string.

After finding a match, additional information is available about the range of the input matched, and the contents of any capture groups. Note that, for simplicity, any error parameters have been omitted. See the API reference for complete a complete description of the API.

Regular Expression Metacharacters

Regular Expression Operators

Replacement Text

The replacement text for find-and-replace operations may contain references to capture-group text from the find. References are of the form $n, where n is the number of the capture group.

Flag Options

The following flags control various aspects of regular expression matching. The flag values may be specified at the time that an expression is compiled into a RegexPattern object, or they may be specified within the pattern itself using the (?ismx-ismx) pattern options.

The UREGEX_CANON_EQ option is not yet available.

Using split()

ICU's split() function is similar in concept to Perl's – it will split a string into fields, with a regular expression match defining the field delimiters and the text between the delimiters being the field content itself.

Suppose you have a string of words separated by spaces

    UnicodeString s = “dog cat   giraffe”;

This code will extract the individual words from the string.

    UErrorCode status = U_ZERO_ERROR;
    RegexMatcher m(“\\s+”, 0, status); 
    const int maxWords = 10;
    UnicodeString words[maxWords];    
    int numWords = m.split(s, words, maxWords, status);

After the split(),

The field delimiters, the spaces from the original string, do not appear in the output strings.

Note that, in this example, “words” is a local, or stack array of actual UnicodeString objects. No heap allocation is involved in initializing this array of empty strings (C++ is not Java!). Local UnicodeString arrays like this are a very good fit for use with split(); after extracting the fields, any values that need to be kept in some more permanent way can be copied to their ultimate destination.

If the number of fields in a string being split exceeds the capacity of the destination array, the last destination string will contain all of the input string data that could not be split, including any embedded field delimiters. This is similar to split() in Perl.

If the pattern expression contains capturing parentheses, the captured data ($1, $2, etc.) will also be saved in the destination array, interspersed with the fields themselves.

If, in the “dog cat giraffe” example, the pattern had been “(\s+)” instead of “\s+”, split() would have produced five output strings instead of three. Words[1] and words[3] would have been the spaces.

Find and Replace

Description of AppendReplacement() and AppendTail(). To be added.