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
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.

, 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)

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.