zzkt/rsc3
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rsc3/doc-schelp/HelpSource/Classes/SimpleNumber.schelp

929 lines
20 KiB
Text
Raw Permalink Normal View History

docs (scm, schelp, scrbl & html)
2022-08-24 13:53:18 +00:00
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::that
the number to compare with within precision
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.
Reference in a new issue Copy permalink