Python - Regex Match Object

Python provides the re module for working with Regular Expressions.

Two important functions used in the beginning are:

• compile()
• finditer()

The basic process is:

Regular Expression Pattern
          │
          ▼
      compile()
          │
          ▼
     Regex Object
          │
          ▼
      finditer()
          │
          ▼
    Match Objects

compile() creates a Regex Object, while finditer() searches the target string and returns Match Objects for matching occurrences.

The compile() function is used to compile a Regular Expression pattern into a Regex Object.

Syntax:

re.compile(pattern)

Example:

import re

pattern = re.compile("ab")

Here:

• "ab" is the Regular Expression.
• re.compile("ab") compiles the pattern.
• pattern refers to the resulting Regex Object.

The object returned by re.compile() is called a Regex Object or compiled Regular Expression object.

"ab"
 │
 ▼
re.compile("ab")
 │
 ▼
Regex Object
 │
 ▼
pattern

We can use this Regex Object to search for occurrences of the compiled pattern inside a target string.

Example:

pattern = re.compile("ab")

Now pattern can be used with methods such as:

pattern.finditer(target_string)

The finditer() method is used to find all occurrences of a Regular Expression inside the given target string.

Syntax:

matcher = pattern.finditer(target_string)

Example:

matcher = pattern.finditer("abaababa")

Here:

• pattern is the Regex Object.
• "abaababa" is the target string.
• finditer() searches for all matching occurrences.
• The matches can be processed one by one using a loop.

Target String
   │
   ▼
"abaababa"
   │
   ▼
finditer()
   │
   ▼
Matching Occurrences

For every successful occurrence found by finditer(), Python provides a Match Object.

The Match Object contains information about the matched text.

Important information includes:

• Starting index of the match
• Ending index of the match
• Matched string

Match Object
     │
     ├── start()
     ├── end()
     └── group()

These methods allow us to inspect every occurrence found by the Regular Expression.

The Match Object provides the following important methods:

Let us look at each method of the Match Object in detail.

1. start() Method

The start() method returns the starting index of the matched substring.

Syntax:

match.start()

Suppose:

Target String: abaababa
Index:         01234567

If ab is matched at index 0, then:

match.start()

returns:

0

2. end() Method

The end() method returns the ending index of the match.

Important: The value returned by end() is the index immediately after the matched substring.

Example:

Target: abaababa
Index:  01234567

Match = "ab"

start() = 0
end()   = 2

The characters of the match are at indexes:

0 and 1

but end() returns:

2

3. group() Method

The group() method returns the actual matched substring.

Syntax:

match.group()

If the Regular Expression is:

ab

then for every successful match:

match.group()

returns:

ab

Consider:

Target String = "abaababa"
Pattern       = "ab"

Index positions:

Characters : a b a a b a b a
Indexes    : 0 1 2 3 4 5 6 7

Visual representation of the matching:

Index      : 0 1 2 3 4 5 6 7
Character  : a b a a b a b a
             └─┘   └─┘ └─┘
              1     2   3

The pattern ab occurs at:

Indexes 0-1
Indexes 3-4
Indexes 5-6

Therefore:

Let us combine everything into a complete demo program that counts and displays every match.

The demo program can be understood step by step. Let us look at the first four steps, which set up the search.

Step 1: Import the re Module

The first statement is:

import re

This imports Python's Regular Expression module. After importing re, we can use Regular Expression functions such as compile() and finditer().

Step 2: Initialize count

Next:

count = 0

The variable count is used to count the total number of matching occurrences. Initially:

count = 0

Step 3: Compile the Pattern

The statement:

pattern = re.compile("ab")

compiles the Regular Expression:

ab

and creates a Regex Object.

"ab"
 │
 ▼
compile()
 │
 ▼
Regex Object
 │
 ▼
pattern

Step 4: Search the Target String

The statement:

matcher = pattern.finditer("abaababa")

searches the target string for all occurrences of ab.

Target:

abaababa

Indexes:

a b a a b a b a
0 1 2 3 4 5 6 7

Matches:

ab      → indexes 0 and 1
ab      → indexes 3 and 4
ab      → indexes 5 and 6

Therefore, there are three matches.

Now let us see how the program processes each match.

Step 5: Iterate Through Match Objects

The loop:

for match in matcher:

processes each Match Object one by one.

matcher
   │
   ├── Match Object 1
   ├── Match Object 2
   └── Match Object 3

For each Match Object, the loop body executes once.

Step 6: Increment the Counter

Inside the loop:

count += 1

increments the number of occurrences.

Initially
count = 0

First Match
count = 1

Second Match
count = 2

Third Match
count = 3

Step 7: Display Match Information

The statement:

print(match.start(), "...", match.end(), "...", match.group())

prints three pieces of information for every match:

• Start index
• End index
• Matched substring

For the first match:

start() = 0
end()   = 2
group() = ab

Output:

0 ... 2 ... ab

Step 8: Second Match

The second ab starts at index 3.

a b a a b a b a
0 1 2 3 4 5 6 7
      └─┘
       ab

Therefore:

start() = 3
end()   = 5
group() = ab

Output:

3 ... 5 ... ab

Step 9: Third Match

The third ab starts at index 5.

a b a a b a b a
0 1 2 3 4 5 6 7
          └─┘
           ab

Therefore:

start() = 5
end()   = 7
group() = ab

Output:

5 ... 7 ... ab

Step 10: Display Number of Occurrences

After processing all Match Objects:

count = 3

The statement:

print("The number of occurrences:", count)

prints:

The number of occurrences: 3

The complete execution flow of the demo program is shown below.

Program Starts
      │
      ▼
import re
      │
      ▼
count = 0
      │
      ▼
re.compile("ab")
      │
      ▼
Create Regex Object
      │
      ▼
pattern.finditer("abaababa")
      │
      ▼
Search for "ab"
      │
      ▼
Match 1 Found
start = 0
end   = 2
group = ab
      │
      ▼
count = 1
      │
      ▼
Match 2 Found
start = 3
end   = 5
group = ab
      │
      ▼
count = 2
      │
      ▼
Match 3 Found
start = 5
end   = 7
group = ab
      │
      ▼
count = 3
      │
      ▼
No More Matches
      │
      ▼
Print Total Occurrences
      │
      ▼
3
      │
      ▼
Program Ends

Students commonly become confused about end().

Consider the first match:

a b
0 1

The matched characters are at indexes:

0 and 1

But:

match.end()

returns:

2

This is because end() returns the index immediately after the matched substring.

Match Range = [start, end)

             0      2
             │      │
             ▼      ▼
             a  b   a
             └──┘
              ab

Therefore:

start() = inclusive
end()   = exclusive

Creating a separate Regex Object with compile() is not compulsory for every case.

Instead of:

pattern = re.compile("ab")
matcher = pattern.finditer("abaababa")

we can directly use:

matcher = re.finditer("ab", "abaababa")

Here:

• The first argument is the Regular Expression.
• The second argument is the target string.

Here, Python directly searches for Pattern = "ab" inside Target = "abaababa". There is no separate statement:

re.compile("ab")

The remaining logic is the same. For every match, match.start(), match.end(), and match.group() provide the start index, end index, and matched text.

Let us rewrite the demo program using this direct approach.

The following table compares the two approaches.

pattern = re.compile("ab")
matcher = pattern.finditer("abaababa")

matcher = re.finditer("ab", "abaababa")

The Regex Object and the Match Object play different roles. The following table compares them.

The complete concept flow, from the Regular Expression to the Match Objects, is shown below.

                 import re
                    │
                    ▼
            Regular Expression
                  "ab"
                    │
                    ▼
             re.compile()
                    │
                    ▼
               Regex Object
                    │
                    ▼
                finditer()
                    │
                    ▼
             Target String
              "abaababa"
                    │
                    ▼
             Matching Results
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
      Match 1     Match 2     Match 3
        │           │           │
        ▼           ▼           ▼
      0..2        3..5        5..7
        │           │           │
        ▼           ▼           ▼
       "ab"        "ab"        "ab"

Each Match Object provides:

start()
end()
group()

The following table quickly revises every concept covered in this page.

Summary:

• Python provides the re module for Regular Expressions.
• re.compile() compiles a Regular Expression pattern into a Regex Object.
• finditer() is used to find matching occurrences in a target string.
• Every successful occurrence can be represented by a Match Object.
• start() returns the starting index of a match.
• end() returns the index immediately after the match.
• group() returns the matched substring.
• For pattern ab in abaababa, three occurrences are found, beginning at indexes 0, 3, and 5, with end() values 2, 5, and 7.
• Instead of separately using compile(), we can directly use re.finditer("ab", "abaababa").

Important Notes:

1. Always import the re module before using its Regular Expression functions.
2. compile() converts a Regular Expression pattern into a Regex Object.
3. A Regex Object represents the compiled pattern.
4. finditer() searches for matching occurrences in the target string.
5. A Match Object represents one successful occurrence.
6. start() returns the starting index of the match.
7. end() returns the index immediately after the match, not the index of the last matched character.
8. Therefore, the match range can be understood as [start, end).
9. group() returns the actual matched substring.
10. The pattern ab occurs three times in abaababa, with starting indexes 0, 3, and 5.
11. We can use re.finditer(pattern, target) directly without explicitly storing a compiled Regex Object first.
12. Using compile() is useful when the same Regular Expression pattern has to be reused.