| blob | ceb674d1300d4ad88f8dc869760d6bfb0256d72c |
1 title:: Symbolic Notations
2 summary:: Catalog of symbolic notations in SuperCollider
3 categories:: Language
4 related:: Overviews/Operators, Reference/Syntax-Shortcuts
6 section:: Arithmetic operators
8 Math operators apply to many classes, including arrays and other collections.
10 Using a basic math operator on a Symbol swallows the operation (returns the symbol)
11 code::
12 \symbol * 5
13 symbol
14 ::
16 definitionlist::
17 ## code:: number + number :: || addition
18 ## code:: number - number :: || subtraction
19 ## code:: number * number :: || multiplication
20 ## code:: number / number :: || division
21 ## code:: number % number :: || modulo
22 ## code:: number ** number :: || exponentiation
23 ::
25 section:: Bitwise arithmetic
26 definitionlist::
27 ## code:: number & number :: || bitwise and
28 ## code:: number | number :: || bitwise or
29 ## code:: number << number :: || bitwise left shift
30 ## code:: number >> number :: || bitwise right shift
31 ## code:: number +>> number :: || unsigned bitwise right shift
32 ::
34 section:: Logical operators
35 definitionlist::
36 ## code:: object == object :: || equivalence
37 ## code:: object === object :: || identity
38 ## code:: object != object :: || not equal to
39 ## code:: object !== object :: || not identical to
40 ::
42 Objects may be equivalent but not identical.
43 code::
44 [1, 2, 3] == [1, 2, 3]
45 true
46 [1, 2, 3] === [1, 2, 3]
47 false // a and b are two different array instances with the same contents
49 a = b = [1, 2, 3];
50 a === b;
51 true // a and b are the same array instance
52 ::
54 definitionlist::
55 ## code:: number < number :: || comparison (less than)
56 ## code:: number <= number :: || comparison (less than or equal to)
57 ## code:: number > number :: || comparison (greater than)
58 ## code:: number >= number :: || comparison (greater than or equal to)
59 ::
60 definitionlist::
61 ## code:: boolean && boolean :: || logical And
62 ## code:: boolean || boolean :: || logical Or
63 ::
64 When a function is the second operand, these operators perform short-circuiting (i.e., the function is executed only when its result would influence the result of the operation). This is recommended for speed.
66 With code:: and: :: and code:: or: :: second-argument functions will be inlined. If you use code::&&:: or code::||::, no inlining will be done and performance will be slower.
67 code::
68 a = 1;
70 a == 1 and: { "second condition".postln; [true, false].choose }
71 second condition
72 true
74 a == 1 or: { "second condition".postln; [true, false].choose }
75 true
77 a != 1 and: { "second condition".postln; [true, false].choose }
78 false
80 a != 1 or: { "second condition".postln; [true, false].choose }
81 second condition
82 true
83 ::
84 In this case, the second condition will cause an error if a is nil, because nil does not understand addition. a.notNil is a safeguard to ensure the second condition makes sense.
85 code::
86 a = nil;
87 a.notNil and: { "second condition".postln; (a = a+1) < 5 }
88 false
90 a = 10;
91 a.notNil and: { "second condition".postln; (a = a+1) < 5 }
92 second condition
93 false
94 ::
96 section:: Array and Collection operators
98 definitionlist::
99 ## code:: object ++ object :: || concatenation
100 ## code:: collection +++ collection :: || lamination (see link::Guides/J-concepts-in-SC::)
101 ## code:: collection @ index :: || collection/array indexing: .at(index) or [index]
102 ## code:: collection @@ integer :: || collection/array indexing: .wrapAt(int)
103 ## code:: collection @|@ integer :: || collection/array indexing: .foldAt(int)
104 ## code:: collection |@| integer :: || collection/array indexing: .clipAt(int)
105 ::
107 section:: Set operators
108 definitionlist::
109 ## code:: set & set :: || intersection of two sets
110 ## code:: set | set :: || union of two sets
111 ## code:: setA - setB :: || difference of sets (elements of setA not found in setB)
112 ## code:: set -- set :: || symmetric difference:
113 code::
114 (setA -- setB) == ((setA - setB) | (setB - setA))
115 ::
116 ::
118 code::
119 a = Set[2, 3, 4, 5, 6, 7];
120 b = Set[5, 6, 7, 8, 9];
122 a - b
123 Set[ 2, 4, 3 ]
125 b - a
126 Set[ 8, 9 ]
128 ((a-b) | (b-a))
129 Set[ 2, 9, 3, 4, 8 ]
131 a -- b
132 Set[ 2, 9, 3, 4, 8 ]
133 ::
135 section:: Geometry operators
136 definitionlist::
137 ## code:: number @ number :: || make a link::Classes/Point:: of two numbers
138 code::
139 x @ y
140 // returns:
141 Point(x, y)
142 ::
143 ## code:: point @ point :: || make a link::Classes/Rect:: of two link::Classes/Point::s
144 code::
145 Point(left, top) @ Point(right, bottom)
146 // returns:
147 Rect(left, top, right-left, bottom-top)
148 ::
149 ## code:: ugen @ ugen :: || create a Point with two link::Classes/UGen::s
150 ## code:: rect & rect :: || intersection of two rectangles
151 ## code:: rect | rect :: || union of two rectangles (returns a Rect whose boundaries exactly encompass both Rects)
152 ::
154 section:: IOStream operators
155 definitionlist::
156 ## code:: stream << object :: || represent the object as a string and add to the stream.
157 A common usage is with the Post class, to write output to the post window.
158 code::
159 Post << "Here is a random number: " << 20.rand << ".\n";
160 Here is a random number: 13.
161 ::
163 ## code:: stream <<* collection :: || add each item of the collection to the stream.
164 code::
165 Post << [0, 1, 2, 3]
166 [ 0, 1, 2, 3 ]
168 Post <<* [0, 1, 2, 3]
169 0, 1, 2, 3
170 ::
172 ## code:: stream <<< object :: || add the object's compile string to the stream.
173 code::
174 Post <<< "a string"
175 "a string"
176 ::
177 ## code:: stream <<<* collection :: || add each item's compile string to the stream.
178 ::
180 section:: Conditional execution operators
181 definitionlist::
182 ## code:: object ? object :: || nil check (no .value)
183 ## code:: object ?? function :: || nil check (.value, function is inlined)
184 If the object is nil, the second expression's value will be used; otherwise, it will be the first object.
185 code::
186 a = [nil, 5];
188 10.do({ (a.choose ? 20.rand).postln });
189 10.do({ (a.choose ?? { 20.rand }).postln });
190 ::
191 code:: ?? { } :: is generally recommended. code::?:: always evaluates the second expression, even if its value will not be used.
192 code:: ?? :: evaluates the function conditionally (only when needed).
193 If the function defines no variables, the function will be inlined for speed.
195 Especially useful when the absence of an object requires a new object to be created. In this example, it's critical that a new SCSlider not be created if the object was already passed in.
196 code::
197 f = { |slider, parent|
198 slider = slider ?? { SCSlider.new(parent, Rect(0, 0, 100, 20)) };
199 slider.value_(0);
200 };
201 ::
202 If the first line inside the function instead read code::
203 slider = slider ? SCSlider.new(parent, Rect(0, 0, 100, 20));
204 ::
205 , a new slider would be created even if it is not needed, or used.
207 ## code:: object !? function :: || execute function if object is not nil.
208 code::
209 a = [10, nil].choose;
210 a !? { "ran func".postln };
211 // equivalent of:
212 if (a.notNil) { "ran func".postln };
213 ::
214 Used when an operation requires a variable not to be empty.
215 code::
216 f = { |a| a + 5 };
217 f.value
218 // error: nil does not understand +
220 f = { |a| a !? { a+5 } };
221 f.value
222 nil // no error
223 f.value(2)
224 7
225 ::
226 ::
228 section:: Miscellaneous operators
229 definitionlist::
230 ## code:: object ! number :: || same as code:: object.dup(number) ::
231 code::
232 15 ! 5
233 [ 15, 15, 15, 15, 15 ]
234 ::
235 If the object is a function, it behaves like Array.fill(number, function).
236 code::
237 { 10.rand } ! 5
238 [ 8, 9, 3, 8, 0 ]
239 ::
240 ## code:: object -> object :: || creates an link::Classes/Association::, used in dictionaries.
241 ## code:: expression <! expression :: || bypass value of second expression.
242 This operator evaluates both expressions, and returns the value of the first.
243 code::
244 a = 0;
245 0
247 // a is incremented twice, but the return value (1)
248 // comes from the first increment (0 + 1)
249 (a = a + 1) <! (a = a + 1)
250 1
252 a // a's value reflects both increments
253 2
254 ::
256 ## code:: function <> function :: || function composition operator.
257 This operator returns a new function, which evaluates the second function and passes the result to the first function.
258 code::
259 f = { |a| a * 5 } <> {|a| a + 2 };
260 f.(10);
261 60 // == (10+2) * 5
262 ::
263 An array as argument is passed through the chain:
264 code::
265 f.([10, 75, 512]);
266 [ 60, 385, 2570 ] // == ([10, 75, 512]+2) * 5
267 ::
268 ::
270 section:: Symbolic notations to define literals/other objects
271 definitionlist::
272 ## code:: $ :: || character prefix: code:: "ABC".at(0) == $A ::
273 ## code:: '' :: or code:: \ :: || define a literal link::Classes/Symbol:: : code:: 'abc' === \abc ::
274 ## code:: "" :: || define a literal link::Classes/String:: : code:: "SuperCollider is the best" ::
275 ## code:: [item, item...] :: || define an link::Classes/Array:: containing given items
276 ## code:: Set[item, item...] :: || define a link::Classes/Set:: -- any link::Classes/Collection:: class name can be used other than Set
277 ## code:: #[item, item...] :: || define a literal link::Classes/Array::
278 ## code:: (a:1, b:2) :: || define an link::Classes/Event:: (same as code:: Event[\a -> 1, \b -> 2] ::)
279 ## code:: ` :: (backtick or backquote) || define a link::Classes/Ref:: : code:: `1 == Ref(1), `(a+1) == Ref(a+1) ::
280 ## code:: \ :: || inside a string or symbol, escapes the next character
281 code::
282 "abc\"def\"ghi"
283 abc"def"ghi
285 'abc\'def\'ghi'
286 abc'def'ghi
287 ::
288 definitionlist::
289 ## code:: \t :: || tab character
290 ## code:: \n :: || newline character
291 ## code:: \l :: || linefeed character
292 ## code:: \r :: || carriage return character
293 ## code:: \\ :: || \ character
294 ::
296 ## code:: { } :: || define an open function
297 ## code:: #{ } :: || define a closed function
298 ## code:: (_ * 2) :: || define a function code:: { |a| a * 2 } :: (see link::Reference/Partial-Application::)
299 ::
301 section:: Argument definition
302 definitionlist::
303 ## code:: |a, b, c| :: || define function/method arguments
304 ## code:: |a, b ... c| :: || define function/method arguments; arguments after a and b will be placed into c as an array
305 ## code:: #a, b, c = myArray ::|| assign consecutive elements of myArray to multiple variables
306 ## code:: #a, b ... c = myArray :: || assign first two elements to a and b; the rest as an array into c
307 ::
309 section:: Where f is a function
310 definitionlist::
311 ## code:: f.( ) :: || evaluate the function with the arguments in parentheses
312 ## code:: f.(*argList) :: || evaluate the function with the arguments in an array
313 ## code:: f.(anArgName: value) :: || keyword addressing of function or method arguments
314 code::
315 f = { |a, b| a * b };
316 f.(2, 4);
317 f.(*[2, 4]);
318 f.(a: 2, b: 4);
319 ::
320 ## code:: SomeClass.[index] :: || Equivalent to SomeClass.at(index) -- Instr.at is a good example
321 ## code:: myObject.method(*array) :: || call the method with the arguments in an array
322 ## code:: obj1 method: obj2 :: || same as code::obj1.method(obj2):: or code::method(obj1, obj2)::.
323 This works only with single-argument methods like binary operators.
324 ::
326 section:: Class and instance variable access
328 Inside a class definition (see link::Tutorials/Writing-Classes:: ):
329 code::
330 {
331 classvar <a, // Define a class variable with a getter method (for outside access)
332 >b, // Define a class variable with a setter method
333 <>c; // Define a class variable with both a getter and setter method
335 var <a, // Define an instance variable with a getter method (for outside access)
336 >b, // Define an instance variable with a setter method
337 <>c; // Define an instance variable with both a getter and setter method
339 // methods go here ...
340 }
341 ::
342 These notations do not apply to variables defined within methods.
344 definitionlist::
345 ## code:: ^someExpression :: || Inside a method definition: return the expression's value to the caller
346 ## code:: instVar_ { } :: || define a setter for an instance variable
347 ## code:: myObject.instVar = x; :: || invoke the setter: code:: (myObject.instVar_(x); x) ::
348 ::
350 section:: Array series and indexing
351 definitionlist::
352 ## code:: (a..b) :: || produces an array consisting of consecutive integers from a to b
353 ## code:: (a, b..c) :: || e.g.: (1, 3..9) produces [1, 3, 5, 7, 9]
354 ## code:: (..b) :: || produces an array 0 through b
355 ## code:: (a..) :: || not legal (no endpoint given)
357 ## code:: a[i..j] :: || same as code:: a.copyRange(i, j) ::
358 ## code:: a[i, j..k] :: || e.g.: code:: a[1, 3..9] :: retrieves array elements 1, 3, 5, 7, 9
359 ## code:: a[..j] :: || same as code:: a.copyRange(0, j) ::
360 ## code:: a[j..] :: || same as code:: a.copyRange(i, a.size-1) :: (this is OK--Array is finite)
362 ## code:: ~ :: || access an environment variable
363 ## code:: ~abc :: || compiles to code:: \abc.envirGet ::
364 ## code:: ~abc = value :: || compiles to code:: \abc.envirPut(value) ::
365 ::
367 section:: Adverbs to math operators
368 (see link::Reference/Adverbs:: )
370 e.g.:
371 code::
372 [1, 2, 3] * [2, 3, 4]
373 [ 2, 6, 12 ]
375 [1, 2, 3] *.t [2, 3, 4]
376 [ [ 2, 3, 4 ], [ 4, 6, 8 ], [ 6, 9, 12 ] ]
377 ::
378 definitionlist::
379 ## code:: .s :: || output length is the shorter of the two arrays
380 ## code:: .f :: || use folded indexing instead of wrapped indexing
381 ## code:: .t :: || table-style
382 ## code:: .x :: || cross (like table, except that the results of each operation are concatenated, not added as another dimension)
383 ## code:: .0 :: || operator depth (see link::Guides/J-concepts-in-SC:: )
384 ## code:: .1 :: || etc.
385 ::