rotation

[Class]
  `rotation`

Permutes elements according to one or more rotational descriptions. A rotation is a list of (up to) four integers that controls an iterative "swapping" process that is mapped over all the data to produce the next permutation:

> `(`start step width [end`])`

Start is the starting index (zero based) in the pattern's data for swapping to begin, step is the stepping increment between swaps, width is the distance between the elements to swap, and end is the position (inclusive) in the data to stop swapping at. The default rotation list is (0 1 1), causes elements in the pattern to rotate leftward, as shown in Table 1.

Table 1. Permutations of A B C using (0 1 1) as the rotation. Lower case letters indicate an intermediate step in the rotation and the _ marks the swap at each step.

Permutation | Swap #1 | Swap #2
--- | --- | ---
A B C | b_a c | b c_a
B C A | c_b a | c a_b
C A B | a_c b | a b_c
A B C | ... |

`rotation` supports the following slot initializations:

`:rotations` { list | pattern }
  The rotation list or pattern that produces rotation lists.

See generic pattern initializations for documentation on additional keyword initializations to the pattern.

#### Examples:

Example 1. The rotation pattern.

    (define pat1 (new rotation :of '(a b c d) :rotations '(0 2 1 3)))

    (next pat1 #t)
    ⇒ (a b c d)
    (next pat1 #t)
    ⇒ (b a d c)
    (next pat1 #t)
    ⇒ (a b d c)

    (define pat1
      (new rotation :of '(a b c d)
           :rotations (new cycle :of '((0 1 2) (1 1 2)))))

    (loop repeat 5 collect (next pat1 #t))
    ⇒ ((a b c d) (c d a b) (c b a d) (a d c b) (a b c d))

Example 2. Rotating a descending whole-tone figure with fixed notes.

    (define pat1
       (new rotation
            :notes `(, (new range :by -2 :initially (keynum 'c6))
                       b3 f4 g5 ef6)
            :rotations (new cycle :of '((0 1 1) (0 1 2)))))

    (define (play-pat reps pat rate)
      (process repeat reps
               for n = (next pat)
               output (new midi :time (now)
                           :amplitude (if (symbol? n) .35 .7)
                           :keynum n
                           :duration (if (symbol? n)
                                         (* rate 2.5)
                                         (* rate 4)))
               wait rate))

    (events (play-pat 69 pat1 .5) "test.mid")
    ⇒ "test.mid"

The file cring.cm contains example rotations that implement different change ringing sequences developed by English church bell ringers.

#### See also:

- Pattern classes [Topic]