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
  48 section:: How it works
  49
  50 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).
  51
  52 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::.
  53
  54 code::
  55 p = Pbind(\degree, Pseq([4, Rest], 1)).asStream;
  56
  57 p.next(());
  58 // prints: ( 'degree': 4 )
  59
  60 p.next(());
  61 // prints: ( 'isRest': true, 'degree': 1 )
  62 ::
  63
  64 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.
  65
  66 CLASSMETHODS::
  67 All methods of Rest except *new are private, and should not be used directly.
  68
  69 private:: processRest
  70 private:: embedInStream
  71 private:: asStream
  72
  73 METHOD:: new
  74 Create an instance of Rest, with a value to be used in the resulting rest event.
  75
  76 argument:: dur
  77 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).
  78
  79
  80 INSTANCEMETHODS::
  81 private:: dur
  82 private:: processRest
  83 private:: embedInStream
  84 private:: asStream
  85
  86 EXAMPLES::
  87
  88 Using the Rest class in a pitch stream
  89
  90 code::
  91 p = Pbind(
  92         \degree, Pif(
  93                 0.1.loop.coin,
  94                 Rest,
  95                 Pseries(0, 1, inf).fold(-7, 7)
  96         ),
  97         \dur, 0.125
  98 ).play;
  99
 100 p.stop;
 101 ::
 102
 103 Using a Rest instance in a duration stream
 104 code::
 105 p = Pbind(
 106         \degree, Pseries(0, 1, inf).fold(-7, 7),
 107         \dur, Pseq([Pn(0.125, { rrand(3, 6) }), Rest(0.25)], inf)
 108 ).play;
 109
 110 p.stop;
 111 ::