Add removeMatch() and updateMatch()

Author: Vovan-VE

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.1.0 (2023-12-13)
+
+- Add: `removeMatch()` removes some items matching the given predicate. It's a
+  combination of `[].findIndex()` and `remove()` or `[].filter()` with inversion
+  and limit.
+- Add: `updateMatch()` updates some items matching the given predicate. It's a
+  combination of `[].map()` with limit.
+
 ## 1.0.0 (2022-06-25)
 
 - Initial release.

README.md

@@ -163,6 +163,38 @@ remove(input, 1, 2);  // => [10, 40]
 remove(input, 1, 10); // => [10]
 ```
 
+### `removeMatch()`
+
+```ts
+removeMatch<T>(
+  array:           readonly T[],
+  removePredicate: (value: T, index: number) => unknown,
+  limit:           number = 1,
+): readonly T[]
+```
+
+Remove items matching the given predicate
+
+Creates new array from the input `array` by *omitting* items *matching*
+predicate `removePredicate`. This is opposite to `Array.prototype.filter()`.
+
+Positive `limit` (defaults to `1`) will omit at most that number of items.
+Negative `limit` means "no limit".
+
+- Will return input `array` when it's nothing to change.
+
+```js
+const input = [10, 20, 30, 40];
+removeMatch(input, (v) => v % 20 === 0);
+// => [10, 30, 40]
+removeMatch(input, (v) => v % 10 === 0, 2);
+// => [30, 40]
+removeMatch(input, (v) => v % 2);
+// => [10, 20, 30, 40]
+removeMatch(input, (v) => v % 2 === 0, -1);
+// => []
+```
+
 ### `set()`
 
 ```ts
@@ -235,3 +267,35 @@ const input = [10, 20, 30, 40];
 update(input, 2, (v, i) => 1000 * i + v);
 // => [10, 20, 2030, 40]
 ```
+
+### `updateMatch()`
+
+```ts
+update(
+  array:     readonly T[],
+  predicate: (value: T, index: number) => T,
+  updater:   (prev: T, index: number) => T,
+  limit:     number = 1,
+): readonly T[]
+```
+
+Creates new array from input `array` with some item matching `predicate` (at
+most `limit`) updated by `updater`.
+
+Callbacks `predicate(value, index)` and `updater(prev, index)` will receive item
+value and index. The `predicate` returns whether the given item need be updated.
+The `updater` will be called for those items matched by `predicated` until
+`limit` exceeds.
+
+Positive `limit` (defaults to `1`) will update at most that number of items.
+Negative `limit` means "no limit".
+
+- `limit` applies to `predicate` only without care if some previous item was
+  actually changed by `updater`.
+- Will return input `array` when nothing to change (`===` check).
+
+```js
+const input = [10, 20, 30, 40];
+updateMatch(input, v => v % 20 === 0, (v, i) => 1000 * i + v);
+// => [10, 1020, 30, 40]
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubux/readonly-array",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Functions to work with read-only arrays",
   "keywords": [
     "array",

src/index.ts

@@ -1,6 +1,8 @@
 export { default as append } from './append';
 export { default as insert } from './insert';
 export { default as remove } from './remove';
+export { default as removeMatch } from './removeMatch';
 export { default as set } from './set';
 export { default as swap } from './swap';
 export { default as update } from './update';
+export { default as updateMatch } from './updateMatch';

src/removeMatch.ts

@@ -0,0 +1,62 @@
+/**
+ * Remove items matching the given predicate
+ *
+ * Creates new array from the input `array` by *omitting* items *matching*
+ * predicate `removePredicate`. This is opposite to `Array.prototype.filter()`.
+ *
+ * Positive `limit` (defaults to `1`) will omit at most that number of items.
+ * Negative `limit` means "no limit".
+ *
+ * - Will return input `array` when it's nothing to change.
+ *
+ * ```js
+ * const input = [10, 20, 30, 40];
+ * removeMatch(input, (v) => v % 20 === 0);
+ * // => [10, 30, 40]
+ * removeMatch(input, (v) => v % 10 === 0, 2);
+ * // => [30, 40]
+ * removeMatch(input, (v) => v % 2);
+ * // => [10, 20, 30, 40]
+ * removeMatch(input, (v) => v % 2 === 0, -1);
+ * // => []
+ * ```
+ *
+ * @param array Source array
+ * @param removePredicate A callback to check whether the item need be removed
+ * @param limit Limit number of items to remove
+ */
+function removeMatch<T>(
+  array: readonly T[],
+  removePredicate: (value: T, index: number) => unknown,
+  limit = 1,
+): readonly T[] {
+  if (limit === 0) {
+    return array;
+  }
+  const next: T[] = [];
+  for (let i = 0, L = array.length; i < L; i++) {
+    // here only previously positive became can become 0
+    if (limit === 0) {
+      // add all the rest and done
+      next.push(...array.slice(i));
+      break;
+    }
+
+    const value = array[i];
+    // if (limit < 0) t.i. no limit
+    // or (limit > 0) still
+    // positive limit will not reach 0 here
+    if (removePredicate(value, i)) {
+      // skip current item
+      // and reduce positive limit until 0
+      if (limit > 0) {
+        limit--;
+      }
+    } else {
+      next.push(value);
+    }
+  }
+  return next.length === array.length ? array : next;
+}
+
+export default removeMatch;

src/updateMatch.ts

@@ -0,0 +1,57 @@
+/**
+ * Update some matching items with a callback
+ *
+ * Creates new array from input `array` with some item matching `predicate` (at
+ * most `limit`) updated by `updater`.
+ *
+ * Callbacks `predicate(value, index)` and `updater(prev, index)` will receive
+ * item value and index. The `predicate` returns whether the given item need be
+ * updated. The `updater` will be called for those items matched by `predicated`
+ * until `limit` exceeds.
+ *
+ * Positive `limit` (defaults to `1`) will update at most that number of items.
+ * Negative `limit` means "no limit".
+ *
+ * - `limit` applies to `predicate` only without care if some previous item was
+ *   actually changed by `updater`.
+ * - Will return input `array` when nothing to change (`===` check).
+ *
+ * @param array Source array
+ * @param predicate Callback to check whether the item need be updated
+ * @param updater Callback to calculate new value
+ * @param limit Limit number of items to remove
+ */
+function updateMatch<T>(
+  array: readonly T[],
+  predicate: (value: T, index: number) => unknown,
+  updater: (prev: T, index: number) => T,
+  limit = 1,
+): readonly T[] {
+  if (limit === 0) {
+    return array;
+  }
+  const next = [...array];
+  let changed = false;
+  for (let i = 0, L = array.length; i < L; i++) {
+    // here only previously positive became can become 0
+    if (limit === 0) {
+      // done
+      break;
+    }
+
+    const value = array[i];
+    if (predicate(value, i)) {
+      const nextItem = updater(value, i);
+      if (nextItem !== value) {
+        next[i] = nextItem;
+        changed = true;
+      }
+      if (limit > 0) {
+        limit--;
+      }
+    }
+  }
+  return changed ? next : array;
+}
+
+export default updateMatch;

test/index.test.ts

@@ -1,11 +1,27 @@
-import { append, insert, remove, set, swap, update } from '../src';
+import {
+  append,
+  insert,
+  remove,
+  removeMatch,
+  set,
+  swap,
+  update,
+  updateMatch,
+} from '../src';
 
 it('direct', () => {
   expect(append([10, 20], 30, 40, 50)).toEqual([10, 20, 30, 40, 50]);
   expect(insert([10, 20, 30], 2, 40, 50)).toEqual([10, 20, 40, 50, 30]);
   expect(remove([10, 20, 30], 1)).toEqual([10, 30]);
-  expect(remove([10, 20, 30], 1)).toEqual([10, 30]);
+  expect(removeMatch([10, 20, 40], n => n % 20 === 0)).toEqual([10, 40]);
   expect(set([10, 20, 30, 40], 2, 42)).toEqual([10, 20, 42, 40]);
   expect(swap([10, 20, 30, 40], 0, 2)).toEqual([30, 20, 10, 40]);
   expect(update([10, 20, 30], 1, n => -n)).toEqual([10, -20, 30]);
+  expect(
+    updateMatch(
+      [2, 3, 5],
+      n => n % 2,
+      n => -n,
+    ),
+  ).toEqual([2, -3, 5]);
 });

test/removeMatch.test.ts

@@ -0,0 +1,15 @@
+import removeMatch from '../src/removeMatch';
+
+it('removeMatch', () => {
+  const input = [10, 20, 30, 40] as const;
+
+  expect(removeMatch(input, v => v % 20 === 0)).toEqual([10, 30, 40]);
+  expect(removeMatch(input, v => v % 20 === 0, -1)).toEqual([10, 30]);
+  expect(removeMatch(input, v => v % 10 === 0, 2)).toEqual([30, 40]);
+  expect(removeMatch(input, v => v % 2)).toBe(input);
+  expect(removeMatch(input, v => v % 2 === 0, -1)).toEqual([]);
+
+  expect(removeMatch(input, v => v % 2, 0)).toBe(input);
+
+  expect(input).toEqual([10, 20, 30, 40]);
+});

test/updateMatch.test.ts

@@ -0,0 +1,16 @@
+import updateMatch from '../src/updateMatch';
+
+it('updateMatch', () => {
+  const a = [10, 20, 30, 40] as const;
+  const inc = (n: number) => n + 1;
+
+  expect(updateMatch(a, v => v % 20 === 0, inc)).toEqual([10, 21, 30, 40]);
+  expect(updateMatch(a, v => v % 20 === 0, inc, -1)).toEqual([10, 21, 30, 41]);
+  expect(updateMatch(a, v => v % 10 === 0, inc, 2)).toEqual([11, 21, 30, 40]);
+  expect(updateMatch(a, v => v % 2, inc)).toBe(a);
+  expect(updateMatch(a, v => v % 2 === 0, inc, -1)).toEqual([11, 21, 31, 41]);
+
+  expect(updateMatch(a, v => v % 2, inc, 0)).toBe(a);
+
+  expect(a).toEqual([10, 20, 30, 40]);
+});