range

[Class]
  `range`

Generates numbers from an iterative description.

`range` supports the following slot initializations:

`:from` {number | pattern}
  The starting value to return from the range. The starting value is reset each time it exceeds range boundaries or, if the range is unbounded, once each period of the pattern. The default value is 0.
`:initially` {number}
  Sets the starting value for the iteration one time and then never resets it. Only appropriate if the range has no upper or lower boundary.
`:to` {number | pattern}
  An optional inclusive upper bound on the range. If this value is exceeded then the range is reset to its starting value.
`:below` {number | pattern}
  Like `:to` except that the upper bound is exclusive.
`:downto` {number | pattern}
  An optional inclusive lower bound on the range. If this value is exceeded then the range is reset to its starting value.
`:above` {number | pattern}
  Like `:downto` except that the lower bound is exclusive.
`:by` {number | pattern}
  The increment to step between numbers in the range. If the value is a pattern a new increment will be reselected whenever the starting value is reset.
`:stepping` {pattern}
  Like `:by` except that a increment is reselected from pattern each time.

For bounded ranges the default period length is the number of values generated in the bounded iteration. For unbounded ranges the default period length is 1. Note that a range may contain both upper and lower boundaries. Combining these with a random `:stepping` pattern implements bounded random walks.

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

#### Examples:

Example 1. The range pattern.

    (define pat1 (new range :below 10))

    (next pat1 20)
    ⇒ (0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9)

    (define pat1
      (new range :from (new cycle :of '(60 74))
                 :downto 48
                 :by (new cycle :of '(1 2 3))
                 :repeat 6))

    (define (play-pat pat rate)
      (process for k = (next pat)
               until (eod? pat)
               output (new midi :time (now)
                           :keynum k
                           :duration (* rate 1.5))
               wait rate))

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

Example 2. Melody generated by bounded random walk with whole steps most prevalent.

    (define pat1
      (new range :from 60
           :to 72 :downto 48
           :stepping (new random
                          :of '((-2 :weight 1.5 :max 3)
                                ( 2 :weight 1.5 :max 3)
                                  1
                                 -1
                                ( 3 :weight .75 :max 1)
                                (-3 :weight .75 :max 1)))))

    (define (play-pat reps pat rate)
      (process repeat reps
               for k = (next pat)
               output (new midi :time (now)
                           :keynum k
                           :duration (* rate 1.5))
               wait rate))

    (events (play-pat 80 pat1 .2) "test.mid")
    ⇒ "test.mid"

#### See also:

- Pattern classes [Topic]