Merge pull request #508 from tidalcycles/arrange

add arrange function

packages/core/pattern.mjs

@@ -1284,6 +1284,20 @@ export function timeCat(...timepats) {
   return stack(...pats);
 }
 
+/**
+ * Allows to arrange multiple patterns together over multiple cycles.
+ * Takes a variable number of arrays with two elements specifying the number of cycles and the pattern to use.
+ *
+ * @return {Pattern}
+ * @example
+ * arrange([4, "<c a f e>(3,8)"],[2, "<g a>(5,8)"]).note()
+ */
+export function arrange(...sections) {
+  const total = sections.reduce((sum, [cycles]) => sum + cycles, 0);
+  sections = sections.map(([cycles, section]) => [cycles, section.fast(cycles)]);
+  return timeCat(...sections).slow(total);
+}
+
 export function fastcat(...pats) {
   return slowcat(...pats)._fast(pats.length);
 }

test/__snapshots__/examples.test.mjs.snap

@@ -848,6 +848,23 @@ exports[`runs examples > example "arpWith" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "arrange" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | note:c ]",
+  "[ 3/8 → 1/2 | note:c ]",
+  "[ 3/4 → 7/8 | note:c ]",
+  "[ 1/1 → 9/8 | note:a ]",
+  "[ 11/8 → 3/2 | note:a ]",
+  "[ 7/4 → 15/8 | note:a ]",
+  "[ 2/1 → 17/8 | note:f ]",
+  "[ 19/8 → 5/2 | note:f ]",
+  "[ 11/4 → 23/8 | note:f ]",
+  "[ 3/1 → 25/8 | note:e ]",
+  "[ 27/8 → 7/2 | note:e ]",
+  "[ 15/4 → 31/8 | note:e ]",
+]
+`;
+
 exports[`runs examples > example "attack" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | note:c3 attack:0 ]",

website/src/pages/learn/factories.mdx

@@ -49,6 +49,10 @@ As a chained function:
 
 <JsDoc client:idle name="timeCat" h={0} />
 
+## arrange
+
+<JsDoc client:idle name="arrange" h={0} />
+
 ## polymeter
 
 <JsDoc client:idle name="polymeter" h={0} />