regexp: add S.replace

.circleci/config.yml

@@ -28,7 +28,7 @@ jobs:
               nvm exec $1 npm test
             }
             case $CIRCLE_NODE_INDEX in
-              0) test_with_version 8 ;;
-              1) test_with_version 10 ;;
-              2) npm install && npm test ;;
+              0) test_with_version 10 ;;
+              1) npm install && npm test ;;
+              2) test_with_version 14 ;;
             esac

index.js

@@ -4403,6 +4403,53 @@
     impl: matchAll
   };
 
+  //# replace :: (Array (Maybe String) -> String) -> RegExp -> String -> String
+  //.
+  //. Replaces occurrences of the given pattern within the given string
+  //. in accordance with the given replacement function, which receives an
+  //. array of captured values. Replaces all occurrences of the pattern if
+  //. its `g` flag is set; just the first occurrence otherwise.
+  //.
+  //. ```javascript
+  //. > S.replace (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/) ('foo')
+  //. 'Foo'
+  //.
+  //. > S.replace (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/g) ('foo')
+  //. 'FOO'
+  //.
+  //. > S.replace (S.show) (/(foo)(bar)?/) ('<>')
+  //. '<>'
+  //.
+  //. > S.replace (S.show) (/(foo)(bar)?/) ('<foo>')
+  //. '<[Just ("foo"), Nothing]>'
+  //.
+  //. > S.replace (S.show) (/(foo)(bar)?/) ('<foobar>')
+  //. '<[Just ("foo"), Just ("bar")]>'
+  //. ```
+  function replace(substitute) {
+    return function(pattern) {
+      return function(text) {
+        return text.replace (pattern, function() {
+          var groups = [];
+          var group, idx = 1;
+          //  eslint-disable-next-line no-plusplus
+          while (typeof (group = arguments[idx++]) !== 'number') {
+            groups.push (group == null ? Nothing : Just (group));
+          }
+          return substitute (groups);
+        });
+      };
+    };
+  }
+  _.replace = {
+    consts: {},
+    types: [$.Fn ($.Array ($.Maybe ($.String))) ($.String),
+            $.RegExp,
+            $.String,
+            $.String],
+    impl: replace
+  };
+
   //. ### String
 
   //# toUpper :: String -> String

test/.eslintrc.json

@@ -1,9 +1,11 @@
 {
   "root": true,
   "extends": ["../node_modules/sanctuary-style/eslint-es6.json"],
+  "parserOptions": {"ecmaVersion": 2018},
   "env": {"node": true},
   "globals": {"suite": false, "test": false},
   "rules": {
+    "comma-dangle": ["error", {"arrays": "always-multiline", "objects": "always-multiline", "functions": "never"}],
     "max-len": ["off"]
   }
 }

test/replace.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const S = require ('..');
+
+const eq = require ('./internal/eq');
+
+
+test ('replace', () => {
+
+  eq (S.show (S.replace)) ('replace :: (Array (Maybe String) -> String) -> RegExp -> String -> String');
+
+  eq (S.replace (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/) ('foo')) ('Foo');
+  eq (S.replace (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/g) ('foo')) ('FOO');
+  eq (S.replace (S.show) (/(foo)(bar)?/) ('<>')) ('<>');
+  eq (S.replace (S.show) (/(foo)(bar)?/) ('<foo>')) ('<[Just ("foo"), Nothing]>');
+  eq (S.replace (S.show) (/(foo)(bar)?/) ('<foobar>')) ('<[Just ("foo"), Just ("bar")]>');
+  eq (S.replace (S.show) (/@(?<username>[-\w]+)/) ('@sanctuary-js')) ('[Just ("sanctuary-js")]');
+
+});