This pull request adds the following two functions:

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

Design decisions:

• Both functions take pattern :: RegExp, so there is no straightforward equivalent of s1.replace (s2, s3) for strings s1, s2, and s3. One could use S.replace (S.regex ('') (S.regexEscape (s2))) (s3) (s1), but it would be simpler and clearer to use String#replace directly in such cases.

  Using pattern :: RegExp exclusively provides two benefits:

  • Simplicity. Supporting both RegExp and String would require splitting replace into two functions (which would pose a naming challenge) or using Either RegExp String (which would not be ergonomic).

  • Clarity. It's unclear whether R.replace ('o') ('x') ('foo') should evaluate to 'fxo' or to 'fxx', whereas the presence of the g flag in /o/g indicates that all occurrences of o should be replaced, and the absence of the g flag in /o/ indicates that only the first occurrence of o should be replaced.

• Like replace', S.replace_ ignores the “offset” and “string” arguments provided by String#replace (when given a function). These are rarely useful.

• Unlike replace', S.replace_ ignores the “groups” argument provided by String#replace (when given a function) if the pattern contains any named capturing groups. I included a fix for this deficiency in purescript/purescript-strings#126.

• Unlike replace', S.replace_ ignores the “match” argument provided by String#replace (when given a function). This simplifies the function's type, and saves one from using S.K (...) when only the captured groups are important (as is commonly the case). If one does require access to the matched substring as a whole, one can use /(...)/ to capture it. Admittedly, this approach is impractical if the RegExp object is defined in another module, but in such exceptional cases one can of course use String#replace directly.

• Unlike replace', S.replace_ acknowledges the existence of optional capturing groups:

  > S.replace_ (S.regex ('') ('(Pure)?(Script)')) (S.show) ('JavaScript')
  'Java[Nothing, Just ("Script")]'

  Evaluating the equivalent PureScript expression results in an exception being thrown:

  > replace' (unsafeRegex "(Pure)?(Script)" noFlags) (const show) "JavaScript"
  ! TypeError: undefined is not an object (evaluating 's.length')

  I have proposed the use of Array (Maybe String) in place of Array String in purescript/purescript-strings#126.

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

@sanctuary-js/owners, what do you think of the proposed additions to the library?

@CrossEye, you may like to rethink R.replace, which currently exposes all the quirks of String#replace.