Feat: Add count parameter to match only the first 'n' items (#91)

Add count parameter to limit number of replacements

Adds an optional 4th parameter 'count' to limit replacements to the first N matches.

Resolves #45

Author: kieransimkin

index.d.ts

@@ -2,7 +2,8 @@ declare module "react-string-replace" {
   function reactStringReplace(
     text?: string | React.ReactNode[],
     regex?: string | RegExp,
-    cb?: (match: string, index: number, offset: number) => React.ReactNode
+    cb?: (match: string, index: number, offset: number) => React.ReactNode,
+    count?: number
   ): React.ReactNode[];
 
   export default reactStringReplace;

index.js

@@ -50,7 +50,7 @@ var flatten = function (array) {
  * @param {function} fn
  * @return {array}
  */
-function replaceString(str, match, fn) {
+function replaceString(str, match, fn, count = null) {
   var curCharStart = 0;
   var curCharLen = 0;
 
@@ -70,6 +70,11 @@ function replaceString(str, match, fn) {
 
   // Apply fn to all odd elements
   for (var i = 1, length = result.length; i < length; i += 2) {
+
+    if (Number.isInteger(count) && (count * 2 < i || count < 1)) {
+      break;
+    }
+    
     /** @see {@link https://github.com/iansinnott/react-string-replace/issues/74} */
     if (result[i] === undefined || result[i - 1] === undefined) {
       console.warn('reactStringReplace: Encountered undefined value during string replacement. Your RegExp may not be working the way you expect.');
@@ -85,10 +90,25 @@ function replaceString(str, match, fn) {
   return result;
 }
 
-module.exports = function reactStringReplace(source, match, fn) {
+module.exports = function reactStringReplace(source, match, fn, count = null) {
   if (!Array.isArray(source)) source = [source];
 
-  return flatten(source.map(function(x) {
-    return isString(x) ? replaceString(x, match, fn) : x;
-  }));
-};
+  return flatten(
+    source.map(function (x) {
+      let ret;
+      if (isString(x)) {
+        if (Number.isInteger(count) && count > 0) {
+          ret = replaceString(x, match, fn, count);
+          count -= (
+            x.match(new RegExp("(" + escapeRegExp(match) + ")", "gi")) || []
+          ).length
+        } else {
+          ret = replaceString(x, match, fn, count);
+        }
+      } else {
+        ret = x;
+      }
+      return ret;
+    }),
+  );
+}

readme.md

@@ -128,7 +128,7 @@ I wanted an easy way to do string replacement similar to `String.prototype.repla
 
 ## API
 
-### reactStringReplace(string, match, replacementFunction)
+### reactStringReplace(string, match, replacementFunction, count)
 
 #### string
 
@@ -163,6 +163,18 @@ const replacementFunction = (match, index, offset) => <span key={index}>{match}<
 reactStringReplace('hey hey you', /(hey)/g, replacementFunction);
 ```
 
+#### count
+
+Type: `number`
+
+The number of substitutions to perform - for example if `count` is 1, then only the first occurrence of the string will be replaced. 
+
+Example: Replace first occurrence of `'hey'` with `<span>hey</span>`
+
+```js
+reactStringReplace('hey hey you', 'hey', () => <span>hey</span>, 1)
+```
+
 ## API Stability
 
 With v1.0.0 the API is considered stable and should be considered production ready. Pull requests are still welcome but there is currently no intent to make changes to this lib other than bug fixes (please submit an issue if you find something!).

test.js

@@ -1,6 +1,7 @@
 /* eslint-disable import/no-extraneous-dependencies */
 import test from 'ava';
 import replaceString from './';
+import reactStringReplace from '.';
 
 test("Doesn't throw if not given invalid input", t => {
   t.notThrows(() => replaceString());
@@ -170,3 +171,17 @@ test("Avoids undefined values due to regex", (t) => {
     replaceString(string, /(hey)|(you)/, x => x);
   });
 });
+
+test("Fixed number of string replacements", (t) => { 
+  const string = `Test hey test hey test`;
+  const replacedContent = reactStringReplace(string, 'hey', match => { 
+    return 'lo';
+  },1);
+  t.deepEqual(replacedContent, [
+    'Test ',
+    'lo',
+    ' test ',
+    'hey',
+    ' test'
+  ])
+})