0
# Core Methods
1

2
Essential regex methods for pattern matching and testing.
3

4
## Capabilities
5

6
### exec Method
7

8
Executes the regex against a string or Buffer and returns detailed match information.
9

10
```javascript { .api }
11
/**
12
 * Execute regex against input and return match details
13
 * @param str - String or Buffer to search
14
 * @returns Match array with details or null if no match
15
 */
16
regex.exec(str: string): RegExpExecArray | null;
17
regex.exec(buffer: Buffer): RE2BufferExecArray | null;
18

19
// Return types
20
interface RegExpExecArray extends Array<string> {
21
  index: number;           // Match start position (characters)
22
  input: string;          // Original input string
23
  groups?: {              // Named capture groups
24
    [key: string]: string;
25
  };
26
}
27

28
interface RE2BufferExecArray extends Array<Buffer> {
29
  index: number;          // Match start position (bytes)
30
  input: Buffer;         // Original input Buffer
31
  groups?: {             // Named capture groups
32
    [key: string]: Buffer;
33
  };
34
}
35
```
36

37
**Behavior:**
38
- Updates `lastIndex` for global regexes
39
- Returns `null` if no match found
40
- For strings: positions in characters, results as strings
41
- For Buffers: positions in bytes, results as Buffers
42

43
**Usage Examples:**
44

45
```javascript
46
const RE2 = require("re2");
47

48
// String execution
49
const regex = new RE2("(\\d{3})-(\\d{4})", "g");
50
const text = "Call 555-1234 or 555-5678";
51

52
let match;
53
while ((match = regex.exec(text)) !== null) {
54
  console.log(match[0]);    // Full match: "555-1234"
55
  console.log(match[1]);    // First group: "555"
56
  console.log(match[2]);    // Second group: "1234"
57
  console.log(match.index); // Position: 5
58
}
59

60
// Buffer execution
61
const bufferRegex = new RE2("hello");
62
const buffer = Buffer.from("hello world", "utf8");
63
const bufferMatch = bufferRegex.exec(buffer);
64
console.log(bufferMatch[0]); // Buffer containing "hello"
65
console.log(bufferMatch.index); // 0 (byte position)
66

67
// Named groups
68
const namedRegex = new RE2("(?<area>\\d{3})-(?<number>\\d{4})");
69
const namedMatch = namedRegex.exec("555-1234");
70
console.log(namedMatch.groups.area);   // "555"
71
console.log(namedMatch.groups.number); // "1234"
72
```
73

74
### test Method
75

76
Tests whether the regex matches in the given input without returning match details.
77

78
```javascript { .api }
79
/**
80
 * Test if regex matches in input
81
 * @param str - String or Buffer to test
82
 * @returns Boolean indicating match success
83
 */
84
regex.test(str: string | Buffer): boolean;
85
```
86

87
**Behavior:**
88
- Returns `true` if match found, `false` otherwise
89
- More efficient than `exec()` when only testing for matches
90
- Updates `lastIndex` for global regexes
91
- Works with both strings and Buffers
92

93
**Usage Examples:**
94

95
```javascript
96
const RE2 = require("re2");
97

98
// Basic testing
99
const emailRegex = new RE2("\\w+@\\w+\\.\\w+");
100
console.log(emailRegex.test("user@example.com")); // true
101
console.log(emailRegex.test("invalid-email"));    // false
102

103
// Global regex testing
104
const globalRegex = new RE2("\\d+", "g");
105
const numbers = "1 2 3 4";
106
console.log(globalRegex.test(numbers)); // true (finds "1")
107
console.log(globalRegex.test(numbers)); // true (finds "2") 
108
console.log(globalRegex.test(numbers)); // true (finds "3")
109
console.log(globalRegex.test(numbers)); // true (finds "4")
110
console.log(globalRegex.test(numbers)); // false (no more matches)
111

112
// Buffer testing
113
const bufferRegex = new RE2("test");
114
const buffer = Buffer.from("test data", "utf8");
115
console.log(bufferRegex.test(buffer)); // true
116
```
117

118
### toString Method
119

120
Returns a string representation of the regex in standard format.
121

122
```javascript { .api }
123
/**
124
 * String representation of the regex
125
 * @returns String in /pattern/flags format
126
 */
127
regex.toString(): string;
128
```
129

130
**Behavior:**
131
- Always includes the `u` (Unicode) flag since RE2 always operates in Unicode mode
132
- Format: `/pattern/flags`
133
- Escapes special characters appropriately
134

135
**Usage Examples:**
136

137
```javascript
138
const RE2 = require("re2");
139

140
const regex1 = new RE2("\\d+", "gi");
141
console.log(regex1.toString()); // "/\\d+/giu"
142

143
const regex2 = new RE2("hello");
144
console.log(regex2.toString()); // "/hello/u"
145

146
const regex3 = new RE2("test", "gmsyid");
147
console.log(regex3.toString()); // "/test/dgimsyu" (flags alphabetically sorted)
148
```
149

150
### Pattern Validation
151

152
RE2 constructor validates patterns and throws errors for unsupported features.
153

154
**Supported Features:**
155
- Standard regex syntax
156
- Character classes: `[a-z]`, `[^0-9]`
157
- Quantifiers: `*`, `+`, `?`, `{n}`, `{n,}`, `{n,m}`
158
- Anchors: `^`, `$`, `\b`, `\B`
159
- Groups: `()`, `(?:)`, `(?<name>)`
160
- Alternation: `|`
161
- Unicode properties: `\p{L}`, `\P{N}`, etc.
162

163
**Unsupported Features (throw SyntaxError):**
164
- Backreferences: `\1`, `\2`, etc.
165
- Lookahead assertions: `(?=...)`, `(?!...)`
166
- Lookbehind assertions: `(?<=...)`, `(?<!...)`
167

168
**Usage Examples:**
169

170
```javascript
171
const RE2 = require("re2");
172

173
// Valid patterns
174
const valid1 = new RE2("\\d+");           // ✓ Basic pattern
175
const valid2 = new RE2("(?<name>\\w+)");  // ✓ Named groups
176
const valid3 = new RE2("\\p{L}+");        // ✓ Unicode properties
177

178
// Invalid patterns (throw SyntaxError)
179
try {
180
  const invalid1 = new RE2("(\\w+)\\1");     // ✗ Backreference
181
} catch (e) {
182
  console.log(e.message); // SyntaxError about backreferences
183
}
184

185
try {
186
  const invalid2 = new RE2("(?=test)");      // ✗ Lookahead
187
} catch (e) {
188
  console.log(e.message); // SyntaxError about lookahead
189
}
190
```