?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
cmake: supernova - missing include_directories() for Jack
[supercollider.git] / Help / Core / Kernel / Function.html
blob823ac4a580c91b133fe7c54210810ca9d8effae9
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="1038.25">
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; color: #0000ee}
13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ad140d}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #cd1612}
18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Helvetica; min-height: 11.0px}
20 p.p11 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
21 p.p12 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #001bb9}
23 p.p14 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
24 p.p15 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
25 p.p16 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco}
26 p.p17 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
27 p.p18 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Monaco; min-height: 14.0px}
28 p.p19 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ad140d; min-height: 12.0px}
29 p.p20 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #2c7014}
30 p.p21 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
31 span.s1 {color: #000000}
32 span.s2 {color: #001bb9}
33 span.s3 {color: #0000ee}
34 span.s4 {color: #ad140d}
35 span.s5 {color: #0b28c6}
36 span.s6 {color: #cd1612}
37 span.s7 {color: #606060}
38 span.s8 {color: #2c7014}
39 span.s9 {text-decoration: underline ; color: #001bb9}
40 span.s10 {font: 9.0px Monaco; color: #2c7014}
41 span.Apple-tab-span {white-space:pre}
42 </style>
43 </head>
44 <body>
45 <p class="p1"><b>Function</b></p>
46 <p class="p2"><br></p>
47 <p class="p3"><span class="s1"><b>Inherits from: </b><a href="../Object.html"><b>Object</b></a></span><span class="s2"><b> : </b><a href="AbstractFunction.html"><span class="s3"><b>AbstractFunction</b></span></a></span></p>
48 <p class="p2"><br></p>
49 <p class="p2"><br></p>
50 <p class="p4">A Function is a reference to a <a href="FunctionDef.html"><span class="s2">FunctionDef</span></a> and its defining context <a href="Frame.html"><span class="s2">Frame</span></a>. When a FunctionDef is encountered in your code it is pushed on the stack as a Function. A Function can be evaluated by using the 'value' method. See the <a href="../../Language/Functions.html"><span class="s2">Functions</span></a> help file for a basic introduction.</p>
51 <p class="p2"><br></p>
52 <p class="p4">Because it inherits from <a href="AbstractFunction.html"><span class="s2">AbstractFunction</span></a>, Functions respond to math operations by creating a new Function.<span class="Apple-converted-space"> </span></p>
53 <p class="p2"><br></p>
54 <p class="p5">// example</p>
55 <p class="p6">(</p>
56 <p class="p6"><span class="s2">var</span> a, b, c;</p>
57 <p class="p6">a = { [100, 200, 300].choose };<span class="Apple-tab-span"> </span><span class="s4">// a Function</span></p>
58 <p class="p6">b = { 10.rand + 1 };<span class="Apple-tab-span"> </span><span class="s4">// another Function</span></p>
59 <p class="p5"><span class="s1">c = a + b; <span class="Apple-tab-span"> </span></span>// c is a Function.</p>
60 <p class="p5"><span class="s1">c.value.postln;<span class="Apple-tab-span"> </span></span>// evaluate c and print the result</p>
61 <p class="p6">)</p>
62 <p class="p7"><br></p>
63 <p class="p4">See <a href="AbstractFunction.html"><span class="s2">AbstractFunction</span></a><b> </b>for function composition examples.</p>
64 <p class="p2"><br></p>
65 <p class="p4">Because Functions are such an important concept, here some examples from related programming languages with functions as first class objects:</p>
66 <p class="p2"><br></p>
67 <p class="p8">// returning the first argument itself:</p>
68 <p class="p6">{ <span class="s5">|x|</span> x }.value(1) <span class="s6">// SuperCollider</span></p>
69 <p class="p6">[:x | x ] value: 1<span class="s6"> // Smalltalk</span></p>
70 <p class="p6">((lambda (x) x) 1) <span class="s6">// Lisp</span></p>
71 <p class="p2"><br></p>
72 <p class="p2"><br></p>
73 <p class="p9"><b>Accessing</b></p>
74 <p class="p2"><br></p>
75 <p class="p2"><br></p>
76 <p class="p4"><b>def</b></p>
77 <p class="p2"><br></p>
78 <p class="p4">Get the definition ( <a href="FunctionDef.html"><span class="s2">FunctionDef</span></a> ) of the Function.</p>
79 <p class="p2"><br></p>
80 <p class="p4"><b>isClosed</b></p>
81 <p class="p2"><br></p>
82 <p class="p4">returns true if the function is closed, i.e. has no external references and can thus be converted to a compile string safely.</p>
83 <p class="p2"><br></p>
84 <p class="p2"><br></p>
85 <p class="p9"><b>Evaluation</b></p>
86 <p class="p2"><br></p>
87 <p class="p4"><b>value(... args)</b></p>
88 <p class="p2"><br></p>
89 <p class="p4">Evaluates the FunctionDef referred to by the Function. The Function is passed the args given.</p>
90 <p class="p2"><br></p>
91 <p class="p6">{ <span class="s2">|a, b|</span> (a * b).postln }.value(3, 10);</p>
92 <p class="p6">{ <span class="s2">arg</span> a, b; (a * b).postln }.value(3, 10); <span class="s4">// different way of expressing the same</span></p>
93 <p class="p7"><br></p>
94 <p class="p7"><br></p>
95 <p class="p2"><br></p>
96 <p class="p4"><b>valueArray(... args)</b></p>
97 <p class="p2"><br></p>
98 <p class="p4">Evaluates the FunctionDef referred to by the Function. If the last argument is an Array or List, then it is unpacked and appended to the other arguments (if any) to the Function. If the last argument is not an Array or List then this is the same as the 'value' method.</p>
99 <p class="p2"><br></p>
100 <p class="p6">{ <span class="s2">|a, b, c|</span> ((a * b) + c).postln }.valueArray([3, 10, 7]);</p>
101 <p class="p10"><br></p>
102 <p class="p6">{ <span class="s2">|a, b, c, d|</span> [a, b, c, d].postln }.valueArray([1, 2, 3]);</p>
103 <p class="p10"><br></p>
104 <p class="p6">{ <span class="s2">|a, b, c, d|</span> [a, b, c, d].postln }.valueArray(9, [1, 2, 3]);</p>
105 <p class="p7"><br></p>
106 <p class="p6">{ <span class="s2">|a, b, c, d|</span> [a, b, c, d].postln }.valueArray(9, 10, [1, 2, 3]);</p>
107 <p class="p7"><br></p>
108 <p class="p4">A common syntactic shortcut:</p>
109 <p class="p7"><br></p>
110 <p class="p11">{ <span class="s5">|a, b, c|</span> ((a * b) + c).postln }.value(*[3, 10, 7]);</p>
111 <p class="p7"><br></p>
112 <p class="p12"><br></p>
113 <p class="p4"><b>valueEnvir(... args)</b></p>
114 <p class="p2"><br></p>
115 <p class="p4">As value above. Unsupplied argument names are looked up in the current <b>Environment</b>.</p>
116 <p class="p2"><br></p>
117 <p class="p6">(</p>
118 <p class="p13">Environment<span class="s1">.use({</span></p>
119 <p class="p6">~a = 3;</p>
120 <p class="p6">~b = 10;</p>
121 <p class="p6">{ <span class="s2">|a, b|</span> (a * b).postln }.valueEnvir;</p>
122 <p class="p6">});</p>
123 <p class="p6">)</p>
124 <p class="p12"><br></p>
125 <p class="p2"><br></p>
126 <p class="p4"><b>valueArrayEnvir(... args)</b></p>
127 <p class="p2"><br></p>
128 <p class="p4">Evaluates the FunctionDef referred to by the Function. If the last argument is an Array or List, then it is unpacked and appended to the other arguments (if any) to the Function. If the last argument is not an Array or List then this is the same as the 'value' method. Unsupplied argument names are looked up in the current <b>Environment</b>.</p>
129 <p class="p2"><br></p>
130 <p class="p2"><br></p>
131 <p class="p4"><b>valueWithEnvir(envir)</b></p>
132 <p class="p2"><br></p>
133 <p class="p4">Evaluate the function, using arguments from the supplied environment</p>
134 <p class="p4">This is slightly faster than <b>valueEnvir</b> and does not require replacing the <b>currentEnvironment</b></p>
135 <p class="p2"><br></p>
136 <p class="p6">(</p>
137 <p class="p6"><span class="s2">e = Environment</span>.make({<span class="s2"> </span>~a = 3; ~b = 10 });</p>
138 <p class="p6">{ <span class="s2">|a, b|</span> (a * b) }.valueWithEnvir(e);</p>
139 <p class="p6">)</p>
140 <p class="p2"><br></p>
141 <p class="p4"><b>functionPerformList(selector, arglist)</b></p>
142 <p class="p2"><br></p>
143 <p class="p4">For Function, this behaves the same as valueArray(arglist). It is used<span class="Apple-converted-space">  </span>where Functions and other objects should behave differently to value, such as in the objecr prototyping implementation of <a href="../../Collections/Environment.html"><span class="s2">Environment</span></a>.</p>
144 <p class="p2"><br></p>
145 <p class="p14"><br></p>
146 <p class="p15"><b>performWithEnvir(selector, envir)</b></p>
147 <p class="p14"><b><span class="Apple-tab-span"> </span></b></p>
148 <p class="p4"><b>selector: </b>A <a href="../Symbol.html"><span class="s2">Symbol</span></a> representing a method selector.<span class="Apple-converted-space"> </span></p>
149 <p class="p4"><b>envir: </b>The remaining arguments derived from the environment and passed as arguments to the method named by the selector.</p>
150 <p class="p2"><br></p>
151 <p class="p6">a = { <span class="s2">|a, b, c|</span> postf(<span class="s7">"% plus % plus % is %\n"</span>, a, b, c, a + b + c); <span class="s7">""</span> };</p>
152 <p class="p6">a.performWithEnvir(<span class="s8">\value</span>, (a: 1, c: 3, d: 4, b: 2));</p>
153 <p class="p2"><span class="Apple-tab-span"> </span></p>
154 <p class="p15"><b>performKeyValuePairs(selector, pairs)</b></p>
155 <p class="p14"><b><span class="Apple-tab-span"> </span></b></p>
156 <p class="p15"><b>selector: </b>A <a href="../Symbol.html"><span class="s2">Symbol</span></a> representing a method selector.<span class="Apple-converted-space"> </span></p>
157 <p class="p15"><b>pairs: </b>Array or List with key-value pairs.</p>
158 <p class="p14"><br></p>
159 <p class="p16">a = { <span class="s2">|a, b, c|</span> postf(<span class="s7">"% plus % plus % is %\n"</span>, a, b, c, a + b + c); <span class="s7">""</span> };</p>
160 <p class="p16">a.performKeyValuePairs(<span class="s8">\value</span>, [<span class="s8">\a</span>, 1, <span class="s8">\b</span>, 2, <span class="s8">\c</span>, 3, <span class="s8">\d</span>, 4]);</p>
161 <p class="p14"><br></p>
162 <p class="p2"><br></p>
163 <p class="p4"><b>loop</b></p>
164 <p class="p2"><br></p>
165 <p class="p4">Repeat this function. Useful with <b>Task</b> and Clocks.</p>
166 <p class="p2"><br></p>
167 <p class="p6">t = <span class="s2">Task</span>({ { <span class="s7">"I'm loopy"</span>.postln; 1.wait;}.loop });</p>
168 <p class="p6">t.start;</p>
169 <p class="p6">t.stop;</p>
170 <p class="p2"><br></p>
171 <p class="p2"><br></p>
172 <p class="p4"><b>defer(delta)</b></p>
173 <p class="p2"><br></p>
174 <p class="p4">Delay the evaluation of this Function by <b>delta</b> in seconds. Uses <b>AppClock</b>.</p>
175 <p class="p2"><br></p>
176 <p class="p17"><span class="s1">{ </span>"2 seconds have passed."<span class="s1">.postln; }.defer(2);</span></p>
177 <p class="p2"><br></p>
178 <p class="p2"><br></p>
179 <p class="p4"><b>dup(n)</b></p>
180 <p class="p2"><br></p>
181 <p class="p4">Return an Array consisting of the results of n evaluations of this Function.</p>
182 <p class="p2"><br></p>
183 <p class="p6">x = { 4.rand; }.dup(4);</p>
184 <p class="p6">x.postln;</p>
185 <p class="p7"><br></p>
186 <p class="p7"><br></p>
187 <p class="p4"><b>! n</b></p>
188 <p class="p2"><br></p>
189 <p class="p4">equivalent to dup(n)</p>
190 <p class="p7"><br></p>
191 <p class="p6">x = { 4.rand } ! 4;</p>
192 <p class="p6">x.postln;</p>
193 <p class="p2"><br></p>
194 <p class="p2"><br></p>
195 <p class="p4"><b>sum(n)</b></p>
196 <p class="p2"><br></p>
197 <p class="p4">return the sum of n values produced.</p>
198 <p class="p2"><br></p>
199 <p class="p6">{ 4.rand }.sum(8);</p>
200 <p class="p7"><br></p>
201 <p class="p4"><b>choose</b><span class="Apple-converted-space"> </span></p>
202 <p class="p2"><br></p>
203 <p class="p4">evaluates the function. This makes it polymorphic to <a href="../../Collections/SequenceableCollection.html"><span class="s9">SequenceableCollection</span></a>, <a href="../../Collections/Bag.html"><span class="s2">Bag</span></a> and <a href="../../Collections/Set.html"><span class="s9">Set</span></a>.</p>
204 <p class="p7"><br></p>
205 <p class="p6">[{ 100.rand }, [20, 30, 40]].collect(_.choose);</p>
206 <p class="p2"><br></p>
207 <p class="p2"><br></p>
208 <p class="p4"><b>bench(print)</b></p>
209 <p class="p2"><br></p>
210 <p class="p4">Returns the amount of time this function takes to evaluate. <b>print</b> is a boolean indicating whether the result is posted. The default is true.</p>
211 <p class="p2"><br></p>
212 <p class="p6">{ 1000000.do({ 1.0.rand }); }.bench;</p>
213 <p class="p7"><br></p>
214 <p class="p7"><br></p>
215 <p class="p4"><b>fork(clock, quant, stackSize)</b></p>
216 <p class="p2"><br></p>
217 <p class="p4">Returns a Routine using the receiver as it's function, and plays it in a <a href="../../Scheduling/TempoClock.html"><span class="s2">TempoClock</span></a>.</p>
218 <p class="p2"><br></p>
219 <p class="p6">{ 4.do({ <span class="s7">"Threadin..."</span>.postln; 1.wait;}) }.fork;</p>
220 <p class="p7"><br></p>
221 <p class="p7"><br></p>
222 <p class="p4"><b>forkIfNeeded(clock, quant, stackSize)</b></p>
223 <p class="p2"><br></p>
224 <p class="p4">If needed, creates a new Routine to evaluate the function in, if the message is called within a routine already, it simply evaluates it.</p>
225 <p class="p2"><br></p>
226 <p class="p6">f = { 4.do({ <span class="s7">"Threadin..."</span>.postln; 1.wait;}) };</p>
227 <p class="p6">f.forkIfNeeded;</p>
228 <p class="p6">{ <span class="s7">"we are now in a routine"</span>.postln; 1.wait; f.forkIfNeeded }.fork;</p>
229 <p class="p2"><br></p>
230 <p class="p2"><br></p>
231 <p class="p4"><b>block</b></p>
232 <p class="p2"><br></p>
233 <p class="p4">Break from a loop. Calls the receiver with an argument which is a function that returns from the method block. To exit the loop, call .value on the function passed in. You can pass a value to this function and that value will be returned from the block method.</p>
234 <p class="p2"><br></p>
235 <p class="p6">block {<span class="s2">|break|</span></p>
236 <p class="p6"><span class="Apple-tab-span"> </span>100.do {<span class="s2">|i|</span></p>
237 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>i.postln;</p>
238 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>if (i == 7) { break.value(999) }</p>
239 <p class="p6"><span class="Apple-tab-span"> </span>};</p>
240 <p class="p6">}</p>
241 <p class="p7"><br></p>
242 <p class="p4"><b>thunk</b></p>
243 <p class="p7"><br></p>
244 <p class="p4">Return a <a href="Thunk.html"><span class="s2">Thunk</span></a>, which is an unevaluated value that can be used in calculations<span class="Apple-converted-space"> </span></p>
245 <p class="p2"><br></p>
246 <p class="p6">x = thunk { 4.rand };</p>
247 <p class="p6">x.value;</p>
248 <p class="p6">x.value;</p>
249 <p class="p7"><br></p>
250 <p class="p7"><br></p>
251 <p class="p4"><b>flop</b></p>
252 <p class="p2"><br></p>
253 <p class="p4">Return a function that, when evaluated with nested arguments, does multichannel expansion by evaluting the receiver function for each channel. A flopped function responds like the "map" function in languages like Lisp.</p>
254 <p class="p7"><br></p>
255 <p class="p6">f = { <span class="s2">|a, b|</span> if(a &gt; 0) { a + b } { -<span class="s2">inf</span> } }.flop;</p>
256 <p class="p6">f.value([-1, 2, 1, -3.0], [10, 1000]);</p>
257 <p class="p6">f.value(2, 3);</p>
258 <p class="p7"><br></p>
259 <p class="p7"><br></p>
260 <p class="p7"><br></p>
261 <p class="p4"><b>envirFlop</b></p>
262 <p class="p2"><br></p>
263 <p class="p4">like flop, but implements an environment argument passing (valueEnvir).<span class="Apple-converted-space"> </span></p>
264 <p class="p4">Less efficient in generation than flop, but not a big difference in evaluation.</p>
265 <p class="p7"><br></p>
266 <p class="p6">f = { <span class="s2">|a|</span> if(a &gt; 0) { a + 1 } { -<span class="s2">inf</span> } }.envirFlop;</p>
267 <p class="p6">e = (a: [20, 40]);</p>
268 <p class="p6">e.use { f.value }</p>
269 <p class="p7"><br></p>
270 <p class="p7"><br></p>
271 <p class="p2"><br></p>
272 <p class="p4"><b>inEnvir(envir)</b></p>
273 <p class="p2"><br></p>
274 <p class="p4">returns an "environment-safe" function. See <a href="../../Collections/Environment.html"><span class="s2">Environment</span></a> for more details.</p>
275 <p class="p2"><br></p>
276 <p class="p5">// prints nil because ~a is read from topEnvironment, not e</p>
277 <p class="p6">e = (a: <span class="s7">"got it"</span>, f: { { ~a.postln }.defer(0.5) });</p>
278 <p class="p6">e.use { e.f };</p>
279 <p class="p7"><br></p>
280 <p class="p5">// prints "got it" because { ~a.postln } is now bound to the e environment</p>
281 <p class="p6">e = (a: <span class="s7">"got it"</span>, f: { { ~a.postln }.inEnvir.defer(0.5) });</p>
282 <p class="p6">e.use { e.f };</p>
283 <p class="p7"><br></p>
284 <p class="p2"><br></p>
285 <p class="p2"><br></p>
286 <p class="p4"><b>case(cases)</b></p>
287 <p class="p2"><br></p>
288 <p class="p4">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. Unlike Object-switch, this is inlined and is therefore just as efficient as nested if statements.</p>
289 <p class="p18"><br></p>
290 <p class="p6">(</p>
291 <p class="p6"><span class="s2">var</span> i, x, z;</p>
292 <p class="p6">z = [0, 1, 1.1, 1.3, 1.5, 2];</p>
293 <p class="p6">i = z.choose;</p>
294 <p class="p6">x = case</p>
295 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 1 } <span class="Apple-converted-space">  </span>{ <span class="s8">\no</span> }</p>
296 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 1.1 } { <span class="s8">\wrong</span> }</p>
297 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 1.3 } { <span class="s8">\wrong</span> }</p>
298 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 1.5 } { <span class="s8">\wrong</span> }</p>
299 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 2 } <span class="Apple-converted-space">  </span>{ <span class="s8">\wrong</span> }</p>
300 <p class="p6"><span class="Apple-tab-span"> </span>{ i == 0 } <span class="Apple-converted-space">  </span>{ <span class="s8">\true</span> };</p>
301 <p class="p6">x.postln;</p>
302 <p class="p6">)</p>
303 <p class="p7"><br></p>
304 <p class="p4"><b>matchItem(item)</b></p>
305 <p class="p2"><br></p>
306 <p class="p4">Interface shared with other classes that implements pattern matching. See also: matchItem.</p>
307 <p class="p4">Function.matchItem evaluates the function with the item as argument, expecting a <a href="../Boolean.html"><span class="s2">Boolean</span></a> as reply.</p>
308 <p class="p2"><br></p>
309 <p class="p6">{ <span class="s2">|x|</span> x &gt; 5 }.matchItem(6); <span class="s4">// true</span></p>
310 <p class="p19"><br></p>
311 <p class="p19"><br></p>
312 <p class="p4"><b>performDegreeToKey(scaleDegree, stepsPerOctave = 12, accidental = 0)</b></p>
313 <p class="p2"><br></p>
314 <p class="p4">use a function as a conversion from scale degree to note number. See also <a href="../../Collections/SequenceableCollection.html"><span class="s9">SequenceableCollection</span></a> and <a href="../../Collections/Scale.html"><span class="s2">Scale</span></a></p>
315 <p class="p2"><br></p>
316 <p class="p5">// a strange mapping</p>
317 <p class="p6">(</p>
318 <p class="p13">var<span class="s1"> f = {</span>|degree, stepsPerOctave, acc|</p>
319 <p class="p6"><span class="Apple-tab-span"> </span>(1.8 ** (degree % stepsPerOctave) + acc).postln</p>
320 <p class="p6">};</p>
321 <p class="p13">Pbind<span class="s1">(</span></p>
322 <p class="p20"><span class="s1"><span class="Apple-tab-span"> </span></span>\scale<span class="s1">, f,</span></p>
323 <p class="p6"><span class="Apple-tab-span"> </span><span class="s8">\degree</span>, <span class="s2">Pseq</span>([0, 1, 2b, 3s, 4s, 6, 14, [0, 2, 4], [1, 3, 6]], <span class="s2">inf</span>)</p>
324 <p class="p6">).play</p>
325 <p class="p6">)</p>
326 <p class="p2"><br></p>
327 <p class="p2"><br></p>
328 <p class="p9"><b>Exception Handling</b></p>
329 <p class="p2"><br></p>
330 <p class="p2"><br></p>
331 <p class="p4">For the following two methods a return ^ inside of the receiver itself cannot be caught. Returns in methods called by the receiver are OK.</p>
332 <p class="p2"><br></p>
333 <p class="p2"><br></p>
334 <p class="p4"><b>try(handler)</b></p>
335 <p class="p2"><br></p>
336 <p class="p4">Executes the receiver. If an exception is thrown the catch function <b>handler</b> is executed with the error as an argument. <b>handler</b> itself can rethrow the error if desired.</p>
337 <p class="p2"><br></p>
338 <p class="p4"><b>protect(handler)</b></p>
339 <p class="p2"><br></p>
340 <p class="p4">Executes the receiver. The cleanup function <b>handler </b>is executed with an error as an argument, or nil if there was no error. The error continues to be in effect.<span class="Apple-converted-space"> </span></p>
341 <p class="p2"><br></p>
342 <p class="p4">Examples:</p>
343 <p class="p7"><br></p>
344 <p class="p5">// no exception handler</p>
345 <p class="p6">value { 8.zorg; <span class="s8">\didnt_continue</span>.postln; }</p>
346 <p class="p7"><br></p>
347 <p class="p6">try { 8.zorg } {<span class="s2">|error|</span> error.postln; <span class="s8">\cleanup</span>.postln; }; <span class="s8">\continued</span>.postln;</p>
348 <p class="p7"><br></p>
349 <p class="p6">protect { 8.zorg } {<span class="s2">|error|</span> error.postln; }; <span class="s8">\didnt_continue</span>.postln;</p>
350 <p class="p7"><br></p>
351 <p class="p6">try { 123.postln; 456.throw; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\catch</span>, error].postln };</p>
352 <p class="p7"><br></p>
353 <p class="p6">try { 123.postln; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\catch</span>, error].postln };</p>
354 <p class="p7"><br></p>
355 <p class="p6">try { 123.postln; <span class="s2">nil</span>.throw; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\catch</span>, error].postln };</p>
356 <p class="p7"><br></p>
357 <p class="p7"><br></p>
358 <p class="p6">protect { 123.postln; 456.throw; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\onExit</span>, error].postln };</p>
359 <p class="p7"><br></p>
360 <p class="p6">protect { 123.postln; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\onExit</span>, error].postln };</p>
361 <p class="p7"><br></p>
362 <p class="p6">(</p>
363 <p class="p6">try {</p>
364 <p class="p6"><span class="Apple-tab-span"> </span>protect { 123.postln; 456.throw; 789.postln } {<span class="s2">|error|</span> [<span class="s8">\onExit</span>, error].postln };</p>
365 <p class="p6">} {<span class="s2">|error|</span> [<span class="s8">\catch</span>, error].postln };</p>
366 <p class="p6">)</p>
367 <p class="p7"><br></p>
368 <p class="p6">value { 123.postln; 456.throw; 789.postln }</p>
369 <p class="p7"><br></p>
370 <p class="p6">value { 123.postln; <span class="s2">Error</span>(<span class="s7">"what happened?"</span>).throw; 789.postln }</p>
371 <p class="p7"><br></p>
372 <p class="p6">(</p>
373 <p class="p20"><span class="s1">a = [</span>\aaa<span class="s1">, </span>\bbb<span class="s1">, </span>\ccc<span class="s1">, </span>\ddd<span class="s1">];</span></p>
374 <p class="p6">a[1].postln;</p>
375 <p class="p6">a[<span class="s8">\x</span>].postln;</p>
376 <p class="p6">a[2].postln;</p>
377 <p class="p6">)</p>
378 <p class="p7"><br></p>
379 <p class="p6">(</p>
380 <p class="p6">try {</p>
381 <p class="p20"><span class="s1"><span class="Apple-tab-span"> </span>a = [</span>\aaa<span class="s1">, </span>\bbb<span class="s1">, </span>\ccc<span class="s1">, </span>\ddd<span class="s1">];</span></p>
382 <p class="p6"><span class="Apple-tab-span"> </span>a[1].postln;</p>
383 <p class="p6"><span class="Apple-tab-span"> </span>a[<span class="s8">\x</span>].postln;</p>
384 <p class="p6"><span class="Apple-tab-span"> </span>a[2].postln;</p>
385 <p class="p6">} {<span class="s2">|error|</span> <span class="s8">\caught</span>.postln; error.dump }</p>
386 <p class="p6">)</p>
387 <p class="p7"><br></p>
388 <p class="p6">(</p>
389 <p class="p6">try {</p>
390 <p class="p20"><span class="s1"><span class="Apple-tab-span"> </span>a = [</span>\aaa<span class="s1">, </span>\bbb<span class="s1">, </span>\ccc<span class="s1">, </span>\ddd<span class="s1">];</span></p>
391 <p class="p6"><span class="Apple-tab-span"> </span>a[1].postln;</p>
392 <p class="p6"><span class="Apple-tab-span"> </span>a[<span class="s8">\x</span>].postln;</p>
393 <p class="p6"><span class="Apple-tab-span"> </span>a[2].postln;</p>
394 <p class="p6">} {<span class="s2">|error|</span> <span class="s8">\caught</span>.postln; error.dump; error.throw }</p>
395 <p class="p6">)</p>
396 <p class="p7"><br></p>
397 <p class="p6">(</p>
398 <p class="p6">protect {</p>
399 <p class="p20"><span class="s1"><span class="Apple-tab-span"> </span>a = [</span>\aaa<span class="s1">, </span>\bbb<span class="s1">, </span>\ccc<span class="s1">, </span>\ddd<span class="s1">];</span></p>
400 <p class="p6"><span class="Apple-tab-span"> </span>a[1].postln;</p>
401 <p class="p6"><span class="Apple-tab-span"> </span>a[<span class="s8">\x</span>].postln;</p>
402 <p class="p6"><span class="Apple-tab-span"> </span>a[2].postln;</p>
403 <p class="p6">} {<span class="s2">|error|</span> <span class="s8">\caught</span>.postln; error.dump }</p>
404 <p class="p6">)</p>
405 <p class="p21"><br></p>
406 <p class="p21"><br></p>
407 <p class="p9"><b>Audio</b></p>
408 <p class="p12"><br></p>
409 <p class="p4"><b>play(target, outbus, fadetime, addAction, args)</b></p>
410 <p class="p2"><br></p>
411 <p class="p4"><span class="Apple-tab-span"> </span>This is probably the simplest way to get audio in SC3. It wraps the Function in a <b>SynthDef</b> (adding an <b>Out</b> ugen if needed), creates and starts a new <b>Synth</b> with it, and returns the Synth object. A <b>Linen</b> is also added to avoid clicks, which is configured to allow the resulting Synth to have its <span class="s10">\gate </span>argument set, or to respond to a release message. Args in the function become args in the resulting def.</p>
412 <p class="p2"><br></p>
413 <p class="p4"><b><span class="Apple-tab-span"> </span>target </b>- a Node, Server, or Nil. A Server will be converted to the default group of that server. Nil will be converted to the default group of the default Server.</p>
414 <p class="p4"><b><span class="Apple-tab-span"> </span>outbus </b>- the output bus to play the audio out on. This is equivalent to Out.ar(outbus, theoutput). The default is 0.</p>
415 <p class="p4"><b><span class="Apple-tab-span"> </span>fadeTime</b> - a fadein time. The default is 0.02 seconds, which is just enough to avoid a click. This will also be the fadeout time for a release if you do not specify.</p>
416 <p class="p4"><b><span class="Apple-tab-span"> </span>addAction</b> - see <b>Synth</b> for a list of valid addActions. The default is <span class="s10">\addToHead</span><b>.</b></p>
417 <p class="p12"><br></p>
418 <p class="p6"><span class="Apple-tab-span"> </span>x = { <span class="s2">|freq = 440|</span> <span class="s2">SinOsc</span>.ar(freq, 0, 0.3) }.play; <span class="s4">// this returns a Synth object;</span></p>
419 <p class="p5"><span class="s1"><span class="Apple-tab-span"> </span>x.set(</span><span class="s8">\freq</span><span class="s1">, 880); </span>// note you can set the freq argument</p>
420 <p class="p5"><span class="s1"><span class="Apple-tab-span"> </span>x.defName; </span>// the name of the resulting SynthDef (generated automatically in a cycle of 512)</p>
421 <p class="p5"><span class="s1"><span class="Apple-tab-span"> </span>x.release(4); </span>// fadeout over 4 seconds</p>
422 <p class="p2"><br></p>
423 <p class="p2"><br></p>
424 <p class="p4"><span class="Apple-tab-span"> </span>Many of the examples make use of the Function.play syntax.<span class="Apple-converted-space"> </span></p>
425 <p class="p4"><span class="Apple-tab-span"> </span>Note that reusing such code in a <a href="../../ServerArchitecture/SynthDef.html"><span class="s2">SynthDef</span></a> requires the addition of an <a href="../../UGens/InOut/Out.html"><span class="s2">Out</span></a> ugen.</p>
426 <p class="p12"><br></p>
427 <p class="p5"><span class="Apple-tab-span"> </span>// the following two lines produce equivalent results</p>
428 <p class="p6"><span class="Apple-tab-span"> </span>{ <span class="s2">SinOsc</span>.ar(440, 0, 0.3) }.play(fadeTime: 0.0);<span class="Apple-converted-space"> </span></p>
429 <p class="p6"><span class="Apple-tab-span"> </span><span class="s2">SynthDef</span>(<span class="s8">\help_FuncPlay</span>, { <span class="s2">Out</span>.ar(0, <span class="s2">SinOsc</span>.ar(440, 0, 0.3))}).play;</p>
430 <p class="p18"><br></p>
431 <p class="p4"><span class="Apple-tab-span"> </span>Function.play is often more convienent than SynthDef.play, particularly for short examples and quick testing. The latter does have some additional options, such as lagtimes for controls, etc. Where reuse and maximum flexibility are of greater importance, SynthDef and its various methods are usually the better choice.<span class="Apple-converted-space"> </span></p>
432 <p class="p2"><span class="Apple-tab-span"> </span></p>
433 <p class="p2"><br></p>
434 <p class="p4"><b>scope(numChannels, outbus, fadeTime, bufsize, zoom)</b></p>
435 <p class="p2"><br></p>
436 <p class="p4"><span class="Apple-tab-span"> </span>As <b>play </b>above, but plays it on the internal <b>Server</b>, and calls Server-scope to open a scope window in which to view the output. Currently only works on OSX.</p>
437 <p class="p2"><span class="Apple-tab-span"> </span></p>
438 <p class="p4"><span class="Apple-tab-span"> </span><b>numChannels</b> - The number of channels to display in the scope window, starting from <b>outbus</b>. The default is 2.</p>
439 <p class="p4"><b><span class="Apple-tab-span"> </span>outbus </b>- The output bus to play the audio out on. This is equivalent to Out.ar(outbus, theoutput). The default is 0.</p>
440 <p class="p4"><span class="Apple-tab-span"> </span><b>fadeTime</b> - A fadein time. The default is 0.02 seconds, which is just enough to avoid a click.</p>
441 <p class="p4"><span class="Apple-tab-span"> </span><b>bufsize </b>- The size of the buffer for the ScopeView. The default is 4096.</p>
442 <p class="p4"><span class="Apple-tab-span"> </span><b>zoom</b> - A zoom value for the scope's X axis. Larger values show more. The default is 1.</p>
443 <p class="p2"><br></p>
444 <p class="p6"><span class="Apple-tab-span"> </span>{ <span class="s2">FSinOsc</span>.ar(440, 0, 0.3) }.scope(1)</p>
445 <p class="p2"><br></p>
446 <p class="p2"><br></p>
447 <p class="p2"><br></p>
448 <p class="p4"><b>plot(duration, server, bounds, minval, maxval, parent)</b></p>
449 <p class="p2"><br></p>
450 <p class="p4"><span class="Apple-tab-span"> </span>Calculates <b>duration</b> in seconds worth of the output of this function, and plots it in a GUI window. Unlike <b>play</b> and <b>scope</b> it will not work with explicit Out Ugens, so your function should return a UGen or an <b>Array</b> of them. The plot will be calculated in realtime.</p>
451 <p class="p2"><br></p>
452 <p class="p4"><b><span class="Apple-tab-span"> </span>duration</b> - The duration of the function to plot in seconds. The default is 0.01.</p>
453 <p class="p4"><b><span class="Apple-tab-span"> </span>server </b>- The <b>Server</b> on which to calculate the plot. This must be running on your local machine, but does not need to be the internal server. If nil the default server will be used.</p>
454 <p class="p4"><span class="Apple-tab-span"> </span><b>bounds</b> - An instance of <b>Rect</b> or <b>Point</b> indicating the bounds of the plot window.</p>
455 <p class="p4"><span class="Apple-tab-span"> </span><b>minval</b> - the minimum value in the plot. Defaults to -1.0.</p>
456 <p class="p4"><span class="Apple-tab-span"> </span><b>maxval</b> - the maximum value in the plot. Defaults to 1.0.</p>
457 <p class="p4"><span class="Apple-tab-span"> </span><b>parent</b> - a window to place the plot in. If nil, one will be created for you.</p>
458 <p class="p2"><br></p>
459 <p class="p6"><span class="Apple-tab-span"> </span>{ <span class="s2">SinOsc</span>.ar(440) }.plot(0.01, bounds: <span class="s2">Window</span>.screenBounds);</p>
460 <p class="p7"><span class="Apple-tab-span"> </span></p>
461 <p class="p6"><span class="Apple-tab-span"> </span>{ {<span class="s2">|i|</span> <span class="s2">SinOsc</span>.ar(1 + i)}.dup(7) }.plot(1);</p>
462 <p class="p2"><br></p>
463 <p class="p2"><br></p>
464 <p class="p2"><br></p>
465 <p class="p9"><b>Conversion</b></p>
466 <p class="p2"><br></p>
467 <p class="p2"><br></p>
468 <p class="p2"><br></p>
469 <p class="p4"><b>asSynthDef(rates, prependArgs, outClass, fadetime)</b></p>
470 <p class="p2"><br></p>
471 <p class="p4"><span class="Apple-tab-span"> </span>Returns a SynthDef based on this Function, adding a <b>Linen </b>and an <b>Out</b> ugen if needed.</p>
472 <p class="p2"><br></p>
473 <p class="p4"><b><span class="Apple-tab-span"> </span>rates </b>- An Array of rates and lagtimes for the function's arguments (see <b>SynthDef</b> for more details).</p>
474 <p class="p4"><span class="Apple-tab-span"> </span><b>outClass</b> - The class of the output ugen as a symbol. The default is <span class="s8">\Out</span>.</p>
475 <p class="p4"><span class="Apple-tab-span"> </span><b>fadeTime</b> - a fadein time. The default is 0.</p>
476 <p class="p2"><br></p>
477 <p class="p2"><br></p>
478 <p class="p2"><br></p>
479 <p class="p4"><b>asDefName</b></p>
480 <p class="p2"><br></p>
481 <p class="p4">Performs asSynthDef (see above), sends the resulting def to the local server and returns the SynthDefs name. This is asynchronous.</p>
482 <p class="p18"><br></p>
483 <p class="p6">x = { <span class="s2">SinOsc</span>.ar(440, 0, 0.3) }.asDefName; <span class="s4">// this must complete first</span></p>
484 <p class="p6">y = <span class="s2">Synth</span>(x);</p>
485 <p class="p18"><br></p>
486 <p class="p18"><br></p>
487 <p class="p4"><b>asRoutine</b></p>
488 <p class="p2"><br></p>
489 <p class="p4">Returns a <a href="Routine.html"><span class="s2">Routine</span></a> using <b>this</b> as its func argument.</p>
490 <p class="p2"><br></p>
491 <p class="p4"><b>r</b></p>
492 <p class="p2"><br></p>
493 <p class="p4">Returns a <a href="Routine.html"><span class="s2">Routine</span></a> using <b>this</b> as its func argument.</p>
494 <p class="p7"><br></p>
495 <p class="p6">a = r { 5.do { <span class="s2">|i|</span> i.rand.yield } };</p>
496 <p class="p6">a.nextN(8);</p>
497 <p class="p7"><br></p>
498 <p class="p4"><b>p</b></p>
499 <p class="p2"><br></p>
500 <p class="p4">Returns a <a href="../../Streams-Patterns-Events/Patterns/Prout.html"><span class="s2">Prout</span></a> using <b>this</b> as its func argument.</p>
501 <p class="p7"><br></p>
502 <p class="p6">a = p { 5.do { <span class="s2">|i|</span> i.rand.yield } };</p>
503 <p class="p6">x = a.asStream;</p>
504 <p class="p6">x.nextN(8);</p>
505 <p class="p7"><br></p>
506 <p class="p4">This is useful for using <a href="../../Language/ListComprehensions.html"><span class="s9">ListComprehensions</span></a> in Patterns:</p>
507 <p class="p7"><br></p>
508 <p class="p6"><span class="s2">Pbind</span>(<span class="s8">\degree</span>, p {:[x, y].postln, x&lt;-(0..10), y&lt;-(0..10), (x + y).isPrime }, <span class="s8">\dur</span>, 0.3).play;<span class="Apple-converted-space"> </span></p>
509 <p class="p7"><br></p>
510 </body>
511 </html>