HelpSource/Reference/Control-Structures.schelp

   1 title::Control Structures
   2 summary:: flow control
   3 categories:: Language
   4 related:: Classes/Boolean
   5
   6 Control structures in SuperCollider are implemented via message sends. Here are a few of those available.
   7 See link::Reference/Syntax-Shortcuts:: for the various ways expressions can be written.
   8
   9 section:: Basic Control Structures
  10
  11 method:: if
  12
  13 Conditional execution is implemented via the code::if:: message. The code::if:: message is sent to an expression which must return a link::Classes/Boolean:: value.
  14 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 code::if:: 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 if message is nil.
  15
  16 discussion::
  17 Syntax
  18 code::
  19 if (expr, trueFunc, falseFunc);
  20 ::
  21 --or--
  22 code::
  23 expr.if (trueFunc, falseFunc);
  24 ::
  25
  26 Examples
  27 code::
  28 if ( [false, true].choose,                              // Boolean expression (chooses one at random)
  29         { "expression was true".postln },       // true function
  30         { "expression was false".postln }       // false function
  31 )
  32
  33 (
  34 var a = 1, z;
  35 z = if (a < 5, { 100 },{ 200 });
  36 z.postln;
  37 )
  38
  39 (
  40 var x;
  41 if (x.isNil, { x = 99 });
  42 x.postln;
  43 )
  44 ::
  45
  46
  47
  48 method:: while
  49
  50 The while 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.
  51
  52 discussion::
  53 Syntax
  54 code::
  55 while ( testFunc, bodyFunc );
  56 ::
  57 --or--
  58 code::
  59 testFunc.while( bodyFunc );
  60 ::
  61
  62 Example
  63 code::
  64 (
  65 i = 0;
  66 while ( { i < 5 }, { i = i + 1; "boing".postln });
  67 )
  68 ::
  69
  70 while expressions are also optimized by the compiler if they do not contain variable declarations in the testFunc and the bodyFunc.
  71
  72
  73 method:: for
  74
  75 The for 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.
  76
  77 discussion::
  78 Syntax
  79 code::
  80 for ( startValue, endValue, function )
  81 ::
  82 --or--
  83 code::
  84 startValue.for ( endValue, function )
  85 ::
  86
  87 Example
  88 code::
  89 for (3, 7, { arg i; i.postln }); // prints values 3 through 7
  90 ::
  91
  92 method:: forBy
  93
  94 The forBy 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.
  95
  96 discussion::
  97 Syntax
  98 code::
  99 forBy ( startValue, endValue, stepValue, function );
 100 ::
 101 --or--
 102 code::
 103 startValue.forBy ( endValue, stepValue, function );
 104 ::
 105
 106 Example
 107 code::
 108 forBy (0, 8, 2, { arg i; i.postln }); // prints values 0 through 8 by 2's
 109 ::
 110
 111
 112 method:: do
 113
 114 Do is used to iterate over a link::Classes/Collection::. Positive Integers also respond to code::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.
 115
 116 discussion::
 117 Syntax
 118 code::
 119 do ( collection, function )
 120 ::
 121 --or--
 122 code::
 123 collection.do(function)
 124 ::
 125
 126 Example
 127 code::
 128 [ 1, 2, "abc", (3@4) ].do({ arg item, i; [i, item].postln; });
 129
 130 5.do({ arg item; item.postln }); // iterates from zero to four
 131
 132 "you".do({ arg item; item.postln }); // a String is a collection of characters
 133
 134 'they'.do({ arg item; item.postln }); // a Symbol is a singular item
 135
 136 (8..20).do({ arg item; item.postln }); // iterates from eight to twenty
 137
 138 (8,10..20).do({ arg item; item.postln }); // iterates from eight to twenty, with stepsize two
 139
 140 Routine({ var i=10; while { i > 0 } { i.yield; i = i - 5.0.rand } }).do({ arg item; item.postln });
 141 ::
 142
 143 Note:: The syntax code::(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 code:: (8..20).do({ |item| item.postln }) :: is 8, the starting value.
 144 code::
 145 (8..20) do: { |item| item.postln } // is not optimized, and returns the array.
 146 ::
 147 ::
 148
 149 method:: switch
 150
 151 Object implements a switch 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.
 152 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.
 153
 154 discussion::
 155 Syntax
 156 code::
 157 switch (value,
 158         testvalue1, trueFunction1,
 159         testvalue2, trueFunction2,
 160         ...
 161         testvalueN, trueFunctionN,
 162         defaultFunction);
 163 ::
 164
 165 Examples
 166 code::
 167 (
 168 var x=0; //also try 1
 169 switch(x,0,{"hello"}, 1, {"goodbye"})
 170 )
 171
 172 (
 173 var x, z;
 174 z = [0, 1, 1.1, 1.3, 1.5, 2];
 175 switch (z.choose.postln,
 176         1,   { \no },
 177         1.1, { \wrong },
 178         1.3, { \wrong },
 179         1.5, { \wrong },
 180         2,   { \wrong },
 181         0,   { \true }
 182 ).postln;
 183 )
 184 ::
 185 or:
 186 code::
 187 (
 188 var x, z;
 189 z = [0, 1, 1.1, 1.3, 1.5, 2];
 190 x = switch (z.choose)
 191         {1}   { \no }
 192         {1.1} { \wrong }
 193         {1.3} { \wrong }
 194         {1.5} { \wrong }
 195         {2}   { \wrong }
 196         {0}   { \true };
 197 x.postln;
 198 )
 199 ::
 200
 201 method:: case
 202
 203 Function implements a case 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.
 204 discussion::
 205 Example
 206 code::
 207 (
 208 var i, x, z;
 209 z = [0, 1, 1.1, 1.3, 1.5, 2];
 210 i = z.choose;
 211 x = case
 212         { i == 1 }   { \no }
 213         { i == 1.1 } { \wrong }
 214         { i == 1.3 } { \wrong }
 215         { i == 1.5 } { \wrong }
 216         { i == 2 }   { \wrong }
 217         { i == 0 }   { \true };
 218 x.postln;
 219 )
 220 ::
 221
 222 section:: Other Control Structures
 223
 224 Using Functions, many control structures can be defined like the ones above. In the class link::Classes/Collection#iteration:: there are many more messages defined for iterating over Collections.
 225
 226 section:: Inline optimization
 227
 228 code::if::, code::while::, code::switch:: and code::case:: expressions are optimized (i.e. inlined) by the compiler if they do not contain variable declarations in the functions. The optimization plucks the code from the functions and uses a more efficient jump statement:
 229 code::
 230 {
 231         if( 6 == 9,{
 232                 "hello".postln;
 233         },{
 234                 "hello".postln;
 235         })
 236 }.def.dumpByteCodes
 237
 238 BYTECODES: (18)
 239   0   FE 06    PushPosInt 6
 240   2   FE 09    PushPosInt 9
 241   4   E6       SendSpecialBinaryArithMsg '=='
 242   5   F8 00 06 JumpIfFalse 6  (14)
 243   8   42       PushLiteral "hello"
 244   9   A1 00    SendMsg 'postln'
 245  11   FC 00 03 JumpFwd 3  (17)
 246  14   41       PushLiteral "hello"
 247  15   A1 00    SendMsg 'postln'
 248  17   F2       BlockReturn
 249 a FunctionDef in closed FunctionDef
 250 ::
 251
 252 Failure to inline due to variable declarations:
 253 code::
 254 {
 255         if( 6 == 9,{
 256                 var notHere;
 257                 "hello".postln;
 258         },{
 259                 "hello".postln;
 260         })
 261 }.def.dumpByteCodes
 262
 263 WARNING: FunctionDef contains variable declarations and so will not be inlined.
 264    in file 'selected text'
 265    line 4 char 14 :
 266                 var notHere;•
 267                 "hello".postln;
 268 -----------------------------------
 269 BYTECODES: (12)
 270   0   FE 06    PushPosInt 6
 271   2   FE 09    PushPosInt 9
 272   4   E6       SendSpecialBinaryArithMsg '=='
 273   5   04 00    PushLiteralX instance of FunctionDef in closed FunctionDef
 274   7   04 01    PushLiteralX instance of FunctionDef in closed FunctionDef
 275   9   C3 0B    SendSpecialMsg 'if'
 276  11   F2       BlockReturn
 277 a FunctionDef in closed FunctionDef
 278 ::
 279