oxjs/source/Ox/js/Math.js

'use strict';

/*@
Ox.asinh <f> Inverse hyperbolic sine
    Missing from <code>Math</code>.
    > Ox.asinh(0)
    0
@*/
Ox.asinh = function(x) {
    return Math.log(x + Math.sqrt(x * x + 1));
};

/*@
Ox.deg <f> Takes radians, returns degrees
    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 integers that
    has a sum of <code>num</code>, a length of <code>by</code>, a minimum of
    <code>Math.floor(num / by)</code> and a maximum of
    <code>Math.ceil(num / by)</code>.
    > Ox.divideInt(100, 3)
    [33, 33, 34]
    > Ox.divideInt(100, 6)
    [16, 16, 17, 17, 17, 17]
@*/
// fixme: is splitInt a better name?
Ox.divideInt = function(num, by) {
    var div = parseInt(num / by),
        mod = num % by;
    return Ox.range(by).map(function(i) {
        return div + (i > by - 1 - mod);
    });
};

/*@
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(-1, -2)
    -2
@*/
Ox.limit = function(/*num[[, min], max]*/) {
    var len = arguments.length,
        num = arguments[0],
        min = len == 3 ? arguments[1] : -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
    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) {
    return (num % by + by) % by;
};

/*@
Ox.rad <f> Takes degrees, returns radians
    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 within a given range
    () -> <n> 0 or 1
    (max) -> <n> Integer between 0 (inclusive) and max (exclusive)
    (min, max) -> <n> Integer between min (inclusive) and max (exclusive)
    > [0, 1].indexOf(Ox.random()) > -1
    true
    > [0, 1, 2].indexOf(Ox.random(3)) > -1
    true
    > Ox.random(1, 2) == 1
    true
@*/
Ox.random = function() {
    var len = arguments.length,
        min = len == 2 ? arguments[0] : 0,
        max = len ? arguments[len - 1] : 2;
    return min + Math.floor(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
    Missing from <code>Math</code>.
    > Ox.sinh(0)
    0
@*/
Ox.sinh = function(x) {
    return (Math.exp(x) - Math.exp(-x)) / 2;
};