Next: , Previous: Regexp Functions, Up: Regular Expressions

5.5.6.2 Match Structures

A match structure is the object returned by string-match and regexp-exec. It describes which portion of a string, if any, matched the given regular expression. Match structures include: a reference to the string that was checked for matches; the starting and ending positions of the regexp match; and, if the regexp included any parenthesized subexpressions, the starting and ending positions of each submatch.

In each of the regexp match functions described below, the match argument must be a match structure returned by a previous call to string-match or regexp-exec. Most of these functions return some information about the original target string that was matched against a regular expression; we will call that string target for easy reference.

— Scheme Procedure: regexp-match? obj

Return #t if obj is a match structure returned by a previous call to regexp-exec, or #f otherwise.

— Scheme Procedure: match:substring match [n]

Return the portion of target matched by subexpression number n. Submatch 0 (the default) represents the entire regexp match. If the regular expression as a whole matched, but the subexpression number n did not match, return #f. 

     (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
     (match:substring s)
     => "2002"
     
     ;; match starting at offset 6 in the string
     (match:substring
       (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
     => "7654"
— Scheme Procedure: match:start match [n]

Return the starting position of submatch number n.

In the following example, the result is 4, since the match starts at character index 4: 

     (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
     (match:start s)
     => 4
— Scheme Procedure: match:end match [n]

Return the ending position of submatch number n.

In the following example, the result is 8, since the match runs between characters 4 and 8 (i.e. the “2002”). 

     (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
     (match:end s)
     => 8
— Scheme Procedure: match:prefix match

Return the unmatched portion of target preceding the regexp match. 

          (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
          (match:prefix s)
          => "blah"
— Scheme Procedure: match:suffix match

Return the unmatched portion of target following the regexp match. 

     (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
     (match:suffix s)
     => "foo"
— Scheme Procedure: match:count match

Return the number of parenthesized subexpressions from match. Note that the entire regular expression match itself counts as a subexpression, and failed submatches are included in the count.

— Scheme Procedure: match:string match

Return the original target string. 

     (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
     (match:string s)
     => "blah2002foo"