0
# Enhanced Execution Methods
1

2
Improved regex execution methods with named capture support, position control, and cross-browser consistency.
3

4
## Capabilities
5

6
### Enhanced Exec Method
7

8
Enhanced exec with named capture support and position/sticky options.
9

10
```javascript { .api }
11
/**
12
 * Enhanced exec with named capture support and position/sticky options
13
 * @param str - String to search
14
 * @param regex - Regex to search with
15
 * @param pos - Zero-based index at which to start the search
16
 * @param sticky - Whether the match must start at the specified position only
17
 * @returns Match array with named capture properties on groups object, or null
18
 */
19
function exec(str: string, regex: RegExp, pos?: number, sticky?: boolean | 'sticky'): ExecArray | null;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Basic usage with named capturing group
26
const regex = XRegExp('U\\+(?<hex>[0-9A-F]{4})');
27
const match = XRegExp.exec('U+2620', regex);
28
console.log(match.groups.hex); // '2620'
29

30
// With position and sticky matching
31
let pos = 3;
32
const result = [];
33
let match;
34
while (match = XRegExp.exec('<1><2><3><4>5<6>', /<(\\d)>/, pos, 'sticky')) {
35
  result.push(match[1]);
36
  pos = match.index + match[0].length;
37
}
38
// result -> ['2', '3', '4']
39

40
// Cross-browser consistent behavior
41
const match2 = XRegExp.exec('test', /t(e)(s)?/);
42
// Properly handles nonparticipating groups across browsers
43
```
44

45
### Enhanced Test Method
46

47
Enhanced test with position/sticky support and cross-browser fixes.
48

49
```javascript { .api }
50
/**
51
 * Enhanced test with position/sticky support
52
 * @param str - String to search
53
 * @param regex - Regex to search with
54
 * @param pos - Zero-based index at which to start the search
55
 * @param sticky - Whether the match must start at the specified position only
56
 * @returns Whether the regex matched the provided value
57
 */
58
function test(str: string, regex: RegExp, pos?: number, sticky?: boolean | 'sticky'): boolean;
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
// Basic usage
65
XRegExp.test('abc', /c/); // true
66

67
// With position and sticky
68
XRegExp.test('abc', /c/, 0, 'sticky'); // false (c not at position 0)
69
XRegExp.test('abc', /c/, 2, 'sticky'); // true (c at position 2)
70

71
// Cross-browser consistent results
72
XRegExp.test('test', /e/g); // Always returns true regardless of lastIndex
73
```
74

75
### ForEach Method
76

77
Executes a provided function once per regex match.
78

79
```javascript { .api }
80
/**
81
 * Executes a provided function once per regex match
82
 * @param str - String to search
83
 * @param regex - Regex to search with
84
 * @param callback - Function to execute for each match
85
 */
86
function forEach(str: string, regex: RegExp, callback: (match: ExecArray, index: number, str: string, regex: RegExp) => void): void;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
// Extract every other digit from a string
93
const evens = [];
94
XRegExp.forEach('1a2345', /\\d/, (match, i) => {
95
  if (i % 2) evens.push(+match[0]);
96
});
97
// evens -> [2, 4]
98

99
// Process all matches with named captures
100
const dates = [];
101
XRegExp.forEach('2021-01-15 and 2022-03-20', 
102
  XRegExp('(?<year>\\\\d{4})-(?<month>\\\\d{2})-(?<day>\\\\d{2})', 'g'),
103
  (match, i) => {
104
    dates.push({
105
      year: match.groups.year,
106
      month: match.groups.month,
107
      day: match.groups.day
108
    });
109
  }
110
);
111
```
112

113
## Named Capture Support
114

115
All execution methods provide enhanced named capture support:
116

117
### Groups Object
118

119
Named captures are available on the `groups` property (ES2018 standard):
120

121
```javascript
122
const regex = XRegExp('(?<name>\\\\w+)\\\\s+(?<age>\\\\d+)');
123
const match = XRegExp.exec('John 25', regex);
124

125
console.log(match.groups.name); // 'John'
126
console.log(match.groups.age);  // '25'
127
```
128

129
### Legacy Support
130

131
For backward compatibility, you can disable namespacing:
132

133
```javascript
134
// Disable namespacing to use old behavior
135
XRegExp.uninstall('namespacing');
136

137
const match = XRegExp.exec('John 25', regex);
138
console.log(match.name); // 'John' (directly on match object)
139
console.log(match.age);  // '25'
140
```
141

142
## Position and Sticky Matching
143

144
### Position Parameter
145

146
Start searching from a specific position:
147

148
```javascript
149
const text = 'abc def ghi';
150
const regex = /\\w+/;
151

152
const match1 = XRegExp.exec(text, regex, 0); // matches 'abc'
153
const match2 = XRegExp.exec(text, regex, 4); // matches 'def'
154
const match3 = XRegExp.exec(text, regex, 8); // matches 'ghi'
155
```
156

157
### Sticky Matching
158

159
Require matches to start exactly at the specified position:
160

161
```javascript
162
const text = 'abc def';
163
const regex = /def/;
164

165
XRegExp.test(text, regex, 4, true);      // true (def starts at position 4)
166
XRegExp.test(text, regex, 4, 'sticky'); // true (same as above)
167
XRegExp.test(text, regex, 0, 'sticky'); // false (def not at position 0)
168
```
169

170
## Cross-browser Compatibility
171

172
XRegExp execution methods fix several browser inconsistencies:
173

174
### Nonparticipating Groups
175

176
Properly handles `undefined` values for nonparticipating capturing groups:
177

178
```javascript
179
// Native behavior varies across browsers
180
const nativeResult = /t(e)(s)?/.exec('te');
181
// Some browsers: ['te', 'e', '']
182
// Others: ['te', 'e', undefined]
183

184
// XRegExp provides consistent behavior
185
const xregexpResult = XRegExp.exec('te', /t(e)(s)?/);
186
// Always: ['te', 'e', undefined]
187
```
188

189
### LastIndex Handling
190

191
Consistent `lastIndex` behavior across browsers:
192

193
```javascript
194
const regex = /\\w/g;
195
regex.lastIndex = 5;
196

197
// XRegExp.exec preserves and properly updates lastIndex
198
const match = XRegExp.exec('hello world', regex);
199
// Consistent behavior regardless of browser
200
```