| blob | f22d70bd9b6c6d5835c97b883ea1fc50f5b081f0 |
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)
153 section:: IOStream operators
154 definitionlist::
155 ## code:: stream << object :: || represent the object as a string and add to the stream.
156 A common usage is with the Post class, to write output to the post window.
157 code::
158 Post << "Here is a random number: " << 20.rand << ".\n";
159 Here is a random number: 13.
160 ::
162 ## code:: stream <<* collection :: || add each item of the collection to the stream.
163 code::
164 Post << [0, 1, 2, 3]
165 [ 0, 1, 2, 3 ]
167 Post <<* [0, 1, 2, 3]
168 0, 1, 2, 3
169 ::
171 ## code:: stream <<< object :: || add the object's compile string to the stream.
172 code::
173 Post <<< "a string"
174 "a string"
175 ::
176 ## code:: stream <<<* collection :: || add each item's compile string to the stream.
177 ::
179 section:: Conditional execution operators
180 definitionlist::
181 ## code:: object ? object :: || nil check (no .value)
182 ## code:: object ?? function :: || nil check (.value, function is inlined)
183 If the object is nil, the second expression's value will be used; otherwise, it will be the first object.
184 code::
185 a = [nil, 5];
187 10.do({ (a.choose ? 20.rand).postln });
188 10.do({ (a.choose ?? { 20.rand }).postln });
189 ::
190 code:: ?? { } :: is generally recommended. code::?:: always evaluates the second expression, even if its value will not be used.
191 code:: ?? :: evaluates the function conditionally (only when needed).
192 If the function defines no variables, the function will be inlined for speed.
194 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.
195 code::
196 f = { |slider, parent|
197 slider = slider ?? { SCSlider.new(parent, Rect(0, 0, 100, 20)) };
198 slider.value_(0);
199 };
200 ::
201 If the first line inside the function instead read code::
202 slider = slider ? SCSlider.new(parent, Rect(0, 0, 100, 20));
203 ::
204 , a new slider would be created even if it is not needed, or used.
206 ## code:: object !? function :: || execute function if object is not nil.
207 code::
208 a = [10, nil].choose;
209 a !? { "ran func".postln };
210 // equivalent of:
211 if (a.notNil) { "ran func".postln };
212 ::
213 Used when an operation requires a variable not to be empty.
214 code::
215 f = { |a| a + 5 };
216 f.value
217 // error: nil does not understand +
219 f = { |a| a !? { a+5 } };
220 f.value
221 nil // no error
222 f.value(2)
223 7
224 ::
225 ::
227 section:: Miscellaneous operators
228 definitionlist::
229 ## code:: object ! number :: || same as code:: object.dup(number) ::
230 code::
231 15 ! 5
232 [ 15, 15, 15, 15, 15 ]
233 ::
234 If the object is a function, it behaves like Array.fill(number, function).
235 code::
236 { 10.rand } ! 5
237 [ 8, 9, 3, 8, 0 ]
238 ::
239 ## code:: object -> object :: || creates an link::Classes/Association::, used in dictionaries.
240 ## code:: expression <! expression :: || bypass value of second expression.
241 This operator evaluates both expressions, and returns the value of the first.
242 code::
243 a = 0;
244 0
246 // a is incremented twice, but the return value (1)
247 // comes from the first increment (0 + 1)
248 (a = a + 1) <! (a = a + 1)
249 1
251 a // a's value reflects both increments
252 2
253 ::
255 ## code:: function <> function :: || function composition operator.
256 This operator returns a new function, which evaluates the second function and passes the result to the first function.
257 code::
258 f = { |a| a * 5 } <> {|a| a + 2 };
259 f.(10);
260 60 // == (10+2) * 5
261 ::
262 An array as argument is passed through the chain:
263 code::
264 f.([10, 75, 512]);
265 [ 60, 385, 2570 ] // == ([10, 75, 512]+2) * 5
266 ::
267 ::
269 section:: Symbolic notations to define literals/other objects
270 definitionlist::
271 ## code:: $ :: || character prefix: code:: "ABC".at(0) == $A ::
272 ## code:: '' :: or code:: \ :: || define a literal link::Classes/Symbol:: : code:: 'abc' === \abc ::
273 ## code:: "" :: || define a literal link::Classes/String:: : code:: "SuperCollider is the best" ::
274 ## code:: [item, item...] :: || define an link::Classes/Array:: containing given items
275 ## code:: Set[item, item...] :: || define a link::Classes/Set:: -- any link::Classes/Collection:: class name can be used other than Set
276 ## code:: #[item, item...] :: || define a literal link::Classes/Array::
277 ## code:: (a:1, b:2) :: || define an link::Classes/Event:: (same as code:: Event[\a -> 1, \b -> 2] ::)
278 ## code:: ` :: (backtick or backquote) || define a link::Classes/Ref:: : code:: `1 == Ref(1), `(a+1) == Ref(a+1) ::
279 ## code:: \ :: || inside a string or symbol, escapes the next character
280 code::
281 "abc\"def\"ghi"
282 abc"def"ghi
284 'abc\'def\'ghi'
285 abc'def'ghi
286 ::
287 definitionlist::
288 ## code:: \t :: || tab character
289 ## code:: \n :: || newline character
290 ## code:: \l :: || linefeed character
291 ## code:: \r :: || carriage return character
292 ## code:: \\ :: || \ character
293 ::
295 ## code:: { } :: || define an open function
296 ## code:: #{ } :: || define a closed function
297 ## code:: (_ * 2) :: || define a function code:: { |a| a * 2 } :: (see link::Reference/Partial-Application::)
298 ::
300 section:: Argument definition
301 definitionlist::
302 ## code:: |a, b, c| :: || define function/method arguments
303 ## code:: |a, b ... c| :: || define function/method arguments; arguments after a and b will be placed into c as an array
304 ## code:: #a, b, c = myArray ::|| assign consecutive elements of myArray to multiple variables
305 ## code:: #a, b ... c = myArray :: || assign first two elements to a and b; the rest as an array into c
306 ::
308 section:: Where f is a function
309 definitionlist::
310 ## code:: f.( ) :: || evaluate the function with the arguments in parentheses
311 ## code:: f.(*argList) :: || evaluate the function with the arguments in an array
312 ## code:: f.(anArgName: value) :: || keyword addressing of function or method arguments
313 code::
314 f = { |a, b| a * b };
315 f.(2, 4);
316 f.(*[2, 4]);
317 f.(a: 2, b: 4);
318 ::
319 ## code:: SomeClass.[index] :: || Equivalent to SomeClass.at(index) -- Instr.at is a good example
320 ## code:: myObject.method(*array) :: || call the method with the arguments in an array
321 ## code:: obj1 method: obj2 :: || same as code::obj1.method(obj2):: or code::method(obj1, obj2)::.
322 This works only with single-argument methods like binary operators.
323 ::
325 section:: Class and instance variable access
327 Inside a class definition (see link::Tutorials/Writing-Classes:: ):
328 code::
329 {
330 classvar <a, // Define a class variable with a getter method (for outside access)
331 >b, // Define a class variable with a setter method
332 <>c; // Define a class variable with both a getter and setter method
334 var <a, // Define an instance variable with a getter method (for outside access)
335 >b, // Define an instance variable with a setter method
336 <>c; // Define an instance variable with both a getter and setter method
338 // methods go here ...
339 }
340 ::
341 These notations do not apply to variables defined within methods.
343 definitionlist::
344 ## code:: ^someExpression :: || Inside a method definition: return the expression's value to the caller
345 ## code:: instVar_ { } :: || define a setter for an instance variable
346 ## code:: myObject.instVar = x; :: || invoke the setter: code:: (myObject.instVar_(x); x) ::
347 ::
349 section:: Array series and indexing
350 definitionlist::
351 ## code:: (a..b) :: || produces an array consisting of consecutive integers from a to b
352 ## code:: (a, b..c) :: || e.g.: (1, 3..9) produces [1, 3, 5, 7, 9]
353 ## code:: (..b) :: || produces an array 0 through b
354 ## code:: (a..) :: || not legal (no endpoint given)
356 ## code:: a[i..j] :: || same as code:: a.copyRange(i, j) ::
357 ## code:: a[i, j..k] :: || e.g.: code:: a[1, 3..9] :: retrieves array elements 1, 3, 5, 7, 9
358 ## code:: a[..j] :: || same as code:: a.copyRange(0, j) ::
359 ## code:: a[j..] :: || same as code:: a.copyRange(i, a.size-1) :: (this is OK--Array is finite)
361 ## code:: ~ :: || access an environment variable
362 ## code:: ~abc :: || compiles to code:: \abc.envirGet ::
363 ## code:: ~abc = value :: || compiles to code:: \abc.envirPut(value) ::
364 ::
366 section:: Adverbs to math operators
367 (see link::Reference/Adverbs:: )
369 e.g.:
370 code::
371 [1, 2, 3] * [2, 3, 4]
372 [ 2, 6, 12 ]
374 [1, 2, 3] *.t [2, 3, 4]
375 [ [ 2, 3, 4 ], [ 4, 6, 8 ], [ 6, 9, 12 ] ]
376 ::
377 definitionlist::
378 ## code:: .s :: || output length is the shorter of the two arrays
379 ## code:: .f :: || use folded indexing instead of wrapped indexing
380 ## code:: .t :: || table-style
381 ## code:: .x :: || cross (like table, except that the results of each operation are concatenated, not added as another dimension)
382 ## code:: .0 :: || operator depth (see link::Guides/J-concepts-in-SC:: )
383 ## code:: .1 :: || etc.
384 ::