Include a header file required for build on mac 10.4
[supercollider.git] / Help / Libraries / JITLib / environments / Maybe.html
blob17aaa8438b15fd589dde9dbc2866e8d4a985285a
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: 12.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: #1032ee}
13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0a26c0; min-height: 14.0px}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
16 p.p7 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; min-height: 12.0px}
17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
18 p.p9 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
19 p.p10 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica}
20 p.p11 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #bf0000}
21 p.p12 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco}
22 p.p13 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #ad140d}
23 p.p14 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #ad140d; min-height: 12.0px}
24 p.p15 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
25 p.p16 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
26 p.p17 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ad140d}
27 p.p18 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ad140d; min-height: 12.0px}
28 p.p19 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000; min-height: 12.0px}
29 span.s1 {font: 18.0px Helvetica}
30 span.s2 {color: #000000}
31 span.s3 {text-decoration: underline}
32 span.s4 {color: #0a26c0}
33 span.s5 {text-decoration: underline ; color: #1032ee}
34 span.s6 {color: #1135f9}
35 span.s7 {color: #0000bf}
36 span.s8 {color: #bf0000}
37 span.s9 {font: 12.0px Helvetica; color: #000000}
38 span.s10 {color: #007300}
39 span.s11 {text-decoration: underline ; color: #0021e7}
40 span.s12 {color: #606060}
41 span.s13 {color: #001bb9}
42 span.s14 {color: #2c7014}
43 span.s15 {color: #ad140d}
44 span.Apple-tab-span {white-space:pre}
45 </style>
46 </head>
47 <body>
48 <p class="p1"><span class="s1"><b>Maybe<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></span><b>referentially transparent proxy object</b><span class="s1"><b><span class="Apple-tab-span"> </span></b></span></p>
49 <p class="p2"><br></p>
50 <p class="p3"><span class="s2"><b>Inherits from:</b> <a href="../../../Core/Object.html"><span class="s3">Object</span></a></span><span class="s4"> : <a href="../../../Core/Kernel/AbstractFunction.html"><span class="s5">AbstractFunction</span></a> : <a href="../../../Core/Ref.html"><span class="s6">Ref</span></a></span></p>
51 <p class="p4"><br></p>
52 <p class="p1">A Maybe object can contain either nil or some other object, and allows to construct calculations without knowing this other object yet. If the calculation fails, due to a loop or a not yet defined object, Maybe returns nil.</p>
53 <p class="p2"><br></p>
54 <p class="p1">The name <b>Maybe</b> stems from the programming language Haskell, where it represents a somewhat similar entity. See also: <a href="../Patterns/Fdef.html"><span class="s6">Fdef</span></a></p>
55 <p class="p2"><br></p>
56 <p class="p1">Overview: <a href="../JITLib.html"><span class="s4">JITLib</span></a></p>
57 <p class="p5"><br></p>
58 <p class="p6"><br></p>
59 <p class="p7"><br></p>
60 <p class="p8"><b><span class="Apple-tab-span"> </span>*new(object)</b></p>
61 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
62 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>create a new instance</p>
63 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>object </b>- an object or nil.<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
64 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
65 <p class="p11"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// example:</p>
66 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a = <span class="s7">Maybe</span>.new;</p>
67 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b = <span class="s7">Maybe</span>(a + 6);</p>
68 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b.value; <span class="s8">// =&gt; nil</span></p>
69 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a.value = 1;</p>
70 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b.value; <span class="s8">// =&gt; 7</span></p>
71 <p class="p7"><br></p>
72 <p class="p8"><b><span class="Apple-tab-span"> </span>source</b></p>
73 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
74 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>return the contained object</p>
75 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
76 <p class="p8"><span class="Apple-tab-span"> </span><b>source_(obj)</b></p>
77 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
78 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>set the contained object</p>
79 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
80 <p class="p8"><span class="Apple-tab-span"> </span><b>value_(obj)</b></p>
81 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
82 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>set the contained object</p>
83 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
84 <p class="p8"><b><span class="Apple-tab-span"> </span>value(arg1, arg2...)</b></p>
85 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
86 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>return the source, or the value of the contained object, if it is a Maybe.</p>
87 <p class="p8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>If there is a recursion, return nil.</p>
88 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
89 <p class="p9"><span class="Apple-tab-span"> </span></p>
90 <p class="p8"><span class="Apple-tab-span"> </span><b>apply(arg1, arg2...)</b></p>
91 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
92 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>return the value, or the value of the contained object, if it is a Maybe.</p>
93 <p class="p8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>This method allows recursion, so that recursive calcualtions can be made.</p>
94 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
95 <p class="p8"><span class="Apple-tab-span"> </span><b>doesNotUnderstand(selector, ... args) </b>(called by any message that Maybe doesn't understand)</p>
96 <p class="p9"><b><span class="Apple-tab-span"> </span></b></p>
97 <p class="p8"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>returns a composition function that, when evaluated, returns the value.</p>
98 <p class="p13"><span class="s9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// example:</p>
99 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a = <span class="s7">Maybe</span>.new;</p>
100 <p class="p11"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a.respondsTo(</span><span class="s10">\flop</span><span class="s2">) </span>// false: Maybe constructs a placeholder instead</p>
101 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b = <span class="s7">Maybe</span>(a.flop);</p>
102 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b.value; <span class="s8">// =&gt; nil</span></p>
103 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a.value = [1, 2, [2, 3]];</p>
104 <p class="p11"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b.value;<span class="Apple-tab-span"> </span></span>// =&gt; [ [ 1, 2, 2 ], [ 1, 2, 3 ] ]<span class="Apple-tab-span"> </span></p>
105 <p class="p9"><br></p>
106 <p class="p14"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
107 <p class="p7"><br></p>
108 <p class="p7"><br></p>
109 <p class="p13">// the following examples use a <a href="LazyEnvir.html"><span class="s11">LazyEnvir</span></a> with a Maybe as a proxy class.</p>
110 <p class="p13">// instead of writing a = Maybe.new; a.value = something;<span class="Apple-converted-space"> </span></p>
111 <p class="p13">// one can simply write ~a = something.</p>
112 <p class="p13">// the Maybe is implictly created for you.</p>
113 <p class="p7"><br></p>
114 <p class="p15">(</p>
115 <p class="p15"><span class="Apple-tab-span"> </span>p.pop.clear;</p>
116 <p class="p15"><span class="Apple-tab-span"> </span>p = <span class="s7">LazyEnvir</span>.new;</p>
117 <p class="p15"><span class="Apple-tab-span"> </span>p.proxyClass = <span class="s7">Maybe</span>;</p>
118 <p class="p16"><span class="s2"><span class="Apple-tab-span"> </span>p.linkDoc; </span>// here: connect to current doc only.</p>
119 <p class="p15">);</p>
120 <p class="p4"><br></p>
121 <p class="p4"><br></p>
122 <p class="p16">// sets</p>
123 <p class="p15">~a = <span class="s7">Set</span>[0, 4, 5, 7];</p>
124 <p class="p15">~b = <span class="s7">Set</span>[4, 5];</p>
125 <p class="p16"><span class="s2">~c = ~a union: ~b; </span>// union of the two sets (note that the shortcut | does not work here.).<span class="Apple-converted-space"> </span></p>
126 <p class="p16"><span class="s2">~d = ~a sect: ~b; </span>// intersection of a and b</p>
127 <p class="p16"><span class="s2">~c.postcs;</span><span class="s12">""</span><span class="s2">; </span>// post the whole construction</p>
128 <p class="p15">~d.postcs;<span class="s12">""</span>;</p>
129 <p class="p16"><span class="s2">~c.value; </span>// Set[ 4, 0, 5, 7 ]</p>
130 <p class="p16"><span class="s2">~d.value; </span>// Set[ 4, 5 ]</p>
131 <p class="p15">~b = <span class="s13">Set</span>[4, 5, 13, 0];</p>
132 <p class="p15">~c.value;</p>
133 <p class="p16"><span class="s2">~d.value; </span>// Set[ 4, 0, 5 ]</p>
134 <p class="p16"><span class="s2">~b.source.add(~w); </span>// add another placeholder</p>
135 <p class="p16"><span class="s2">~c.value; </span>// it is part of the union.</p>
136 <p class="p16"><span class="s2">~d.value; </span>// but not part of the intersection</p>
137 <p class="p4"><br></p>
138 <p class="p4"><br></p>
139 <p class="p17">// envirs</p>
140 <p class="p15">~a = (note: [1, 2]);</p>
141 <p class="p15">~b = (dur: 1);</p>
142 <p class="p16"><span class="s2">~c = ~a.putAll(~b) </span>// provisionally put everything into the placholder<span class="Apple-converted-space"> </span></p>
143 <p class="p15">~c.value;</p>
144 <p class="p15">~a = (note: [1, 2, 4]);</p>
145 <p class="p15">~c.value;</p>
146 <p class="p15">~d = ~a.at(<span class="s14">\note</span>);</p>
147 <p class="p15">~d.value;</p>
148 <p class="p15">~a = (note: [7.5]);</p>
149 <p class="p15">~d.value; <span class="s15">// [7.5]</span></p>
150 <p class="p4"><br></p>
151 <p class="p17">// patterns</p>
152 <p class="p15">~a = <span class="s13">Pseq</span>([1, 2, 3]);</p>
153 <p class="p15">~b = <span class="s13">Pseq</span>([5, ~a, ~a + 10], <span class="s13">inf</span>);</p>
154 <p class="p15">~b.value.asStream.nextN(10);</p>
155 <p class="p4"><br></p>
156 <p class="p4"><br></p>
157 <p class="p15">~a = <span class="s13">Prand</span>([100, 200]);</p>
158 <p class="p15">~b.value.asStream.nextN(10);</p>
159 <p class="p4"><br></p>
160 <p class="p18"><br></p>
161 <p class="p17">// to do : flop!</p>
162 <p class="p4"><br></p>
163 <p class="p17">//////////////// deep recursion</p>
164 <p class="p4"><br></p>
165 <p class="p17">// with normal functions:</p>
166 <p class="p15">f = { <span class="s13">|x|</span> if(x &lt;= 1) { 1 } { x * f.(x - 1) } };</p>
167 <p class="p15">f.(12)</p>
168 <p class="p4"><br></p>
169 <p class="p4"><br></p>
170 <p class="p15">~faculty = { <span class="s13">|x|</span> if(x == 1) { 1 } { x * ~faculty.(x - 1) } };</p>
171 <p class="p17"><span class="s2">~faculty.(12) </span>// doesn't work (=&gt; nil). here we _do_ want recursion ...</p>
172 <p class="p4"><br></p>
173 <p class="p17">// for explicit recursion use "apply"</p>
174 <p class="p15">~faculty = { <span class="s13">|x|</span> if(x == 1) { 1 } { x * ~faculty.apply(x - 1) } };</p>
175 <p class="p15">~faculty.(12)</p>
176 <p class="p4"><br></p>
177 <p class="p16">/*// safety (not yet implemented)</p>
178 <p class="p16">Maybe.maxDepth = 1e2; // higher depth is risky..</p>
179 <p class="p16">~faculty = { |x|<span class="Apple-converted-space">  </span>x * ~faculty.apply(x - 1)<span class="Apple-converted-space">  </span>}; // infinite recursion</p>
180 <p class="p16">~faculty.(12)</p>
181 <p class="p19"><br></p>
182 <p class="p16">Maybe.maxDepth = nil; // unsafe again.*/</p>
183 <p class="p4"><br></p>
184 <p class="p4"><br></p>
185 <p class="p17">//////////////// recursion prevention tests</p>
186 <p class="p4"><br></p>
187 <p class="p15">~b = ~a;</p>
188 <p class="p15">~a = ~b;</p>
189 <p class="p15">~a.value; <span class="s8">// =&gt; nil</span></p>
190 <p class="p4"><br></p>
191 <p class="p4"><br></p>
192 <p class="p15">~a = ~b;</p>
193 <p class="p15">~b = ~c;</p>
194 <p class="p15">~c = ~a;</p>
195 <p class="p15">~a.value; <span class="s8">// =&gt; nil</span></p>
196 <p class="p4"><br></p>
197 <p class="p15">~a = ~b + ~c;</p>
198 <p class="p15">~c = ~a;</p>
199 <p class="p15">~a.value; <span class="s8">// =&gt; nil</span></p>
200 <p class="p4"><br></p>
201 <p class="p4"><br></p>
202 <p class="p15">~a = ~b;</p>
203 <p class="p15">~b = 19;</p>
204 <p class="p15">~a.value; <span class="s8">// =&gt; 19</span></p>
205 <p class="p15">~b.value; <span class="s8">// =&gt; 19</span></p>
206 <p class="p4"><br></p>
207 <p class="p17">// function evaluation and argument passing</p>
208 <p class="p4"><br></p>
209 <p class="p15">~a = { <span class="s13">|x|</span> x + 2 };</p>
210 <p class="p15">~a.value;<span class="Apple-converted-space">  </span><span class="s8">// =&gt; nil</span></p>
211 <p class="p4"><br></p>
212 <p class="p15">~a.value(~c);<span class="Apple-converted-space">  </span><span class="s8">// =&gt; nil</span></p>
213 <p class="p15">~b = 2000;</p>
214 <p class="p15">~a.value(~b); <span class="s8">// =&gt; 2002</span></p>
215 <p class="p15">~x = [600, 1000];</p>
216 <p class="p4"><br></p>
217 <p class="p15">(~a + 1).value(~b); <span class="s15">// 2003</span></p>
218 <p class="p15">(~a + 1).value(~x); <span class="s15">// [ 603, 1003 ]</span></p>
219 <p class="p15">(~a + 1).value({ 8 }); <span class="s15">// binary op func.</span></p>
220 <p class="p15">(~a + 1).value({ 5 + 3 }).value <span class="s15">// 11</span></p>
221 <p class="p4"><br></p>
222 <p class="p15">~a = { <span class="s13">|x|</span> x + 2 + ~b };</p>
223 <p class="p15">~a.value(8); <span class="s8">// 2010</span></p>
224 <p class="p4"><br></p>
225 <p class="p15">~c = <span class="s13">nil</span>;</p>
226 <p class="p15">~a = { <span class="s13">|x|</span><span class="Apple-converted-space">  </span>x + 2 + ~c }; <span class="s15">// ~c is undefined.</span></p>
227 <p class="p15">~a.value(8); <span class="s8">// =&gt; nil</span></p>
228 <p class="p4"><br></p>
229 <p class="p17"><span class="s2">~c = 100; </span>// define ~c</p>
230 <p class="p4"><br></p>
231 <p class="p17"><span class="s2">~a.value(8); </span>// now returns a value.</p>
232 <p class="p4"><br></p>
233 <p class="p17"><span class="s2">~c = ~b; </span>// now recursion?</p>
234 <p class="p15">~b = ~a;</p>
235 <p class="p17"><span class="s2">~a.value(8); </span>// caught recursion<span class="s2"><span class="Apple-converted-space"> </span></span><span class="s8"> =&gt; nil</span></p>
236 <p class="p4"><br></p>
237 <p class="p15">~c = { 100.rand }; <span class="s15">// ~c is a function</span></p>
238 <p class="p4"><br></p>
239 <p class="p15">~a.value(8);</p>
240 <p class="p15">~a.value(8);</p>
241 <p class="p4"><br></p>
242 <p class="p15">~c = { ~a + ~b };</p>
243 <p class="p17"><span class="s2">~a.value(8);<span class="Apple-tab-span"> </span></span>// ~c is a recursion with ~a<span class="Apple-converted-space"> </span><span class="s2"> </span><span class="s8">=&gt; nil</span></p>
244 <p class="p4"><br></p>
245 <p class="p4"><br></p>
246 <p class="p17">// function composition</p>
247 <p class="p15">~a = {<span class="s13">|x|</span> x + 1 };</p>
248 <p class="p17"><span class="s2">~v = ~a &lt;&gt; ~a &lt;&gt; ~a; </span>// same as: { ~a.(~a.(~a)) }</p>
249 <p class="p15">~v.value(0); <span class="s8">// =&gt; 3</span></p>
250 <p class="p4"><br></p>
251 <p class="p15">~a = {<span class="s13">|x|</span> x + 2 };</p>
252 <p class="p17"><span class="s2">~v.value(0); </span>// transparent.<span class="Apple-converted-space"> </span><span class="s8"> =&gt; 6</span></p>
253 <p class="p4"><br></p>
254 <p class="p17">// {|x| x }.valueEnvir // doesn't work with current implementation of Function:valueEnvir</p>
255 <p class="p4"><br></p>
256 <p class="p4"><br></p>
257 <p class="p17">// calculations with functions:</p>
258 <p class="p15">~c = 0;</p>
259 <p class="p15">~a = { <span class="s13">|ff|</span> { ff = ff + 1; ~c + ff + 2 + ~c } };</p>
260 <p class="p15">~x = ~a.value(8);</p>
261 <p class="p17"><span class="s2">~x.value; </span>// return 11, 12, 13...</p>
262 <p class="p15">~x.value;</p>
263 <p class="p15">~x.value;<span class="Apple-converted-space"> </span></p>
264 <p class="p15">~c = 100;</p>
265 <p class="p17"><span class="s2">~x.value; </span>// return 214, 215 ...</p>
266 <p class="p15">~x.value;</p>
267 <p class="p4"><br></p>
268 <p class="p17">// binary op functions:</p>
269 <p class="p15">~c = 0;</p>
270 <p class="p15">~a = { <span class="s13">|ff|</span> { [600, 800] } + { ff + 2 + ~c } };</p>
271 <p class="p4"><br></p>
272 <p class="p15">~x = ~a.value(8);</p>
273 <p class="p17"><span class="s2">~x.value; </span>// return [ 610, 810 ]</p>
274 <p class="p4"><br></p>
275 <p class="p15">~c = { [10, -10].rand };</p>
276 <p class="p17"><span class="s2">~x.value; </span>// return random between [ 610..620, 800..810 ]</p>
277 <p class="p4"><br></p>
278 <p class="p4"><br></p>
279 <p class="p4"><br></p>
280 <p class="p4"><br></p>
281 <p class="p4"><br></p>
282 <p class="p4"><br></p>
283 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
284 </body>
285 </html>