HelpSource/Classes/Rest.schelp

   1 CLASS:: Rest
   2 summary:: Represents a rest in event patterns
   3 categories:: Streams-Patterns-Events
   4 related:: Classes/Pbind, Classes/Event
   5
   6 DESCRIPTION::
   7 Rest may be used in event patterns to indicate that the resulting event should be a rest (i.e., silent). It should be used in one of the child patterns belonging to a Pbind, for instance.
   8
   9 subsection:: Expressing rests in event patterns
  10
  11 In addition to the Rest class, rests can be specified in two other ways (legacy usages).
  12
  13 list::
  14 ## A link::Classes/Symbol:: may be specified in any frequency stream (under the keys degree, note, midinote or freq). The exception to this rule is control bus mapping symbols, beginning with 'c' followed by a number. Typical symbols that have been used include strong::\rest::, strong::\r:: and the empty symbol strong::\::.
  15
  16 code::
  17 p = Pbind(
  18         \degree, Pseq([
  19                 0, 1, 2, 0, 0, 1, 2, 0,
  20                 2, 3, 4, \rest, 2, 3, 4, \rest
  21         ]),
  22         \dur, 0.25
  23 ).play;
  24 ::
  25
  26 ## The event's strong::\type:: may be set to strong::\rest::.
  27
  28 code::
  29 p = Pbind(
  30         \degree, Pseries(0, 1, inf).fold(-7, 7),
  31         \dur, 0.125,
  32         \type, Pwrand([\note, \rest], [0.9, 0.1], inf)
  33 ).play;
  34
  35 p.stop;
  36 ::
  37 ::
  38
  39 The Rest class allows rests to be indicated in any stream, not only frequency or event type. Also, using the duration argument (see the *new method below), rests may be embedded into a duration stream. That is, rests may be treated as part of the rhythmic specification, rather than the pitch specification.
  40
  41 subsection:: Usage
  42
  43 list::
  44 ## The class Rest may be embedded directly in a child pattern. This sets the isRest flag and puts the number 1 into the event.
  45 ## Or, a Rest instance may be embedded. Rest.new's argument specifies the value that will be placed into the event. This allows rests to be given in a duration stream -- the argument is the rest's rhythmic value.
  46
  47 section:: How it works
  48
  49 When a Pbind child pattern returns a Rest, the Rest object sets a flag 'isRest' in the resulting event to be true. The child pattern's value in the event is a number. This is to prevent math errors if Rest is used in a pitch or duration stream (degree, note, midiNote, freq, dur, delta, stretch).
  50
  51 When a Rest is returned from a child stream, the rest object itself will not appear in the event. You can tell that the event is a rest by the presence of code::'isRest': true::.
  52
  53 code::
  54 p = Pbind(\degree, Pseq([4, Rest], 1)).asStream;
  55
  56 p.next(());
  57 // prints: ( 'degree': 4 )
  58
  59 p.next(());
  60 // prints: ( 'isRest': true, 'degree': 1 )
  61 ::
  62
  63 That is, the importance of the Rest object is not that it appears in the event. The importance is the side effect that this object has on the resulting event.
  64
  65 CLASSMETHODS::
  66 private:: processRest
  67 private:: embedInStream
  68 private:: asStream
  69
  70 All methods of Rest except *new are private, and should not be used directly.
  71
  72 METHOD:: new
  73 Create an instance of Rest, with a value to be used in the resulting rest event.
  74
  75 argument:: dur
  76 Typically, Rest instances will be used in duration streams, so the argument should be the rest's rhythmic value, or duration. Rest instances may also be used in any other stream, but the value will be ignored (since the event will do nothing except take time).
  77
  78
  79 INSTANCEMETHODS::
  80 private:: dur
  81 private:: processRest
  82 private:: embedInStream
  83 private:: asStream
  84
  85 EXAMPLES::
  86
  87 Using the Rest class in a pitch stream
  88
  89 code::
  90 p = Pbind(
  91         \degree, Pif(
  92                 0.1.loop.coin,
  93                 Rest,
  94                 Pseries(0, 1, inf).fold(-7, 7)
  95         ),
  96         \dur, 0.125
  97 ).play;
  98
  99 p.stop;
 100 ::
 101
 102 Using a Rest instance in a duration stream
 103 code::
 104 p = Pbind(
 105         \degree, Pseries(0, 1, inf).fold(-7, 7),
 106         \dur, Pseq([Pn(0.125, { rrand(3, 6) }), Rest(0.25)], inf)
 107 ).play;
 108
 109 p.stop;
 110 ::