package flare.util
{
/**
* Utility methods for mathematics not found in the Math class.
*/
public class Maths
{
private static var EPSILON:Number = 1e-30;
/**
* Constructor, throws an error if called, as this is an abstract class.
*/
public function Maths() {
throw new ArgumentError("This is an abstract class");
}
// -- Operators -------------------------------------------------------
/**
* Returns the logarithm with a given base value.
* @param x the number for which to compute the logarithm
* @param base the base of the logarithm
* @return the logarithm value
*/
public static function log(x:Number, base:Number):Number
{
return Math.log(x) / Math.log(base);
}
/**
* Rounds an input value down according to its logarithm. The method
* takes the floor of the logarithm of the value and then uses the
* resulting value as an exponent for the base value. For example:
*
* trace(Maths.logFloor(13,10)); // prints "10"
* trace(Maths.logFloor(113,10)); // prints "100"
*
* @param x the number for which to compute the logarithm floor
* @param base the base of the logarithm
* @return the rounded-by-logarithm value
*/
public static function logFloor(x:Number, base:Number):Number {
if (x > 0) {
return Math.pow(base, Math.floor(Maths.log(x, base)));
} else {
return -Math.pow(base, -Math.floor(-Maths.log(-x, base)));
}
}
/**
* Rounds an input value up according to its logarithm. The method
* takes the ceiling of the logarithm of the value and then uses the
* resulting value as an exponent for the base value. For example:
*
* trace(Maths.logCeil(13,10)); // prints "100"
* trace(Maths.logCeil(113,10)); // prints "1000"
*
* @param x the number for which to compute the logarithm ceiling
* @param base the base of the logarithm
* @return the rounded-by-logarithm value
*/
public static function logCeil(x:Number, base:Number):Number {
if (x > 0) {
return Math.pow(base, Math.ceil(Maths.log(x, base)));
} else {
return -Math.pow(base, -Math.ceil(-Maths.log(-x, base)));
}
}
/**
* Computes a zero-symmetric logarithm. Computes the logarithm of the
* absolute value of the input, and determines the sign of the output
* according to the sign of the input value.
* @param x the number for which to compute the logarithm
* @param b the base of the logarithm
* @return the symmetric log value.
*/
public static function symLog(x:Number, b:Number) : Number
{
return x == 0 ? 0 : x > 0 ? log(x, b) : -log(-x, b);
}
/**
* Computes a zero-symmetric logarithm, with adjustment to values
* between zero and the logarithm base. This adjustment introduces
* distortion for values less than the base number, but enables
* simultaneous plotting of log-transformed data involving both
* positive and negative numbers.
* @param x the number for which to compute the logarithm
* @param b the base of the logarithm
* @return the adjusted, symmetric log value.
*/
public static function adjLog(x:Number, b:Number) : Number
{
var neg:Boolean = (x < 0);
if (neg) x = -x;
if (x < b) x += (b-x)/b;
return neg ? -log(x,b) : log(x,b);
}
/**
* Computes a zero-symmetric square root. Computes the square root of
* the absolute value of the input, and determines the sign of the
* output according to the sign of the input value.
* @param x the number for which to compute the square root
* @return the symmetric square root value.
*/
public static function symSqrt(x:Number) : Number
{
return (x > 0 ? Math.sqrt(x) : -Math.sqrt(-x));
}
/**
* Computes a zero-symmetric Nth root. Computes the root of
* the absolute value of the input, and determines the sign of the
* output according to the sign of the input value.
* @param x the number for which to compute the square root
* @param p the root value (2 for square root, 3 for cubic root, etc)
* @return the symmetric Nth root value.
*/
public static function symRoot(x:Number, p:Number) : Number
{
return (x > 0 ? Math.pow(x, 1/p) : -Math.pow(-x, 1/p));
}
// -- Statistics ------------------------------------------------------
/**
* Computes the n-quantile boundaries for a set of values.
* @param n the number of quantiles
* @param values the values to break into quantiles, in an object vector
* @param sort indicates if the values object vector needs to be sorted. If
* true, the vector will be sorted prior to determining quantile
* boundaries. If false, the vector must be in ascending sort order.
* @return an n-length object vector of quantile boundaries
*/
public static function quantile(n:uint, values:Vector.