Document that String.prototype.replace() resets lastIndex for global regexes

[btea]

Description

Explain that when the pattern is a regex with the g flag, replace() sets the regex's lastIndex to 0 before matching and leaves it at 0 after the call, so there is no need to manually reset lastIndex after using the same regex with methods like test(). Also note that non-global regexes do not get their lastIndex reset.

Per ECMA-262:

• https://tc39.es/ecma262/multipage/text-processing.html#sec-string.prototype.replace
• https://tc39.es/ecma262/#sec-regexp.prototype-@@replace

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace

[Josh-Cena]

Thanks, but as the paragraph directly preceding your addition says, all behaviors related to the regex itself is documented in the regex reference instead. The String method merely calls that method so this behavior doesn't pertain to it at all. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace offers a detailed explanation about how lastIndex is changed.

[btea]

Thanks for pointing that out — I hadn't noticed the RegExp.prototype[Symbol.replace]() page, which already documents this behavior.

[btea]

One follow-up after re-reading the spec and the current page: the RegExp.prototype[Symbol.replace]() page explains that exec() is called repeatedly until it returns null, and that the final failing exec() resets lastIndex to 0. However, it does not explicitly mention that the algorithm also resets lastIndex to 0 before matching starts.

Per ECMA-262 RegExp.prototype [ @@replace ], step 6:

If global is true, then
a. Perform ? Set(rx, "lastIndex", +0𝔽, true).

So for global regexes, matching always starts from the beginning of the string regardless of the regex's previous lastIndex (e.g. left behind by a prior test() call). The observable "left at 0 after the call" behavior comes from the failing exec() in the loop (per RegExpBuiltinExec, which sets lastIndex to 0 on failure for global/sticky regexes) — but the "starts from the beginning" guarantee comes from this entry step, which the page currently does not state.

Do you think it is worth adding one sentence to that page, e.g. "If the regex is global, lastIndex is first set to 0, so matching always starts from the beginning of the string"? Happy to open a new PR for that if you agree.

[Josh-Cena]

Yeah, I think that might be worth mentioning. Happy to take another PR!

[btea]

Opened #44957 to add the note about lastIndex being reset to 0 before matching on the RegExp.prototype[Symbol.replace]() page.