0
# String Methods
1

2
String processing methods compatible with JavaScript's built-in string operations, enhanced with Buffer support.
3

4
## Capabilities
5

6
### match Method
7

8
Executes regex against input and returns match results, similar to String.prototype.match().
9

10
```javascript { .api }
11
/**
12
 * Find matches in input string or Buffer
13
 * @param str - String or Buffer to search
14
 * @returns Match array or null if no match
15
 */
16
regex.match(str: string): RegExpMatchArray | null;
17
regex.match(buffer: Buffer): RE2BufferMatchArray | null;
18

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

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

37
**Behavior:**
38
- **Non-global regex**: Returns first match with groups and position info
39
- **Global regex**: Returns array of all matches (no groups or position info)
40
- Compatible with `String.prototype.match()` via `Symbol.match`
41

42
**Usage Examples:**
43

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

47
// Non-global match (first match with details)
48
const phoneRegex = new RE2("(\\d{3})-(\\d{4})");
49
const phoneText = "Call 555-1234 or 555-5678";
50
const singleMatch = phoneRegex.match(phoneText);
51
console.log(singleMatch[0]);     // "555-1234" (full match)
52
console.log(singleMatch[1]);     // "555" (first group)
53
console.log(singleMatch[2]);     // "1234" (second group)
54
console.log(singleMatch.index);  // 5 (position)
55

56
// Global match (all matches, no groups)
57
const globalRegex = new RE2("\\d{3}-\\d{4}", "g");
58
const allMatches = globalRegex.match(phoneText);
59
console.log(allMatches); // ["555-1234", "555-5678"]
60

61
// Use with string method via Symbol.match
62
console.log(phoneText.match(phoneRegex)); // Same as phoneRegex.match(phoneText)
63

64
// Buffer matching
65
const bufferRegex = new RE2("\\w+");
66
const buffer = Buffer.from("hello world", "utf8");
67
const bufferMatch = bufferRegex.match(buffer);
68
console.log(bufferMatch[0]); // Buffer containing "hello"
69

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

77
### search Method
78

79
Finds the index of the first match, similar to String.prototype.search().
80

81
```javascript { .api }
82
/**
83
 * Find index of first match
84
 * @param str - String or Buffer to search
85
 * @returns Index of first match, or -1 if no match
86
 */
87
regex.search(str: string | Buffer): number;
88
```
89

90
**Behavior:**
91
- Returns character position for strings, byte position for Buffers
92
- Returns -1 if no match found
93
- Compatible with `String.prototype.search()` via `Symbol.search`
94
- Ignores global flag (always finds first match)
95

96
**Usage Examples:**
97

98
```javascript
99
const RE2 = require("re2");
100

101
// String search
102
const regex = new RE2("\\d+");
103
const text = "Page 123 of 456";
104
console.log(regex.search(text)); // 5 (position of "123")
105

106
const notFound = new RE2("xyz");
107
console.log(notFound.search(text)); // -1 (no match)
108

109
// Use with string method via Symbol.search
110
console.log(text.search(regex)); // Same as regex.search(text)
111

112
// Buffer search (byte positions)
113
const bufferRegex = new RE2("world");
114
const buffer = Buffer.from("hello world", "utf8");
115
console.log(bufferRegex.search(buffer)); // 6 (byte position)
116

117
// Unicode handling
118
const unicodeRegex = new RE2("世界");
119
const unicodeBuffer = Buffer.from("hello 世界", "utf8");
120
console.log(unicodeRegex.search(unicodeBuffer)); // 6 (byte position of 世界)
121
```
122

123
### replace Method
124

125
Replaces matches with replacement text or function result, similar to String.prototype.replace().
126

127
```javascript { .api }
128
/**
129
 * Replace matches with replacement text or function result
130
 * @param str - String or Buffer to process
131
 * @param replacement - Replacement string/Buffer or function
132
 * @returns New string/Buffer with replacements (same type as input)
133
 */
134
regex.replace<K extends String | Buffer>(
135
  str: K, 
136
  replacement: string | Buffer
137
): K;
138

139
regex.replace<K extends String | Buffer>(
140
  str: K,
141
  replacer: (substring: string, ...args: any[]) => string | Buffer
142
): K;
143
```
144

145
**Replacement Patterns:**
146
- `$&` - Full match
147
- `$1`, `$2`, etc. - Numbered groups
148
- `$<name>` - Named groups
149
- `$$` - Literal `$`
150

151
**Replacer Function Parameters:**
152
- `substring` - The matched text
153
- `...groups` - Captured groups (numbered)
154
- `offset` - Match position
155
- `input` - Original input
156
- `namedGroups` - Object with named groups
157

158
**Special Property:**
159
- Set `replacer.useBuffers = true` to receive Buffer arguments in replacer function
160

161
**Usage Examples:**
162

163
```javascript
164
const RE2 = require("re2");
165

166
// String replacement
167
const phoneRegex = new RE2("(\\d{3})-(\\d{4})");
168
const phoneText = "Call 555-1234";
169
const formatted = phoneRegex.replace(phoneText, "($1) $2");
170
console.log(formatted); // "Call (555) 1234"
171

172
// Global replacement
173
const globalRegex = new RE2("\\d+", "g");
174
const numbers = "1 and 2 and 3";
175
const doubled = globalRegex.replace(numbers, (match) => String(parseInt(match) * 2));
176
console.log(doubled); // "2 and 4 and 6"
177

178
// Named group replacement
179
const namedRegex = new RE2("(?<first>\\w+) (?<last>\\w+)");
180
const name = "John Doe";
181
const swapped = namedRegex.replace(name, "$<last>, $<first>");
182
console.log(swapped); // "Doe, John"
183

184
// Buffer replacement
185
const bufferRegex = new RE2("world");
186
const buffer = Buffer.from("hello world", "utf8");
187
const replaced = bufferRegex.replace(buffer, Buffer.from("universe", "utf8"));
188
console.log(replaced.toString()); // "hello universe"
189

190
// Replacer function with Buffer support
191
const bufferReplacer = (match, offset, input) => {
192
  return Buffer.from(match.toUpperCase(), "utf8");
193
};
194
bufferReplacer.useBuffers = true; // Receive Buffer arguments
195

196
const upperRegex = new RE2("\\w+", "g");
197
const upperBuffer = Buffer.from("hello world", "utf8");
198
const upperResult = upperRegex.replace(upperBuffer, bufferReplacer);
199
console.log(upperResult.toString()); // "HELLO WORLD"
200

201
// Use with string method via Symbol.replace
202
console.log(phoneText.replace(phoneRegex, "($1) $2")); // Same result
203
```
204

205
### split Method
206

207
Splits input by regex matches, similar to String.prototype.split().
208

209
```javascript { .api }
210
/**
211
 * Split input by regex matches
212
 * @param str - String or Buffer to split
213
 * @param limit - Optional maximum number of splits
214
 * @returns Array of string/Buffer parts (same type as input)
215
 */
216
regex.split<K extends String | Buffer>(str: K, limit?: number): K[];
217
```
218

219
**Behavior:**
220
- Returns array of same type as input (string → string[], Buffer → Buffer[])
221
- Includes captured groups in result array
222
- Respects optional limit parameter
223
- Compatible with `String.prototype.split()` via `Symbol.split`
224

225
**Usage Examples:**
226

227
```javascript
228
const RE2 = require("re2");
229

230
// Basic string splitting
231
const commaRegex = new RE2(",\\s*");
232
const csv = "apple, banana, cherry";
233
const fruits = commaRegex.split(csv);
234
console.log(fruits); // ["apple", "banana", "cherry"]
235

236
// Splitting with capture groups (groups included in result)
237
const delimiterRegex = new RE2("(,)\\s*");
238
const withDelimiters = delimiterRegex.split(csv);
239
console.log(withDelimiters); // ["apple", ",", "banana", ",", "cherry"]
240

241
// With limit
242
const limited = commaRegex.split(csv, 2);
243
console.log(limited); // ["apple", "banana"]
244

245
// Buffer splitting
246
const spaceRegex = new RE2("\\s+");
247
const buffer = Buffer.from("hello world test", "utf8");
248
const parts = spaceRegex.split(buffer);
249
console.log(parts.map(b => b.toString())); // ["hello", "world", "test"]
250

251
// Use with string method via Symbol.split
252
console.log(csv.split(commaRegex)); // Same as commaRegex.split(csv)
253

254
// Complex splitting with multiple delimiters
255
const multiRegex = new RE2("[,;]\\s*");
256
const mixed = "a,b; c , d;e";
257
const mixedParts = multiRegex.split(mixed);
258
console.log(mixedParts); // ["a", "b", "c", "d", "e"]
259
```
260

261
### Symbol Methods
262

263
RE2 implements Symbol methods to enable seamless integration with JavaScript string methods:
264

265
```javascript { .api }
266
/**
267
 * Symbol methods for string integration
268
 */
269
regex[Symbol.match](str: string): RegExpMatchArray | null;
270
regex[Symbol.search](str: string): number;
271
regex[Symbol.replace](str: string, replacement: string | Function): string;
272
regex[Symbol.split](str: string, limit?: number): string[];
273
regex[Symbol.matchAll](str: string): Iterator<RegExpExecArray>;
274
```
275

276
**matchAll Method** (requires global flag):
277

278
```javascript
279
const RE2 = require("re2");
280

281
// matchAll requires global flag
282
const globalRegex = new RE2("\\d+", "g");
283
const text = "1 and 2 and 3";
284

285
// Use Symbol.matchAll
286
for (const match of text.matchAll(globalRegex)) {
287
  console.log(match[0], "at position", match.index);
288
}
289
// Output:
290
// "1" at position 0
291
// "2" at position 6  
292
// "3" at position 12
293

294
// Convert to array
295
const allMatches = Array.from(text.matchAll(globalRegex));
296
console.log(allMatches.length); // 3
297

298
// Non-global regex throws TypeError
299
const nonGlobal = new RE2("\\d+");
300
try {
301
  Array.from(text.matchAll(nonGlobal)); // Throws TypeError
302
} catch (e) {
303
  console.log(e.message); // String.prototype.matchAll called with non-global RE2
304
}
305
```