Overviews | Language

# Symbolic Notations

Catalog of symbolic notations in SuperCollider

## Arithmetic operators

Math operators apply to many classes, including arrays and other collections.

Using a basic math operator on a Symbol swallows the operation (returns the symbol)

`number + number`
`number - number`
subtraction
`number * number`
multiplication
`number / number`
division
`number % number`
modulo
`number ** number`
exponentiation

## Bitwise arithmetic

`number & number`
bitwise and
`number | number`
bitwise or
`number << number`
bitwise left shift
`number >> number`
bitwise right shift
`number +>> number`
unsigned bitwise right shift

## Logical operators

`object == object`
equivalence
`object === object`
identity
`object != object`
not equal to
`object !== object`
not identical to

Objects may be equivalent but not identical.

`number < number`
comparison (less than)
`number <= number`
comparison (less than or equal to)
`number > number`
comparison (greater than)
`number >= number`
comparison (greater than or equal to)

`boolean && boolean`
logical And
`boolean || boolean`
logical Or

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.

With `and:` and `or:` second-argument functions will be inlined. If you use `&&` or `||`, no inlining will be done and performance will be slower.

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.

## Array and Collection operators

`object ++ object`
concatenation
`collection +++ collection`
lamination (see J concepts in SC)
`collection @ index`
collection/array indexing: .at(index) or [index]
`collection @@ integer`
collection/array indexing: .wrapAt(int)
`collection @|@ integer`
collection/array indexing: .foldAt(int)
`collection |@| integer`
collection/array indexing: .clipAt(int)

## Set operators

`set & set`
intersection of two sets
`set | set`
union of two sets
`setA - setB`
difference of sets (elements of setA not found in setB)
`set -- set`
symmetric difference:

## Geometry operators

`number @ number`
make a Point of two numbers

`point @ point`
make a Rect of two Points

`ugen @ ugen`
create a Point with two UGens
`rect & rect`
intersection of two rectangles
`rect | rect`
union of two rectangles (returns a Rect whose boundaries exactly encompass both Rects)

## IOStream operators

`stream << object`
represent the object as a string and add to the stream. A common usage is with the Post class, to write output to the post window.
`stream <<* collection`
add each item of the collection to the stream.
`stream <<< object`
add the object's compile string to the stream.

`stream <<<* collection`
add each item's compile string to the stream.

## Conditional execution operators

`object ? object`
nil check (no .value)
`object ?? function`
nil check (.value, function is inlined) If the object is nil, the second expression's value will be used; otherwise, it will be the first object.

`?? { }` is generally recommended. `?` always evaluates the second expression, even if its value will not be used. `??` evaluates the function conditionally (only when needed). If the function defines no variables, the function will be inlined for speed.

Especially useful when the absence of an object requires a new object to be created. In this example, it's critical that a new Slider not be created if the object was already passed in.

If the first line inside the function instead read

, a new slider would be created even if it is not needed, or used.

`object !? function`
execute function if object is not nil.

Used when an operation requires a variable not to be empty.

## Miscellaneous operators

`object ! number`
same as `object.dup(number)`

If the object is a function, it behaves like Array.fill(number, function).

`object -> object`
creates an Association, used in dictionaries.
`expression <! expression`
bypass value of second expression. This operator evaluates both expressions, and returns the value of the first.
`function <> function`
function composition operator. This operator returns a new function, which evaluates the second function and passes the result to the first function.

An array as argument is passed through the chain:

## Symbolic notations to define literals/other objects

`\$`
character prefix: `"ABC".at(0) == \$A`
`''` or `\`
define a literal Symbol : `'abc' === \abc`
`""`
define a literal String : `"SuperCollider is the best"`
`[item, item...]`
define an Array containing given items
`Set[item, item...]`
define a Set -- any Collection class name can be used other than Set
`#[item, item...]`
define a literal Array
`(a:1, b:2)`
define an Event (same as `Event[\a -> 1, \b -> 2]`)
``` (backtick or backquote)
define a Ref : ``1 == Ref(1), `(a+1) == Ref(a+1)`
`\`
inside a string or symbol, escapes the next character

`\t`
tab character
`\n`
newline character
`\l`
linefeed character
`\r`
carriage return character
`\\`
\ character
`{ }`
define an open function
`#{ }`
define a closed function
`(_ * 2)`
define a function `{ |a| a * 2 }` (see Partial Application)

## Argument definition

`|a, b, c|`
define function/method arguments
`|a, b ... c|`
define function/method arguments; arguments after a and b will be placed into c as an array
`#a, b, c = myArray`
assign consecutive elements of myArray to multiple variables
`#a, b ... c = myArray`
assign first two elements to a and b; the rest as an array into c

## Where f is a function

`f.( )`
evaluate the function with the arguments in parentheses
`f.(*argList)`
evaluate the function with the arguments in an array
`f.(anArgName: value)`
keyword addressing of function or method arguments

`SomeClass.[index]`
Equivalent to SomeClass.at(index) -- Instr.at is a good example
`myObject.method(*array)`
call the method with the arguments in an array
`obj1 method: obj2`
same as `obj1.method(obj2)` or `method(obj1, obj2)`. This works only with single-argument methods like binary operators.

## Class and instance variable access

Inside a class definition (see Writing Classes ):

These notations do not apply to variables defined within methods.

`^someExpression`
Inside a method definition: return the expression's value to the caller
`instVar_ { }`
define a setter for an instance variable
`myObject.instVar = x;`
invoke the setter: `(myObject.instVar_(x); x)`

## Array series and indexing

`(a..b)`
produces an array consisting of consecutive integers from a to b
`(a, b..c)`
e.g.: (1, 3..9) produces [1, 3, 5, 7, 9]
`(..b)`
produces an array 0 through b
`(a..)`
not legal (no endpoint given)
`a[i..j]`
same as `a.copySeries(i, j)` (see ArrayedCollection: -copySeries)
`a[i, j..k]`
e.g.: `a[1, 3..9]` retrieves array elements 1, 3, 5, 7, 9
`a[..j]`
same as `a.copySeries(0, j)`
`a[j..]`
same as `a.copySeries(i, a.size-1)` (this is OK--Array is finite)
`~`
access an environment variable
`~abc`
compiles to `\abc.envirGet`
`~abc = value`
compiles to `\abc.envirPut(value)`

## Adverbs to math operators

e.g.:

`.s`
output length is the shorter of the two arrays
`.f`
use folded indexing instead of wrapped indexing
`.t`
table-style
`.x`
cross (like table, except that the results of each operation are concatenated, not added as another dimension)
`.0`
operator depth (see J concepts in SC )
`.1`
etc.