HelpSource/Overviews/SymbolicNotations.schelp

   1 title:: Symbolic Notations
   2 summary:: Catalog of symbolic notations in SuperCollider
   3 categories:: Language
   4 related:: Overviews/Operators, Reference/Syntax-Shortcuts
   5
   6 section:: Arithmetic operators
   7
   8 Math operators apply to many classes, including arrays and other collections.
   9
  10 Using a basic math operator on a Symbol swallows the operation (returns the symbol)
  11 code::
  12 \symbol * 5
  13 symbol
  14 ::
  15
  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 ::
  24
  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 ::
  33
  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 ::
  41
  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
  48
  49 a = b = [1, 2, 3];
  50 a === b;
  51 true        // a and b are the same array instance
  52 ::
  53
  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.
  65
  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;
  69
  70 a == 1 and: { "second condition".postln; [true, false].choose }
  71 second condition
  72 true
  73
  74 a == 1 or: { "second condition".postln; [true, false].choose }
  75 true
  76
  77 a != 1 and: { "second condition".postln; [true, false].choose }
  78 false
  79
  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
  89
  90 a = 10;
  91 a.notNil and: { "second condition".postln; (a = a+1) < 5 }
  92 second condition
  93 false
  94 ::
  95
  96 section:: Array and Collection operators
  97
  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 ::
 106
 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 ::
 117
 118 code::
 119 a = Set[2, 3, 4, 5, 6, 7];
 120 b = Set[5, 6, 7, 8, 9];
 121
 122 a - b
 123 Set[ 2, 4, 3 ]
 124
 125 b - a
 126 Set[ 8, 9 ]
 127
 128 ((a-b) | (b-a))
 129 Set[ 2, 9, 3, 4, 8 ]
 130
 131 a -- b
 132 Set[ 2, 9, 3, 4, 8 ]
 133 ::
 134
 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 ::
 153
 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 ::
 162
 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 ]
 167
 168 Post <<* [0, 1, 2, 3]
 169 0, 1, 2, 3
 170 ::
 171
 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 ::
 179
 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];
 187
 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.
 194
 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.
 206
 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 +
 219
 220 f = { |a| a !? { a+5 } };
 221 f.value
 222 nil // no error
 223 f.value(2)
 224 7
 225 ::
 226 ::
 227
 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
 246
 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
 251
 252 a       // a's value reflects both increments
 253 2
 254 ::
 255
 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 ::
 269
 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
 284
 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 ::
 295
 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 ::
 300
 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 ::
 308
 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 ::
 325
 326 section:: Class and instance variable access
 327
 328 Inside a class definition (see link::Guides/WritingClasses:: ):
 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
 334
 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
 338
 339     // methods go here ...
 340 }
 341 ::
 342 These notations do not apply to variables defined within methods.
 343
 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 ::
 349
 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)
 356
 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)
 361
 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 ::
 366
 367 section:: Adverbs to math operators
 368 (see link::Reference/Adverbs:: )
 369
 370 e.g.:
 371 code::
 372 [1, 2, 3] * [2, 3, 4]
 373 [ 2, 6, 12 ]
 374
 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 ::
 386