Operators:
Filter:
Overviews |

# Operators

common unary and binary operators

SuperCollider supports operator overloading. Operators can thus be applied to a variety of different objects; Numbers, Ugens, Collections, and so on. When operators are applied to ugens they result in BinaryOpUGens or UnaryOpUGens, through the methods of AbstractFunction.

This is a list of some of the common unary and binary operators that are implemented by several classes. See the specific classes for details and other operators.

You can see which classes implements a specific operator by clicking on the method name.

## Unary Operators

Unary operators may be written in two ways:

Inversion.

### reciprocal

Reciprocal (1/x).

Absolute value.

### floor

Next lower integer.

### ceil

Next higher integer.

Fractional part.

### sign

Sign function.

#### Returns:

-1 when a < 0, +1 when a > 0, 0 when a is 0

Squared value.

`a*a`

Cubed value.

`a*a*a`

### sqrt

Square root.

#### Discussion:

The definition of square root is extended for signals so that sqrt(a) when a<0 returns -sqrt(-a).

Exponential.

### midicps

Convert MIDI note number to cycles per second.

### cpsmidi

Convert cycles per second to MIDI note.

### midiratio

Convert an interval in MIDI notes into a frequency ratio.

### ratiomidi

Convert a frequency ratio to an interval in MIDI notes.

### dbamp

Convert decibels to linear amplitude.

### ampdb

Convert linear amplitude to decibels.

### octcps

Convert decimal octaves to cycles per second.

### cpsoct

Convert cycles per second to decimal octaves.

### Random operators

See also Randomness

### rand

Returns an evenly distributed random value between this and zero.

### rand2

Returns an evenly distributed random value between [+this ... - this].

### linrand

Returns a linearly distributed random value between this and zero.

### bilinrand

Returns a linearly distributed random value between [+this ... - this].

### sum3rand

Returns a value from a gaussian-like random distribution between this and zero. Larry Polansky's poor man's gaussian generator, follows the formula:

### coin

Returns one or zero with the probability given by the argument.

### log

Natural logarithm.

### log2

Base 2 logarithm.

### log10

Base 10 logarithm.

Sine.

Cosine.

Tangent.

Arcsine.

Arccosine.

Arctangent.

Hyperbolic sine.

### cosh

Hyperbolic cosine.

### tanh

Hyperbolic tangent.

### distort

Nonlinear distortion.

#### Discussion:

The formula used is :

Here is an example :

### softclip

Nonlinear distortion.

#### Discussion:

Distortion with a perfectly linear region from -0.5 to +0.5

### isPositive

Test if signal is >= 0.

### isNegative

Test if signal is < 0.

### isStrictlyPositive

Test if signal is > 0.

## Binary Operators

Three different syntaxes can be used for binary operators consisting of letters:

Operators consisting of symbols are written like this:

Addition.

Subtraction.

Multiplication.

Division.

### %

Floating point modulo.

### **

Exponentiation. When used with UGens which produce a negative signal this function extends the usual definition of exponentiation and returns `neg(neg(a) ** b)`. This allows exponentiation of negative signal values by noninteger exponents. For the normal behaviour use pow (see below).

Exponentiation.

### lcm

Least common multiple. This definition extends the usual definition and returns a negative number if any of the operands is negative. This makes it consistent with the lattice-theoretical interpretation and its idempotency, commutative, associative, absorption laws.

Following the example of the programming language J (see: J concepts in SC), lcm is analogous to logical and (see also: http://www.jsoftware.com/papers/eem/gcd.htm).

### gcd

Greatest common divisor. This definition extends the usual definition and returns a negative number if both operands are negative. This makes it consistent with the lattice-theoretical interpretation and its idempotency, commutative, associative, absorption laws.

"greater" means "divisible by" in this interpretation, so `gcd(-1, -1)` returns a negative number. This is necessary to make the whole system consistent (fundamental law of arithmetics, idempotency and absorption laws would fail). See examples below.

Following the example of the programming language J (see: J concepts in SC), gcd is analogous to logical or (see also: http://www.jsoftware.com/papers/eem/gcd.htm).

Here is an overview of how negative numbers are treated:

Less than.

### <=

Less than or equal.

### >

Greater than.

#### Discussion:

With UGens, this can be useful for triggering purposes, among other things:

### >=

Greater than or equal.

Equal.

Not equal.

### <!

Return first argument.

Minimum.

Maximum.

### round

Quantization by rounding. Rounds a to the nearest multiple of b.

### trunc

Quantization by truncation. Truncate a to a multiple of b.

### hypot

Hypotenuse. Returns the square root of the sum of the squares of a and b. Or equivalently, the distance from the origin to the point (x, y).

#### Discussion:

In this example, hypot is used to calculate a doppler shift pitch and amplitude based on distance.

The next example uses the distance to modulate a delay line.

### hypotApx

Hypotenuse approximation. Returns an approximation of the square root of the sum of the squares of x and y.

#### Discussion:

The formula used is :

hypotApx is used to implement Complex method magnitudeApx. This should not be used for simulating a doppler shift because it is discontinuous. Use hypot.

See also .hypot, .atan2.

### atan2

Returns the arctangent of y/x.

#### Discussion:

OK, now we can add a pan to the .hypot doppler examples by using atan2 to find the azimuth, or direction angle, of the sound source. Assume speakers at +/- 45 degrees and clip the direction to between those.

### ring1

Ring modulation plus first source.

#### Discussion:

Return the value of ((a*b) + a). This is more efficient than using separate unit generators for the multiply and add.

See also .*, .ring1, .ring2, .ring3, .ring4.

same as :

normal ring modulation:

### ring2

Ring modulation plus both sources.

#### Discussion:

Return the value of ((a*b) + a + b). This is more efficient than using separate unit generators for the multiply and adds.

same as :

### ring3

Ring modulation variant.

#### Discussion:

Return the value of (a*a *b). This is more efficient than using separate unit generators for each multiply.

same as :

### ring4

Ring modulation variant.

#### Discussion:

Return the value of ((a*a *b) - (a*b*b)). This is more efficient than using separate unit generators for each operation.

same as :

### sumsqr

Sum of squares.

#### Discussion:

Return the value of (a*a) + (b*b). This is more efficient than using separate unit generators for each operation.

same as :

### difsqr

Difference of squares.

#### Discussion:

Return the value of (a*a) - (b*b). This is more efficient than using separate unit generators for each operation.

same as :

### sqrsum

Square of the sum.

#### Discussion:

Return the value of (a + b)**2. This is more efficient than using separate unit generators for each operation.

same as :

### sqrdif

Square of the difference.

#### Discussion:

Return the value of (a - b)**2. This is more efficient than using separate unit generators for each operation.

same as :

### absdif

Absolute value of the difference. `abs(a - b)`

### moddif

On a circle, there are two distances between two points. This operator returns the smaller value of the two.

### thresh

Thresholding.

#### Discussion:

0 when a < b, otherwise a.

### amclip

Two quadrant multiply.

#### Discussion:

0 when b <= 0, a*b when b > 0

### scaleneg

Scale negative part of input.

#### Discussion:

a*b when a < 0, otherwise a.

### clip2

Bilateral clipping.

#### Discussion:

clips input wave a to +/- b

### wrap2

Bilateral wrapping.

#### Discussion:

wraps input wave to +/- b

### fold2

Bilateral folding.

#### Discussion:

folds input wave a to +/- b

### excess

Residual of clipping.

#### Discussion:

Returns the difference of the original signal and its clipped form: (a - clip2(a,b)).