add filter + filterWhen + within

packages/core/pattern.mjs

@@ -2487,6 +2487,37 @@ Pattern.prototype.tag = function (tag) {
   return this.withContext((ctx) => ({ ...ctx, tags: (ctx.tags || []).concat([tag]) }));
 };
 
+/**
+ * Filters haps using the given function
+ * @name filter
+ * @param {Function} test function to test Hap
+ * @example
+ * s("hh!7 oh").filter(hap => hap.value.s==='hh')
+ */
+export const filter = register('filter', (test, pat) => pat.withHaps((haps) => haps.filter(test)));
+
+/**
+ * Filters haps by their begin time
+ * @name filterWhen
+ * @noAutocomplete
+ * @param {Function} test function to test Hap.whole.begin
+ */
+export const filterWhen = register('filterWhen', (test, pat) => pat.filter((h) => test(h.whole.begin)));
+
+/**
+ * Use within to apply a function to only a part of a pattern.
+ * @name within
+ * @param {number} start start within cycle (0 - 1)
+ * @param {number} end end within cycle (0 - 1). Must be > start
+ * @param {Function} func function to be applied to the sub-pattern
+ */
+export const within = register('within', (a, b, fn, pat) =>
+  stack(
+    fn(pat.filterWhen((t) => t.cyclePos() >= a && t.cyclePos() <= b)),
+    pat.filterWhen((t) => t.cyclePos() < a || t.cyclePos() > b),
+  ),
+);
+
 //////////////////////////////////////////////////////////////////////
 // Control-related functions, i.e. ones that manipulate patterns of
 // objects

test/__snapshots__/examples.test.mjs.snap

@@ -2560,6 +2560,43 @@ exports[`runs examples > example "fastGap" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "filter" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | s:hh ]",
+  "[ 1/8 → 1/4 | s:hh ]",
+  "[ 1/4 → 3/8 | s:hh ]",
+  "[ 3/8 → 1/2 | s:hh ]",
+  "[ 1/2 → 5/8 | s:hh ]",
+  "[ 5/8 → 3/4 | s:hh ]",
+  "[ 3/4 → 7/8 | s:hh ]",
+  "[ 7/8 → 1/1 | s:oh ]",
+  "[ 1/1 → 9/8 | s:hh ]",
+  "[ 9/8 → 5/4 | s:hh ]",
+  "[ 5/4 → 11/8 | s:hh ]",
+  "[ 11/8 → 3/2 | s:hh ]",
+  "[ 3/2 → 13/8 | s:hh ]",
+  "[ 13/8 → 7/4 | s:hh ]",
+  "[ 7/4 → 15/8 | s:hh ]",
+  "[ 15/8 → 2/1 | s:oh ]",
+  "[ 2/1 → 17/8 | s:hh ]",
+  "[ 17/8 → 9/4 | s:hh ]",
+  "[ 9/4 → 19/8 | s:hh ]",
+  "[ 19/8 → 5/2 | s:hh ]",
+  "[ 5/2 → 21/8 | s:hh ]",
+  "[ 21/8 → 11/4 | s:hh ]",
+  "[ 11/4 → 23/8 | s:hh ]",
+  "[ 23/8 → 3/1 | s:oh ]",
+  "[ 3/1 → 25/8 | s:hh ]",
+  "[ 25/8 → 13/4 | s:hh ]",
+  "[ 13/4 → 27/8 | s:hh ]",
+  "[ 27/8 → 7/2 | s:hh ]",
+  "[ 7/2 → 29/8 | s:hh ]",
+  "[ 29/8 → 15/4 | s:hh ]",
+  "[ 15/4 → 31/8 | s:hh ]",
+  "[ 31/8 → 4/1 | s:oh ]",
+]
+`;
+
 exports[`runs examples > example "firstOf" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:g3 ]",