Help/Language/Control-Structures.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.44">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Courier}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #000000}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000; min-height: 12.0px}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
  20 p.p11 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Courier; min-height: 14.0px}
  21 p.p12 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #000000; min-height: 14.0px}
  22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  23 p.p14 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Monaco; color: #000000; min-height: 14.0px}
  24 p.p15 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Monaco; min-height: 14.0px}
  25 p.p16 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica; min-height: 22.0px}
  26 span.s1 {color: #002bfe}
  27 span.s2 {color: #000000}
  28 span.s3 {color: #0000bf}
  29 span.s4 {color: #bf0000}
  30 span.s5 {font: 12.0px Monaco}
  31 span.s6 {color: #606060}
  32 span.s7 {color: #007300}
  33 span.s8 {font: 9.0px Monaco}
  34 span.s9 {font: 9.0px Monaco; color: #0000bf}
  35 span.Apple-tab-span {white-space:pre}
  36 </style>
  37 </head>
  38 <body>
  39 <p class="p1"><b>Control Structures</b></p>
  40 <p class="p2"><br></p>
  41 <p class="p3">Control structures in SuperCollider are implemented via message sends. Here are a few of those available.<span class="Apple-converted-space"> </span></p>
  42 <p class="p3">See <a href="Syntax-Shortcuts.html"><span class="s1">Syntax-Shortcuts</span></a> for the various ways expressions can be written.</p>
  43 <p class="p2"><br></p>
  44 <p class="p2"><br></p>
  45 <p class="p2"><br></p>
  46 <p class="p1"><b>If</b></p>
  47 <p class="p2"><br></p>
  48 <p class="p3">Conditional execution is implemented via the <b>if</b> message. The <b>if</b> message is sent to an expression which must return a Boolean value. In addition it takes two arguments: a function to execute if the expression is true and another optional function to execute if the expression is false. The <b>if</b> message returns the value of the function which is executed. If the falseFunc is not present and the expression is false then the result of the <b>if</b> message is nil.</p>
  49 <p class="p2"><br></p>
  50 <p class="p3">syntax:</p>
  51 <p class="p2"><br></p>
  52 <p class="p4">if (expr, trueFunc, falseFunc);</p>
  53 <p class="p4">..or..</p>
  54 <p class="p4">expr.if (trueFunc, falseFunc);</p>
  55 <p class="p2"><br></p>
  56 <p class="p2"><br></p>
  57 <p class="p5">see also: the<b> </b><a href="../Core/if.html">if</a><b> helpfile</b></p>
  58 <p class="p2"><br></p>
  59 <p class="p3">examples:</p>
  60 <p class="p2"><br></p>
  61 <p class="p6"><span class="s2">if ( [</span><span class="s3">false</span><span class="s2">, </span><span class="s3">true</span><span class="s2">].choose,<span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>// Boolean expression (chooses one at random)</p>
  62 <p class="p7"><span class="s2"><span class="Apple-tab-span">    </span>{ </span>"expression was true"<span class="s2">.postln },<span class="Apple-tab-span">   </span></span><span class="s4">// true function</span></p>
  63 <p class="p7"><span class="s2"><span class="Apple-tab-span">    </span>{ </span>"expression was false"<span class="s2">.postln }<span class="Apple-tab-span">   </span></span><span class="s4">// false function</span></p>
  64 <p class="p8">)</p>
  65 <p class="p9"><br></p>
  66 <p class="p8">(</p>
  67 <p class="p8"><span class="s3">var</span> a = 1, z;</p>
  68 <p class="p8">z = if (a &lt; 5, { 100 },{ 200 });</p>
  69 <p class="p8">z.postln;</p>
  70 <p class="p8">)</p>
  71 <p class="p9"><br></p>
  72 <p class="p8">(</p>
  73 <p class="p8"><span class="s3">var</span> x;</p>
  74 <p class="p8">if (x.isNil, { x = 99 });</p>
  75 <p class="p8">x.postln;</p>
  76 <p class="p8">)</p>
  77 <p class="p10"><br></p>
  78 <p class="p3"><span class="s5">'</span>If' expressions are optimized (i.e. inlined) by the compiler if they do not contain variable declarations in the trueFunc and the falseFunc.</p>
  79 <p class="p2"><br></p>
  80 <p class="p2"><br></p>
  81 <p class="p2"><br></p>
  82 <p class="p2"><br></p>
  83 <p class="p2"><br></p>
  84 <p class="p1"><b>While</b></p>
  85 <p class="p2"><br></p>
  86 <p class="p3">The <b>while</b> message implements conditional execution of a loop. If the testFunc answers true when evaluated, then the bodyFunc is evaluated and the process is repeated. Once the testFunc returns false, the loop terminates.</p>
  87 <p class="p2"><br></p>
  88 <p class="p3">syntax:</p>
  89 <p class="p2"><br></p>
  90 <p class="p4">while ( testFunc, bodyFunc );</p>
  91 <p class="p4">..or..</p>
  92 <p class="p4">testFunc.while( bodyFunc );</p>
  93 <p class="p2"><br></p>
  94 <p class="p3">example:</p>
  95 <p class="p2"><br></p>
  96 <p class="p8">(</p>
  97 <p class="p8">i = 0;</p>
  98 <p class="p8">while ( { i &lt; 5 }, { i = i + 1; <span class="s6">"boing"</span>.postln });</p>
  99 <p class="p8">)</p>
 100 <p class="p10"><br></p>
 101 <p class="p3"><span class="s5">'</span>While' expressions are optimized by the compiler if they do not contain variable declarations in the testFunc and the bodyFunc.</p>
 102 <p class="p2"><br></p>
 103 <p class="p2"><br></p>
 104 <p class="p2"><br></p>
 105 <p class="p1"><b>For</b></p>
 106 <p class="p2"><br></p>
 107 <p class="p3">The <b>for</b> message implements iteration over an integer series from a starting value to an end value stepping by one each time. A function is evaluated each iteration and is passed the iterated numeric value as an argument.</p>
 108 <p class="p2"><br></p>
 109 <p class="p3">syntax:</p>
 110 <p class="p2"><br></p>
 111 <p class="p4">for ( startValue, endValue, function )</p>
 112 <p class="p4">..or..</p>
 113 <p class="p4">startValue.for ( endValue, function )</p>
 114 <p class="p2"><br></p>
 115 <p class="p3">example:</p>
 116 <p class="p2"><br></p>
 117 <p class="p8">for (3, 7, { <span class="s3">arg</span> i; i.postln }); <span class="s4">// prints values 3 through 7</span></p>
 118 <p class="p10"><br></p>
 119 <p class="p10"><br></p>
 120 <p class="p10"><br></p>
 121 <p class="p1"><b>ForBy</b></p>
 122 <p class="p2"><br></p>
 123 <p class="p3">The <b>forBy</b> selector implements iteration over an integer series with a variable step size. A function is evaluated each iteration and is passed the iterated numeric value as an argument.</p>
 124 <p class="p2"><br></p>
 125 <p class="p3">syntax:</p>
 126 <p class="p2"><br></p>
 127 <p class="p4">forBy ( startValue, endValue, stepValue, function );</p>
 128 <p class="p4">..or..</p>
 129 <p class="p4">startValue.forBy ( endValue, stepValue, function );</p>
 130 <p class="p11"><br></p>
 131 <p class="p2"><br></p>
 132 <p class="p3">example:</p>
 133 <p class="p2"><br></p>
 134 <p class="p8">forBy (0, 8, 2, { <span class="s3">arg</span> i; i.postln }); <span class="s4">// prints values 0 through 8 by 2's</span></p>
 135 <p class="p2"><br></p>
 136 <p class="p2"><br></p>
 137 <p class="p2"><br></p>
 138 <p class="p1"><b>Do</b></p>
 139 <p class="p2"><br></p>
 140 <p class="p3"><b>Do</b> is used to iterate over a collection. Positive Integers also respond to 'do' by iterating from zero up to their value. Collections iterate, calling the function for each object they contain. Other kinds of Objects respond to do by passing themselves to the function one time. The function is called with two arguments, the item, and an iteration counter.</p>
 141 <p class="p2"><br></p>
 142 <p class="p3">syntax:</p>
 143 <p class="p2"><br></p>
 144 <p class="p4">do ( collection, function )</p>
 145 <p class="p4">..or..</p>
 146 <p class="p4">collection.do(function)</p>
 147 <p class="p11"><br></p>
 148 <p class="p3">example:</p>
 149 <p class="p2"><br></p>
 150 <p class="p8">[ 1, 2, <span class="s6">"abc"</span>, (3@4) ].do({ <span class="s3">arg</span> item, i; [i, item].postln; });</p>
 151 <p class="p9"><br></p>
 152 <p class="p8">5.do({ <span class="s3">arg</span> item; item.postln }); <span class="s4">// iterates from zero to four</span></p>
 153 <p class="p9"><br></p>
 154 <p class="p6"><span class="s6">"you"</span><span class="s2">.do({ </span><span class="s3">arg</span><span class="s2"> item; item.postln }); </span>// a String is a collection of characters</p>
 155 <p class="p9"><br></p>
 156 <p class="p6"><span class="s7">'they'</span><span class="s2">.do({ </span><span class="s3">arg</span><span class="s2"> item; item.postln }); </span>// a Symbol is a singular item</p>
 157 <p class="p9"><br></p>
 158 <p class="p8">(8..20).do({ <span class="s3">arg</span> item; item.postln }); <span class="s4">// iterates from eight to twenty<span class="Apple-converted-space"> </span></span></p>
 159 <p class="p9"><br></p>
 160 <p class="p6"><span class="s2">(8,10..20).do({ </span><span class="s3">arg</span><span class="s2"> item; item.postln }); </span>// iterates from eight to twenty, with stepsize two</p>
 161 <p class="p9"><br></p>
 162 <p class="p8"><span class="s3">Routine</span>({ <span class="s3">var</span> i=10; while { i &gt; 0 } { i.yield; i = i - 5.0.rand } }).do({ <span class="s3">arg</span> item; item.postln });</p>
 163 <p class="p12"><br></p>
 164 <p class="p5"><b>Note:</b> The syntax (8..20).do uses an optimization to avoid generating an array that is used only for iteration (but which would be discarded thereafter). The return value of <span class="s8">(8..20).do({ </span><span class="s9">|item|</span><span class="s8"> item.postln })</span> is 8, the starting value.</p>
 165 <p class="p12"><br></p>
 166 <p class="p5"><span class="s8">(8..20) do: { </span><span class="s9">|item|</span><span class="s8"> item.postln }</span> is not optimized, and returns the array.</p>
 167 <p class="p12"><br></p>
 168 <p class="p12"><br></p>
 169 <p class="p1"><b>Switch</b></p>
 170 <p class="p2"><br></p>
 171 <p class="p3">Object implements a <b>switch </b>method which allows for conditional evaluation with multiple cases. These are implemented as pairs of test objects (tested using if this == test.value) and corresponding functions to be evaluated if true. The switch statement will be inlined if the test objects are all Floats, Integers, Symbols, Chars, nil, false, true and if the functions have no variable or argument declarations. The inlined switch uses a hash lookup (which is faster than nested if statements), so it should be very fast and scale to any number of clauses.</p>
 172 <p class="p2"><br></p>
 173 <p class="p13"><br></p>
 174 <p class="p8">(</p>
 175 <p class="p6"><span class="s3">var</span><span class="s2"> x=0; </span>//also try 1</p>
 176 <p class="p8">switch(x,0,{<span class="s6">"hello"</span>}, 1, {<span class="s6">"goodbye"</span>})</p>
 177 <p class="p8">)</p>
 178 <p class="p9"><br></p>
 179 <p class="p9"><br></p>
 180 <p class="p8">(</p>
 181 <p class="p8"><span class="s3">var</span> x, z;</p>
 182 <p class="p8">z = [0, 1, 1.1, 1.3, 1.5, 2];</p>
 183 <p class="p8">switch (z.choose.postln,</p>
 184 <p class="p8"><span class="Apple-tab-span">     </span>1, <span class="Apple-converted-space">  </span>{ <span class="s7">\no</span> },</p>
 185 <p class="p8"><span class="Apple-tab-span">     </span>1.1, { <span class="s7">\wrong</span> },</p>
 186 <p class="p8"><span class="Apple-tab-span">     </span>1.3, { <span class="s7">\wrong</span> },</p>
 187 <p class="p8"><span class="Apple-tab-span">     </span>1.5, { <span class="s7">\wrong</span> },</p>
 188 <p class="p8"><span class="Apple-tab-span">     </span>2, <span class="Apple-converted-space">  </span>{ <span class="s7">\wrong</span> },</p>
 189 <p class="p8"><span class="Apple-tab-span">     </span>0, <span class="Apple-converted-space">  </span>{ <span class="s7">\true</span> }</p>
 190 <p class="p8">).postln;</p>
 191 <p class="p8">)</p>
 192 <p class="p14"><br></p>
 193 <p class="p5">or:</p>
 194 <p class="p14"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></p>
 195 <p class="p8">(</p>
 196 <p class="p8"><span class="s3">var</span> x, z;</p>
 197 <p class="p8">z = [0, 1, 1.1, 1.3, 1.5, 2];</p>
 198 <p class="p8">x = switch (z.choose)</p>
 199 <p class="p8"><span class="Apple-tab-span">     </span>{1} <span class="Apple-converted-space">  </span>{ <span class="s7">\no</span> }</p>
 200 <p class="p8"><span class="Apple-tab-span">     </span>{1.1} { <span class="s7">\wrong</span> }</p>
 201 <p class="p8"><span class="Apple-tab-span">     </span>{1.3} { <span class="s7">\wrong</span> }</p>
 202 <p class="p8"><span class="Apple-tab-span">     </span>{1.5} { <span class="s7">\wrong</span> }</p>
 203 <p class="p8"><span class="Apple-tab-span">     </span>{2} <span class="Apple-converted-space">  </span>{ <span class="s7">\wrong</span> }</p>
 204 <p class="p8"><span class="Apple-tab-span">     </span>{0} <span class="Apple-converted-space">  </span>{ <span class="s7">\true</span> };</p>
 205 <p class="p8">x.postln;</p>
 206 <p class="p8">)</p>
 207 <p class="p15"><br></p>
 208 <p class="p1"><b>Case</b></p>
 209 <p class="p15"><br></p>
 210 <p class="p3">Function implements a <b>case </b>method which allows for conditional evaluation with multiple cases. Since the receiver represents the first case this can be simply written as pairs of test functions and corresponding functions to be evaluated if true. Case is inlined and is therefore just as efficient as nested if statements.</p>
 211 <p class="p15"><br></p>
 212 <p class="p8">(</p>
 213 <p class="p8"><span class="s3">var</span> i, x, z;</p>
 214 <p class="p8">z = [0, 1, 1.1, 1.3, 1.5, 2];</p>
 215 <p class="p8">i = z.choose;</p>
 216 <p class="p8">x = case</p>
 217 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 1 } <span class="Apple-converted-space">  </span>{ <span class="s7">\no</span> }</p>
 218 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 1.1 } { <span class="s7">\wrong</span> }</p>
 219 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 1.3 } { <span class="s7">\wrong</span> }</p>
 220 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 1.5 } { <span class="s7">\wrong</span> }</p>
 221 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 2 } <span class="Apple-converted-space">  </span>{ <span class="s7">\wrong</span> }</p>
 222 <p class="p8"><span class="Apple-tab-span">     </span>{ i == 0 } <span class="Apple-converted-space">  </span>{ <span class="s7">\true</span> };</p>
 223 <p class="p8">x.postln;</p>
 224 <p class="p8">)</p>
 225 <p class="p16"><br></p>
 226 <p class="p16"><br></p>
 227 <p class="p1"><b>Other Control Structures</b></p>
 228 <p class="p2"><br></p>
 229 <p class="p3">Using Functions, many control structures can be defined like the ones above. In the class <b>Collection</b> there are many more messages defined for iterating over Collections.</p>
 230 <p class="p2"><br></p>
 231 </body>
 232 </html>