regexp: add S.replace

[davidchambers]

Supersedes #686

This pull request adds the following function:

replace :: (Array (Maybe String) -> String) -> RegExp -> String -> String

In #686 (comment), @Avaq made a strong case for naming this more general function replace. @Avaq also noted that the specialized function, replaceWith, is trivially derivable from replace. For this reason I decided not to include replaceWith in this pull request; it could easily be added in the future if replace (K ('...')) proves irksome.

I have opened sanctuary-js/sanctuary-site#90 to provide several examples of replace in use.

[Avaq]

Is it possible to know the length of this array upfront? Say, using var groups = new Array(arguments.length). If so, then that would get you slightly better performance at relatively low implementation and maintenance cost. You would have to alter groups.push statements to index assignment statements instead, eg: groups[idx] = (...).

[davidchambers]

Is it possible to know the length of this array upfront?

No, due to the existence of named capturing groups:

> '@sanctuary-js'.replace (/@([-\w]+)/, function() { return arguments.length; })
'4'

> '@sanctuary-js'.replace (/@(?<username>[-\w]+)/, function() { return arguments.length; })
'5'

[Avaq]

Ah, so these named groups are skipped? Is that what the typeof check below is doing?

[davidchambers]

That's right. I imagine groups is omitted when the pattern contains no named capturing groups to preserve backward compatibility. Providing the sensible empty value, {}, as an additional argument would break programs that assume that Array.prototype.slice.call(arguments, 1, -2) extracts (only) the captured values.

[Avaq]

Oh, wow. It took me a really long time to realize that what's happening there is: skip one argument, and keep taking arguments until a number is encountered. The numeric argument signifies the "end" of the capture group arguments. Wow. The signature of JavaScript's replace is crazier than I remember.