oxjs/source/Ox/js/Math.js

/*@
Ox.asinh <f> Inverse hyperbolic sine
    Strangely missing from <code>Math</code>.
@*/
Ox.asinh = function(x) {
    // fixme: no test
    return Math.log(x + Math.sqrt(x * x + 1));
};

/*@
Ox.deg <f> Takes radians, returns degrees
    Strangely missing from <code>Math</code>.
    > Ox.deg(2 * Math.PI)
    360
@*/
Ox.deg = function(rad) {
    return rad * 180 / Math.PI;
};

/*@
Ox.divideInt <f> Divides a number by another and returns an array of integers
    <code>Ox.divideInt(num, by)</code> returns a sorted array of "as equal as
    possible" integers that has a sum of <code>num</code> and a length of
    <code>by</code>.
    > Ox.divideInt(100, 3)
    [33, 33, 34]
    > Ox.divideInt(100, 6)
    [16, 16, 17, 17, 17, 17]
@*/
Ox.divideInt = function(num, by) {
    var arr = [],
        div = parseInt(num / by),
        mod = num % by;
    Ox.loop(by, function(i) {
        arr[i] = div + (i > by - 1 - mod);
    });
    return arr;
}

/*@
Ox.limit <f> Limits a number by a given mininum and maximum
    <code>Ox.limit(num, min, max)</code> is a shorthand for
    <code>Math.min(Math.max(num, min), max)</code>
    (num) -> <n> <code>num</code>
    (num, max) -> <n> <code>Math.max(num, max)</code>
    (num, min, max) -> <n> <code>Math.min(Math.max(num, min), max)</code>
    num <n> number
    min <n> minimum
    max <n> maximum
    > Ox.limit(1, 2, 3)
    2
    > Ox.limit(4, 2, 3)
    3
    > Ox.limit(2, 1)
    1
@*/
Ox.limit = function(/*num[[, min], max]*/) {
    var len = arguments.length,
        num = arguments[0],
        min = len == 3 ? arguments[1] : 0, // fixme: should be -Infinity
        max = arguments[len - 1];
    return Math.min(Math.max(num, min), max);
};

/*@
Ox.log <f> Returns the logarithm of a given number to a given base
    Strangely missing from <code>Math</code>.
    > Ox.log(100, 10)
    2
    > Ox.log(Math.E)
    1
@*/
Ox.log = function(num, base) {
    return Math.log(num) / Math.log(base || Math.E);
};

/*@
Ox.mod <f> Modulo function
    Unlike <code>-1 % 10</code>, which returns <code>-1</code>,
    <code>Ox.mod(-1, 10)</code> returns <code>9</code>.
    > Ox.mod(11, 10)
    1
    > Ox.mod(-11, 10)
    9
@*/
Ox.mod = function(num, by) {
    var mod = num % by;
    return mod >= 0 ? mod : mod + by;
};

/*@
Ox.rad <f> Takes degrees, returns radians
    Strangely missing from <code>Math</code>.
    > Ox.rad(360)
    2 * Math.PI
@*/
Ox.rad = function(deg) {
    return deg * Math.PI / 180;
};

/*@
Ox.random <f> Returns a random integer
    > [0, 1, 2].indexOf(Ox.random(3)) > -1
    true
    > Ox.random(1, 2) == 1
    true
@*/
Ox.random = function() {
    var len = arguments.length,
        min = len == 1 ? 0 : arguments[0],
        max = arguments[len - 1];
    return min + parseInt(Math.random() * (max - min));
};

/*@
Ox.round <f> Rounds a number with a given number of decimals
    > Ox.round(2 / 3, 6)
    0.666667
    > Ox.round(1 / 2, 3)
    0.5
    > Ox.round(1 / 2)
    1
@*/
Ox.round = function(num, dec) {
    var pow = Math.pow(10, dec || 0);
    return Math.round(num * pow) / pow;
};

/*@
Ox.sinh <f> Hyperbolic sine
    Strangely missing from <code>Math</code>.
@*/
Ox.sinh = function(x) {
    // fixme: no test
    return (Math.exp(x) - Math.exp(-x)) / 2;
};