supercollider-common 1:3.8.0~repack-2 / usr / share / SuperCollider / HelpSource / Classes / SimpleNumber.schelp

CLASS:: SimpleNumber
summary:: one-dimensional value
categories:: Math
related::Classes/Polar, Classes/Complex, Classes/Float, Classes/Integer, Classes/UnaryOpUGen, Classes/BinaryOpUGen

DESCRIPTION::
Base class for numbers which can be represented by a single one dimensional value.

Most of the Unary and Binary operations are also implemented by link::Classes/UnaryOpUGen:: and link::Classes/BinaryOpUGen::, so you can get more examples by looking at the help for those.

CLASSMETHODS::

method:: new
allocates a new SimpleNumber.

INSTANCEMETHODS::

private:: prSimpleNumberSeries

subsection:: math support

method:: +
Addition


method:: -
Subtraction

method:: *
Multiplication

method:: /
Division

method:: %
Modulo

method:: mod
Modulo

method:: div
Integer Division

method:: **
Exponentiation

method:: !=
Is not

method:: >
greater than

method:: <
greater than

method:: >=
greater or equal than

method:: <=
smaller or equal than

method:: lcm
Least common multiple

method:: gcd
Greatest common divisor

method:: round
Round to multiple of aNumber
method:: roundUp
round up to a multiply of aNumber

method:: thresh

method:: min
Minimum

method:: max
Maximum

method:: wrap2

method:: trunc
Truncate to multiple of aNumber

method:: atan2
Arctangent of (this/aNumber)

method:: hypot
Square root of the sum of the squares.


method:: log
returns:: Base e logarithm.

method:: log2
returns:: Base 2 logarithm.

method:: log10
returns:: Base 10 logarithm.

method:: neg
returns:: negation

method:: abs
returns:: absolute value.

method:: sign
returns:: Answer -1 if negative, +1 if positive or 0 if zero.

method:: ceil
returns:: next larger integer.

method:: floor
returns:: next smaller integer

method:: sin
Sine

method:: cos
Cosine

method:: tan
Tangent

method:: asin
Arcsine

method:: acos
Arccosine

method:: atan
Arctangent

method:: sinh
Hyperbolic sine

method:: cosh
Hyperbolic cosine

method:: tanh
Hyperbolic tangent

method:: frac
fractional part

method:: squared
the square of the number

method:: cubed
the cube of the number

method:: sqrt
the square root of the number.

method:: exp
e to the power of the receiver.

method:: reciprocal
1 / this

method:: pow
this to the power of aNumber

method:: fold2
the folded value, a bitwise or with aNumber

method:: previousPowerOf
the number relative to this that is the previous power of aNumber

method:: nextPowerOf
the next power of aNumber

method:: nextPowerOfTwo
returns:: the number relative to this that is the next power of 2

method:: nextPowerOfThree
the next power of three

method:: hash
returns:: a hash value

method:: <!
returns:: the receiver. aNumber is ignored.

method:: &
Bitwise And

method::|
Bitwise Or

method:: bitXor
Bitwise Exclusive Or

method:: bitHammingDistance
Binary Hamming distance: the count of bits that are not the same in the two numbers

method:: bitTest
returns:: true if bit at index aNumber is set.

method:: bitNot
returns:: ones complement

method:: <<
Binary shift left.

method:: >>
Binary shift right.

method:: +>>
Unsigned binary shift right.

method:: rightShift
returns:: performs a binary right shift

method:: unsignedRightShift
returns:: performs an unsigned right shift

method:: leftShift
returns:: performs a binary left shift

method:: bitOr
returns:: performs a bitwise or with aNumber

method:: bitAnd
returns:: performs a bitwise and with aNumber

method:: ring1
(a * b) + a

method:: ring2
((a*b) + a + b)

method:: ring3
(a * a *b)

method:: ring4
((a*a *b) - (a*b*b))

method:: difsqr
(a*a) - (b*b)

method:: sumsqr
(a*a) + (b*b)

method:: sqrdif
(a - b) ** 2

method:: sqrsum
(a + b) ** 2

method:: absdif
(a - b).abs

method:: moddif
On a circle, there are two distances between two points. This operator returns the smaller value of the two.
code::
moddif(0.75, 0, 1)
::

method:: amclip
0  when  b <= 0,  a*b  when  b > 0

method:: scaleneg
a * b when a < 0, otherwise a.

method:: clip2
clips receiver to +/- aNumber

method:: excess
Returns the difference of the receiver and its clipped form.
discussion::
code::
(a - clip2(a,b))
::

method:: madd
code::
this * a + b
::

subsection:: testing
method:: isPositive
Answer if the number is >= 0.

method:: isNegative
Answer if the number is < 0.

method:: isStrictlyPositive
Answer if the number is > 0.

method:: booleanValue
returns:: true, if strictly positive ( > 0), otherwise false (see link::Classes/Boolean::)

method:: isNaN
method:: ==

subsection:: conversion

method:: asFraction
argument::denominator
argument::fasterBetter
if true, asFraction may find a much closer approximation and do it faster.
returns:: an array of denominator and divisor of the nearest and smallest fraction

method:: asAudioRateInput
Converts this into an audiorate input.

method:: asTimeString
Compile a time string.
argument:: precision
how accurate
argument::maxDays
the maximum number of days
argument::dropDaysIfPossible
a link::Classes/Boolean::
returns:: a string corresponding to the hours:minutes:seconds based on the receiver as number of seconds
discussion::
code::
(
var start;
start = Main.elapsedTime;
{ loop({(Main.elapsedTime - start).asTimeString.postln; 0.05.wait}) }.fork;
)
::

method:: asPoint
returns:: this as link::Classes/Point::. x = y = this.

method:: asComplex
returns:: this as link::Classes/Point::. x = y = this.

method:: asWarp
argument::spec
a link::Classes/ControlSpec::
returns:: this as link::Classes/CurveWarp:: according to spec.

method:: asFloat
returns:: this as link::Classes/Float::

method:: asRect
returns:: a link::Classes/Rect:: with x = y = w = h = this.

method:: asBoolean
returns:: this as a link::Classes/Boolean::.  this > 0

method:: asQuant
returns:: the values as link::Classes/Quant::

method:: asInteger
returns:: this as link::Classes/Integer::

subsection:: timing

method::wait
within a routine, yield the number so that the clock can wait for this many beats. Outside a Routine, this trows an error (see also Routine for details).

discussion::
Create a routine by a function fork
code::
(
fork {
	1.wait;
	"I did wait".postln;
	1.0.rand.wait;
	"No you didn't".postln;
	2.wait;
	(1..).do { |i|
		"yes I did".postln;
		i.asFloat.rand.wait;
		"no you didn't".postln;
		i.wait
	}
}
)
::

method:: waitUntil
like wait, only specify a time (measured in beats of the current thread's clock). Outside a Routine, this trows an error (see also Routine for details).

method:: sleep
make the current thread sleep, until woken up by re-scheduling. Outside a Routine, this trows an error (see also Routine for details).

method:: nextTimeOnGrid
argument::clock
returns:: the next possible multiple of the clock's beats.

method:: schedBundleArrayOnClock



subsection:: series and arrays

method:: nearestInList
returns:: the value in the list closest to this

discussion::
code::
(
l = [0, 0.5, 0.9, 1];
(0, 0.05..1).collect { |i| i.nearestInList(l) }
)
::

method:: nearestInScale
argument:: scale
an array of SimpleNumbers each treated as a step in the octave.
argument:: stepsPerOctave
12 by default
returns:: the value in the collection closest to this, assuming an octave repeating table of note values.

discussion::
code::
(
l = [0, 1, 5, 9, 11]; // pentatonic scale
(60, 61..76).collect { |i| i.nearestInScale(l, 12) }
)
::

method:: series
return an arithmetic series from this over second to last.
discussion::
This is used in the shortcuts:
code::
(0..100);
(1, 3 .. 17)
::
If second is nil, it is one magnitude step towards last (1 or -1).
Examples:
code::
series(5, 7, 10);
series(5, nil, 10);
(5, 7 .. 10)
::

method:: seriesIter
returns:: a Routine that iterates over the numbers from this to last.

discussion::
Since this is a lazy operation, last may be inf, generating an endless series
(see also link::Guides/ListComprehensions::)
code::
r = seriesIter(0, 5);
r.nextN(8);
r.nextN(8);
::


subsection:: windowing

method:: rectWindow
returns:: a value for a rectangular window function between 0 and 1.

method:: hanWindow
returns:: a value for a hanning window function between 0 and 1.

method:: welWindow
returns:: a value for a welsh window function between 0 and 1.

method:: triWindow
returns:: a value for a triangle window function between 0 and 1.

subsection:: mapping

method:: distort
a nonlinear distortion function.

method:: softclip
Distortion with a perfectly linear region from -0.5 to +0.5

method:: scurve
Map receiver in the onto an S-curve.
discussion::
code::
((0..100) / 100 ).collect(_.scurve).plot
::

method:: ramp
Map receiver onto a ramp starting at 0.
discussion::
code::
((-100..100) / 100 ).collect(_.ramp).plot
::

method::magnitude
returns:: absolute value (see link::Classes/Polar::, link::Classes/Complex::)

method::angle
returns:: angle of receiver conceived as link::Classes/Polar:: or link::Classes/Complex:: number.


method:: degreeToKey
argument:: scale
an array of SimpleNumbers each treated as a step in the octave.
argument:: stepsPerOctave
12 is the standard chromatic scale.
discussion::
the value is truncated to an integer and used as an index into an octave repeating table of note values. Indices wrap around the table and shift octaves as they do.

code::
(
l = [0, 1, 5, 9, 11]; // pentatonic scale
(1, 2..15).collect{|i|
	i.degreeToKey(l, 12)
};
)
::

method:: keyToDegree
inverse of degreeToKey.
argument:: scale
an array of SimpleNumbers each treated as a step in the octave.
argument:: stepsPerOctave
12 is the standard chromatic scale.
discussion::
code::
(
l = [0, 1, 5, 9, 11]; // pentatonic scale
(60, 61..75).collect { |i| i.keyToDegree(l, 12) }
)
::
code::
(
l = [0, 1, 5, 9, 11]; // pentatonic scale
(60, 61..75).postln.collect { |i| i.keyToDegree(l, 12).degreeToKey(l) }
)
::



method::gaussCurve
map the receiver onto a gauss function.

discussion::
Uses the formula:
code::
a * (exp(squared(this - b) / (-2.0 * squared(c)))) Default values: a = 1; b = 0; c = 1
::
Example code
code::
(0..1000).normalize(-10, 10).collect { |num| num.gaussCurve }.plot;
::


method:: equalWithPrecision

argument::precision
The absolute precision, independent of the value compared

argument::relativePrecision
The precision relative to the larger absolute of the values compared.


returns:: true if receiver is closer to that than precision.

discussion::
code::
3.1.equalWithPrecision(3.0, 0.05); // false
3.1.equalWithPrecision(3.0, 0.1); // false
3.1.equalWithPrecision(3.0, 0.11); // true
3000.1.equalWithPrecision(3000.0, 0, 0.01); // true
3.1.equalWithPrecision(3.0, 0, 0.01); // false

::



method:: quantize
round the receiver to the quantum.
argument::quantum
amount.
argument::tolerance
allowed tolerance.
argument::strength
Determines how much the value is allowed to differ in the tolerance range.
discussion::
code::
((0..10) / 10).collect { |num| num.quantize(1, 0.3, 0.5) }.postcs.plot;
((0..10) / 10).collect { |num| num.quantize(1, 0.6, 0.5) }.postcs.plot;
((0..10) / 10).collect { |num| num.quantize(1, 1.0, 0.5) }.postcs.plot;
::

method:: linlin
map the receiver from an assumed linear input range to a linear output range. If the input exceeds the assumed input range, the behaviour is specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).

discussion::
code::
(0..10).collect { |num| num.linlin(0, 10, -4.3, 100) };
(0..10).linlin(0, 10, -4.3, 100); // equivalent.
::

method::linexp
map the receiver from an assumed linear input range (inMin..inMax) to an exponential output range (outMin..outMax). The output range must not include zero. If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).
discussion::
code::
(0..10).collect { |num| num.linexp(0, 10, 4.3, 100) };
(0..10).linexp(0, 10, 4.3, 100); // equivalent.
::

method::explin
map the receiver from an assumed exponential input range (inMin..inMax) to a linear output range (outMin..outMax). If the input exceeds the assumed input range. The input range must not include zero.
If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).
discussion::
code::
(1..10).collect { |num| num.explin(0.1, 10, -4.3, 100) };
(1..10).explin(0.1, 10, -4.3, 100); // equivalent.
::

method::expexp
map the receiver from an assumed exponential input range (inMin..inMax) to an exponential output range (outMin..outMax). If the input exceeds the assumed input range. Both input range and output range must not include zero.
If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).
discussion::
code::
(1..10).collect { |num| num.expexp(0.1, 10, 4.3, 100) };
(1..10).expexp(0.1, 10, 4.3, 100); // equivalent.
::

method::lincurve
map the receiver from an assumed linear input range (inMin..inMax) to an exponential curve output range (outMin..outMax). A curve is like the curve parameter in Env. Unlike with linexp, the output range may include zero.
If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::curve
0 (linear) <0 (concave, negatively curved) >0 (convex, positively curved)
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).
discussion::
code::
(0..10).collect { |num| num.lincurve(0, 10, -4.3, 100, -3) };
(0..10).lincurve(0, 10, -4.3, 100, -3); // equivalent.
::
code::
// different curves:
(-4..4).do { |val|
	(0..100).collect(_.lincurve(0, 100, 0, 1, val)).plot
}
::

method::curvelin
map the receiver from an assumed curve-exponential input range (inMin..inMax) to a linear output range (outMin..outMax). If the input exceeds the assumed input range. A curve is like the curve parameter in Env. Unlike with explin, the input range may include zero. If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outMin
output minimum
argument::outMax
output maximum
argument::curve
0 (linear) <0 (concave, negatively curved) >0 (convex, positively curved)
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).

discussion::
code::
(1..10).collect { |num| num.curvelin(0, 10, -4.3, 100, -3) };
(1..10).curvelin(0, 10, -4.3, 100, -3); // equivalent.
::
code::
// different curves:
(-4..4).do { |val|
	(0..100).collect(_.curvelin(0, 100, 0, 1, val)).plot
}
::

method::bilin
map the receiver from two assumed linear input ranges (inMin..inCenter) and (inCenter..inMax) to two linear output ranges (outMin..outCenter) and (outCenter..outMax). If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inCenter
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outCenter
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).
discussion::
code::
var center = 0.5, ctlCenter;
w = Window("bilin", Rect(100, 100, 200, 100)).front;
a = Slider(w, Rect(20, 20, 150, 20)).value_(0.5);
b = Slider(w, Rect(20, 45, 150, 20)).value_(0.5);
b.action = { center = b.value };
a.mouseDownAction = { ctlCenter = a.value };
a.action = {
	b.value = a.value.bilin(ctlCenter, 0, 1, center, 0, 1);
};
::


method::biexp
map the receiver from two assumed exponential input ranges (inMin..inCenter) and (inCenter..inMax) to two linear output ranges (outMin..outCenter) and (outCenter..outMax). The input range must not include zero. If the input exceeds the input range, the following behaviours are specified by the clip argument.
argument::inCenter
argument::inMin
assumed input minimum
argument::inMax
assumed input maximum
argument::outCenter
argument::outMin
output minimum
argument::outMax
output maximum
argument::clip
nil (don't clip)
\max (clip ceiling)
\min (clip floor)
\minmax (clip both - this is default).

discussion::
code::
// doesn't properly work yet.
(
var center = 0.5, ctlCenter;
w = Window("biexp", Rect(100, 100, 200, 100)).front;
a = Slider(w, Rect(20, 20, 150, 20)).value_(0.5);
b = Slider(w, Rect(20, 45, 150, 20)).value_(0.5);
b.action = { center = b.value };
a.mouseDownAction = { ctlCenter = a.value + 0.05 };
a.action = {
	b.value = (a.value + 0.1).biexp(ctlCenter, 0.1, 1.1, center, 0, 1);
};
)
::

method::lcurve
map the receiver onto an L-curve.

discussion::
Uses the formula
code::
a * (m * exp(x) * rTau + 1) / (n * exp(x) * rTau + 1)
::
This is used for smoothing values and limiting them to a range.
code::
(0..1000).normalize(-10, 10).collect { |num| num.lcurve }.plot;
::


method:: degrad
returns:: converts degree to radian

method:: raddeg
returns:: converts radian to degree

method:: midicps
Convert MIDI note to cycles per second
returns:: cycles per second

method:: cpsmidi
Convert cycles per second to MIDI note.
returns:: midi note


method:: midiratio
Convert an interval in semitones to a ratio.
returns:: a ratio

method:: ratiomidi
Convert a ratio to an interval in semitones.
returns:: an interval in semitones

method:: ampdb
Convert a linear amplitude to decibels.


method:: dbamp
Convert a decibels to a linear amplitude.

method:: octcps
Convert decimal octaves to cycles per second.

method:: cpsoct
Convert cycles per second to decimal octaves.


subsection:: streams

method:: storeOn
stores this on the given stream
method:: printOn
prints this on the given stream

subsection:: random

method:: coin
Answers a Boolean which is the result of a random test whose probability of success in a range from zero to one is this.

method:: rand
returns:: Random number from zero up to the receiver, exclusive.

method:: rand2
returns:: a random number from -this to +this.

method:: rrand
argument::aNumber
the upper limit
argument::adverb
returns:: a random number in the interval ]a, b[.
discussion::
If both a and b are link::Classes/Integer:: then the result will be an link::Classes/Integer::.

method:: linrand
returns:: a linearly distributed random number from zero to this.

method:: bilinrand
returns:: Bilateral linearly distributed random number from -this to +this.

method:: sum3rand
This was suggested by Larry Polansky as a poor man's gaussian.
returns:: A random number from -this to +this that is the result of summing three uniform random generators to yield a bell-like distribution.

method:: exprand
an exponentially distributed random number in the interval ]a, b[. This is always a link::Classes/Float::.
(Note that the distribution of numbers is not exactly an EMPHASIS::exponential distribution::, since that would be unbounded: we might call it a EMPHASIS::logarithmic uniform distribution::.)
argument::aNumber
the upper limit
argument::adverb

method:: gauss
a gaussian distributed random number.
argument::standardDeviation
the upper limit
discussion::
Always returns a link::Classes/Float::.
code::
(0..1000).collect { |num| gauss(0.0, num) }.plot;
::

method:: partition
randomly partition a number into parts of at least min size.
argument:: parts
number of parts
argument:: min
the minimum size

discussion::
code::
75.partition(8, 3);
75.partition(75, 1);
::


subsection:: UGen Compatibility Methods

Some methods to ease the development of generic ugen code.

method:: lag, lag2, lag3, lagud, lag2ud, lag3ud, slew, varlag

returns:: code::this::


subsection:: misc

method:: isValidUGenInput
returns:: false if receiver cannot be used in UGen.