Difference between revisions of "PregMatchEx"

Revision as of 09:36, 2 July 2011

Definition

function PregMatchEx(const Pattern, Subject: AnsiString; out Matches: TRegexMatchArray): Boolean;

Availability

SCAR Divi 3.25 > Current

Description

Matches a regular expression defined by Pattern in a string defined by Subject and returns true if a match was found. All capture groups are returned in the given TRegexMatchArray Matches. The function is modeled after the equivalent which is available in PHP.

Patterns

Regular expressions have to be defined in a specific way to be used with this function, the syntax is similar/the same as in PHP. The function allows you define modifiers (options) for the regex engine in the pattern string.

Patterns are defined as: /pattern/modifiers or @pattern@modifiers

Modifiers^[1]

• i: If this modifier is set, letters in the pattern match both upper and lower case letters.
• m: By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually contains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline. This is the same as Perl. When this modifier is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the subject string, respectively, as well as at the very start and end. This is equivalent to Perl's /m modifier. If there are no "\n" characters in a subject string, or no occurrences of ^ or $ in a pattern, setting this modifier has no effect.
• s: If this modifier is set, a dot metacharacter in the pattern matches all characters, including newlines. Without it, newlines are excluded. This modifier is equivalent to Perl's /s modifier. A negative class such as [^a] always matches a newline character, independent of the setting of this modifier.
• x: If this modifier is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored. This is equivalent to Perl's /x modifier, and makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern.
• A: If this modifier is set, the pattern is forced to be "anchored", that is, it is constrained to match only at the start of the string which is being searched (the "subject string"). This effect can also be achieved by appropriate constructs in the pattern itself, which is the only way to do it in Perl.
• S: When a pattern is going to be used several times, it is worth spending more time analyzing it in order to speed up the time taken for matching. If this modifier is set, then this extra analysis is performed. At present, studying a pattern is useful only for non-anchored patterns that do not have a single fixed starting character.
• U: This modifier inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by ?. It is not compatible with Perl. It can also be set by a (?U) modifier setting within the pattern or by a question mark behind a quantifier (e.g. .*?).

Example 1

var
  Matches: TRegexMatchArray;
  i: Integer;

begin
  PregMatchEx('/World\! (\d+)/', 'Hello World! 125', Matches);
  for i := Low(Matches) to High(Matches) do
    WriteLn('"' + Matches[i].MatchedText + '" at ' + IntToStr(Matches[i].OffSet) +
      ' with length ' + IntToStr(Matches[i].Length));
end.

Output:

"World! 125" at 7 with length 10
"125" at 14 with length 3

Example 2 (Using a modifier)

var
  Matches: TRegexMatchArray;
  i: Integer;

begin
  PregMatchEx('/world\! (\d+)/i', 'Hello World! 125', Matches);
  for i := Low(Matches) to High(Matches) do
    WriteLn('"' + Matches[i].MatchedText + '" at ' + IntToStr(Matches[i].OffSet) +
      ' with length ' + IntToStr(Matches[i].Length));
end.

Output:

"World! 125" at 7 with length 10
"125" at 14 with length 3

See Also

• PregMatch
• PregQuote
• PregReplace

References