0
# Core Pattern Matching
1
2
Essential pattern matching functions that provide the primary interface for regular expressions. These functions support searching for patterns within text, matching patterns at specific positions, and extracting subpatterns.
3
4
## Capabilities
5
6
### Pattern Search
7
8
Searches for the first occurrence of a pattern anywhere in the input text, returning a match object if found.
9
10
```python { .api }
11
def search(pattern, text, options=None):
12
"""
13
Search for pattern in text and return the first match.
14
15
Args:
16
pattern (str): Regular expression pattern
17
text (str): Input text to search
18
options (Options, optional): Compilation options
19
20
Returns:
21
_Match or None: Match object if pattern found, None otherwise
22
"""
23
```
24
25
Example usage:
26
27
```python
28
import re2
29
30
# Find email address in text
31
text = "Contact us at support@example.com"
32
match = re2.search(r'(\w+)@(\w+\.\w+)', text)
33
if match:
34
print(match.group()) # "support@example.com"
35
print(match.groups()) # ("support", "example.com")
36
print(match.start()) # 14
37
print(match.end()) # 33
38
```
39
40
### Pattern Match
41
42
Matches a pattern only at the beginning of the input text, similar to anchoring the pattern with `^`.
43
44
```python { .api }
45
def match(pattern, text, options=None):
46
"""
47
Match pattern at the beginning of text.
48
49
Args:
50
pattern (str): Regular expression pattern
51
text (str): Input text to match
52
options (Options, optional): Compilation options
53
54
Returns:
55
_Match or None: Match object if pattern matches at start, None otherwise
56
"""
57
```
58
59
Example usage:
60
61
```python
62
import re2
63
64
# Match at beginning only
65
text = "Hello world"
66
match = re2.match(r'Hello', text)
67
print(match is not None) # True
68
69
match = re2.match(r'world', text)
70
print(match is not None) # False (doesn't match at beginning)
71
```
72
73
### Full Pattern Match
74
75
Matches a pattern against the entire input text, requiring the pattern to match the complete string.
76
77
```python { .api }
78
def fullmatch(pattern, text, options=None):
79
"""
80
Match pattern against the entire text.
81
82
Args:
83
pattern (str): Regular expression pattern
84
text (str): Input text to match
85
options (Options, optional): Compilation options
86
87
Returns:
88
_Match or None: Match object if pattern matches entire text, None otherwise
89
"""
90
```
91
92
Example usage:
93
94
```python
95
import re2
96
97
# Must match entire string
98
text = "123-45-6789"
99
match = re2.fullmatch(r'\d{3}-\d{2}-\d{4}', text)
100
print(match is not None) # True
101
102
match = re2.fullmatch(r'\d{3}', text)
103
print(match is not None) # False (doesn't match entire string)
104
```
105
106
### Find All Matches
107
108
Finds all non-overlapping matches of a pattern in the input text, returning captured groups or full matches.
109
110
```python { .api }
111
def findall(pattern, text, options=None):
112
"""
113
Find all matches of pattern in text.
114
115
Args:
116
pattern (str): Regular expression pattern
117
text (str): Input text to search
118
options (Options, optional): Compilation options
119
120
Returns:
121
list: List of matched strings or tuples of groups
122
"""
123
```
124
125
Example usage:
126
127
```python
128
import re2
129
130
# Find all digits
131
text = "Phone: 555-1234, Fax: 555-5678"
132
numbers = re2.findall(r'\d+', text)
133
print(numbers) # ['555', '1234', '555', '5678']
134
135
# Find with groups
136
matches = re2.findall(r'(\w+): (\d{3})-(\d{4})', text)
137
print(matches) # [('Phone', '555', '1234'), ('Fax', '555', '5678')]
138
```
139
140
### Find All Match Objects
141
142
Returns an iterator of match objects for all non-overlapping matches, providing detailed information about each match.
143
144
```python { .api }
145
def finditer(pattern, text, options=None):
146
"""
147
Return iterator of match objects for all matches.
148
149
Args:
150
pattern (str): Regular expression pattern
151
text (str): Input text to search
152
options (Options, optional): Compilation options
153
154
Returns:
155
iterator: Iterator of _Match objects
156
"""
157
```
158
159
Example usage:
160
161
```python
162
import re2
163
164
text = "The numbers are 42 and 123"
165
for match in re2.finditer(r'\d+', text):
166
print(f"Found '{match.group()}' at position {match.start()}-{match.end()}")
167
# Found '42' at position 16-18
168
# Found '123' at position 23-26
169
```
170
171
## Match Object Interface
172
173
```python { .api }
174
class _Match:
175
"""Represents a successful regular expression match."""
176
177
def group(*groups):
178
"""
179
Return one or more subgroups of the match.
180
181
Args:
182
*groups: Group numbers or names (0 = entire match)
183
184
Returns:
185
str or tuple: Matched group(s)
186
"""
187
188
def groups(default=None):
189
"""
190
Return tuple of all groups.
191
192
Args:
193
default: Value for unmatched groups
194
195
Returns:
196
tuple: All captured groups
197
"""
198
199
def groupdict(default=None):
200
"""
201
Return dictionary of named groups.
202
203
Args:
204
default: Value for unmatched groups
205
206
Returns:
207
dict: Named groups mapping
208
"""
209
210
def start(group=0):
211
"""
212
Return start position of group.
213
214
Args:
215
group (int): Group number (0 = entire match)
216
217
Returns:
218
int: Start position
219
"""
220
221
def end(group=0):
222
"""
223
Return end position of group.
224
225
Args:
226
group (int): Group number (0 = entire match)
227
228
Returns:
229
int: End position
230
"""
231
232
def span(group=0):
233
"""
234
Return (start, end) tuple for group.
235
236
Args:
237
group (int): Group number (0 = entire match)
238
239
Returns:
240
tuple: (start, end) positions
241
"""
242
243
def expand(template):
244
"""
245
Expand template string using match groups.
246
247
Args:
248
template (str): Template with group references
249
250
Returns:
251
str: Expanded string
252
"""
253
254
# Properties
255
re: '_Regexp' # Pattern object that produced this match
256
string: str # String that was searched
257
pos: int # Start position of search
258
endpos: int # End position of search
259
lastindex: int # Index of last matched group
260
lastgroup: str # Name of last matched group
261
```