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