1CLASS:: Rest 2summary:: Represents a rest in event patterns 3categories:: Streams-Patterns-Events 4related:: Classes/Pbind, Classes/Event, Classes/AbstractFunction 5 6DESCRIPTION:: 7A 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 9code:: 10// do nothing for 2 seconds 11(note:Rest(), dur:2).play; 12 13// intersperse pauses in pattern 14Pbind(\note, Pseq([0, 4, 7, 11], inf), \dur, Pseq([2, 1, Rest(1)], inf) / 5).play; 15:: 16 17subsection:: Expressing rests in event patterns 18 19The Rest class allows rests to be indicated in any stream, not only frequency or event type. Also, using the duration argument (see the link::#*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. 20 21 22note:: 23As of SuperCollider 3.9, code::Rest::'s behavior has changed to be more intuitive. Note that you have to now use code::Rest():: - the shortcut of code::Rest:: as class directly is strong::not supported:: anymore. 24:: 25 26 27subsection:: Usage 28 29list:: 30## link::Classes/Event#-isRest:: checks every item in the event to see if it meets the condition to be a rest: it may be a code::Rest:: instance, the code::Rest:: class, or either of the symbols code:: \ :: or code::\r::. If any item meets the condition, the event will be considered a rest and it will not take action when played. 31 32## If a Pbind child pattern yields a Rest object, the Rest is placed directly into the event. This is a change of behavior from 3.8. 33 34## If a Rest object has a value, it will respond to math operations: code::Rest(1) * 2 == Rest(2)::. 35:: 36 37 38CLASSMETHODS:: 39All methods of Rest except *new are private, and should not be used directly. 40 41private:: processRest 42private:: embedInStream 43private:: asStream 44 45METHOD:: new 46Create an instance of Rest, with a value to be used in the resulting rest event. 47 48argument:: value 49The Rest instance's numeric value, to be used in math operations. Note that a Rest's value is ignored for most Event keys (assuming the Event does nothing in response to code::.play::). If a Rest appears in a rhythm key (code::dur:: or code::delta::), then the number is the time until the next event. Consequently, numeric Rests are often used for duration -- but there is no requirement that a Rest's value must be a duration. 50 51discussion:: 52code:: 53a = Rest(6); 54b = a * 2; // returns Rest(12) 55b = 2 * a; // the same 56b.value; // returns 12 57:: 58 59The rest of a rest is always a rest. This idempotence is implemented by Rest's superclass link::Classes/Operand::. 60code:: 61Rest(Rest(1)) // returns Rest(1) 62:: 63 64 65INSTANCEMETHODS:: 66private:: dur 67private:: embedInStream 68private:: asStream 69private:: asControlInput 70private:: playAndDelta 71 72METHOD:: isRest 73returns true 74 75METHOD::unwrapBoolean 76returns the value. 77discussion:: 78This method implements the following behavior. 79code:: 80Rest(6) + 1 // Rest(7) 81Rest(true) // true 82:: 83This makes comparisons work: 84code:: 85Rest(6) < 7 // true, and not Rest(true) 86a = Pseq([1, 2, 1, 3, Rest(1), 2, Rest(3)], inf); // e.g. as a duration pattern 87b = a.collect { |x| if(x > 2) { x / 2 } { x } }; 88b.asStream.nextN(8) 89:: 90 91EXAMPLES:: 92 93 94Using Rest instances in a pitch stream 95 96code:: 97( 98Pbind( 99 \degree, Pif( 100 0.1.loop.coin, 101 Pseq([Rest(), 7], inf), // every second is a Rest 102 Pseries(0, 1, inf).fold(-7, 7) 103 ), 104 \dur, 0.125 105).play 106) 107:: 108 109Using a Rest instance in a duration stream 110code:: 111( 112Pbind( 113 \degree, Pseries(0, 1, inf).fold(-7, 7), 114 \dur, Pseq([Pn(0.125, { rrand(3, 6) }), Rest(0.25)], inf) 115).play 116) 117:: 118 119 120subsection:: Alternatives to Rest 121 122In addition to Rest, in events, rests can be specified in two other ways (legacy usages). 123 124list:: 125## 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:: \ ::. 126 127code:: 128p = Pbind( 129 \degree, Pseq([ 130 0, 1, 2, 0, 0, 1, 2, 0, 131 2, 3, 4, \rest, 2, 3, 4, \rest 132 ]), 133 \dur, 0.25 134).play; 135:: 136 137## The event's strong::\type:: may be set to strong::\rest::. 138 139code:: 140p = Pbind( 141 \degree, Pseries(0, 1, inf).fold(-7, 7), 142 \dur, 0.125, 143 \type, Pwrand([\note, \rest], [0.9, 0.1], inf) 144).play; 145 146p.stop; 147:: 148:: 149