0
# String Processing Methods
1

2
Enhanced string methods with named backreference support and cross-browser fixes.
3

4
## Capabilities
5

6
### Enhanced Match Method
7

8
Enhanced match method with scope control and consistent return types.
9

10
```javascript { .api }
11
/**
12
 * Enhanced match method with scope control
13
 * @param str - String to search
14
 * @param regex - Regex to search with
15
 * @param scope - Use 'one' to return first match as string, 'all' for array of all matches
16
 * @returns In match-first mode: first match as string or null. In match-all mode: array of matches or empty array
17
 */
18
function match(str: string, regex: RegExp, scope?: 'one' | 'all'): string | string[] | null;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Match first occurrence
25
XRegExp.match('abc', /\\w/); // 'a'
26
XRegExp.match('abc', /\\w/g, 'one'); // 'a' (overrides global flag)
27
XRegExp.match('abc', /x/g, 'one'); // null
28

29
// Match all occurrences
30
XRegExp.match('abc', /\\w/g); // ['a', 'b', 'c']
31
XRegExp.match('abc', /\\w/, 'all'); // ['a', 'b', 'c'] (forces match-all)
32
XRegExp.match('abc', /x/, 'all'); // [] (empty array instead of null)
33
```
34

35
### Enhanced Replace Method
36

37
Enhanced replace with named backreference support and improved replacement syntax.
38

39
```javascript { .api }
40
/**
41
 * Enhanced replace with named backreference support
42
 * @param str - String to search
43
 * @param search - Search pattern to be replaced (string or regex)
44
 * @param replacement - Replacement string or function
45
 * @param scope - Use 'one' to replace first match only, 'all' for global replacement
46
 * @returns New string with one or all matches replaced
47
 */
48
function replace(str: string, search: string | RegExp, replacement: string | Function, scope?: 'one' | 'all'): string;
49
```
50

51
**Named Backreference Syntax:**
52
- `$<name>` or `${name}` - Named backreferences
53
- `$1`, `$2`, etc. - Numbered backreferences
54
- `$&` or `$0` - Full match
55
- `$$` - Literal dollar sign
56
- `$\`` - Left context (text before match)
57
- `$'` - Right context (text after match)
58

59
**Usage Examples:**
60

61
```javascript
62
// Named backreferences in replacement string
63
const nameRegex = XRegExp('(?<first>\\\\w+) (?<last>\\\\w+)');
64
XRegExp.replace('John Smith', nameRegex, '$<last>, $<first>');
65
// Result: 'Smith, John'
66

67
// Named backreferences in replacement function
68
XRegExp.replace('John Smith', nameRegex, (...args) => {
69
  const groups = args[args.length - 1];
70
  return `${groups.last}, ${groups.first}`;
71
});
72
// Result: 'Smith, John'
73

74
// String search with replace-all
75
XRegExp.replace('RegExp builds RegExps', 'RegExp', 'XRegExp', 'all');
76
// Result: 'XRegExp builds XRegExps'
77

78
// Scope control
79
XRegExp.replace('test test test', /test/g, 'X', 'one'); // 'X test test'
80
XRegExp.replace('test test test', /test/, 'X', 'all');  // 'X X X'
81
```
82

83
### Batch Replace Method
84

85
Performs batch processing of string replacements.
86

87
```javascript { .api }
88
/**
89
 * Performs batch processing of string replacements
90
 * @param str - String to search
91
 * @param replacements - Array of replacement detail arrays [search, replacement, scope?]
92
 * @returns New string with all replacements applied
93
 */
94
function replaceEach(str: string, replacements: [string | RegExp, string | Function, ('one' | 'all')?][]): string;
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
const result = XRegExp.replaceEach('abcdef', [
101
  [XRegExp('(?<name>a)'), 'z$<name>'],           // 'zabcdef'
102
  [/b/gi, 'y'],                                 // 'zaydef'
103
  [/c/g, 'x', 'one'],                          // 'zayxdef' (scope overrides /g)
104
  [/d/, 'w', 'all'],                           // 'zaywxef' (scope adds global)
105
  ['e', 'v', 'all'],                           // 'zaywxvf'
106
  [/f/g, (match) => match.toUpperCase()]       // 'zaywxvF'
107
]);
108
```
109

110
### Enhanced Split Method
111

112
Enhanced split method with cross-browser fixes and backreference support.
113

114
```javascript { .api }
115
/**
116
 * Enhanced split method with cross-browser fixes
117
 * @param str - String to split
118
 * @param separator - Regex or string to use for separating
119
 * @param limit - Maximum number of items to include in result array
120
 * @returns Array of substrings
121
 */
122
function split(str: string, separator: string | RegExp, limit?: number): string[];
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Basic usage
129
XRegExp.split('a b c', ' '); // ['a', 'b', 'c']
130

131
// With limit
132
XRegExp.split('a b c', ' ', 2); // ['a', 'b']
133

134
// Backreferences in result array
135
XRegExp.split('..word1..', /([a-z]+)(\\d+)/i);
136
// Result: ['..', 'word', '1', '..']
137

138
// Cross-browser consistent behavior
139
XRegExp.split('a,,b', /,/); // Always ['a', '', 'b'] regardless of browser
140
```
141

142
## Named Backreferences in Replacements
143

144
### Replacement String Syntax
145

146
XRegExp extends standard replacement syntax with named backreferences:
147

148
```javascript
149
const phoneRegex = XRegExp('(?<area>\\\\d{3})-(?<exchange>\\\\d{3})-(?<number>\\\\d{4})');
150
const phone = '555-123-4567';
151

152
// Standard numbered backreferences
153
XRegExp.replace(phone, phoneRegex, '($1) $2-$3');
154
// Result: '(555) 123-4567'
155

156
// Named backreferences with angle brackets
157
XRegExp.replace(phone, phoneRegex, '($<area>) $<exchange>-$<number>');
158
// Result: '(555) 123-4567'
159

160
// Named backreferences with curly braces
161
XRegExp.replace(phone, phoneRegex, '(${area}) ${exchange}-${number}');
162
// Result: '(555) 123-4567'
163
```
164

165
### Replacement Functions
166

167
Named captures are passed to replacement functions:
168

169
```javascript
170
const dateRegex = XRegExp('(?<year>\\\\d{4})-(?<month>\\\\d{2})-(?<day>\\\\d{2})');
171

172
XRegExp.replace('2021-02-22', dateRegex, (match, year, month, day, index, string, groups) => {
173
  // With namespacing enabled (default in XRegExp 5+):
174
  // groups.year, groups.month, groups.day
175
  return `${groups.month}/${groups.day}/${groups.year}`;
176
});
177

178
// Without namespacing (legacy mode):
179
XRegExp.uninstall('namespacing');
180
XRegExp.replace('2021-02-22', dateRegex, (match, year, month, day, index, string) => {
181
  // Named properties directly on match object
182
  return `${match.month}/${match.day}/${match.year}`;
183
});
184
```
185

186
## Cross-browser Consistency
187

188
XRegExp string methods provide consistent behavior across browsers:
189

190
### Replacement Text Handling
191

192
Properly handles replacement text edge cases:
193

194
```javascript
195
// Consistent handling of special replacement sequences
196
XRegExp.replace('test', /e/, '$&$&'); // Always 'teest'
197
XRegExp.replace('test', /e/, '$$');   // Always 'te$t'
198
```
199

200
### Split Edge Cases
201

202
Handles split edge cases consistently:
203

204
```javascript
205
// Consistent empty string handling
206
XRegExp.split('abc', /(?=)/); // Consistent results across browsers
207

208
// Proper limit handling
209
XRegExp.split('a-b-c', /-/, 2); // Always ['a', 'b']
210
```
211

212
### Match Type Consistency
213

214
Provides predictable return types:
215

216
```javascript
217
// XRegExp.match always returns arrays for match-all, strings/null for match-first
218
const result1 = XRegExp.match('abc', /\\w/, 'all'); // Always array ['a', 'b', 'c']
219
const result2 = XRegExp.match('abc', /x/, 'all');   // Always array []
220
const result3 = XRegExp.match('abc', /\\w/);        // Always string 'a' or null
221
```