      1 // ==========================================================================
      2 // Project:   The M-Project - Mobile HTML5 Application Framework
      3 // Copyright: (c) 2010 M-Way Solutions GmbH. All rights reserved.
      4 // Creator:   Dominik
      5 // Date:      22.11.2010
      6 // License:   Dual licensed under the MIT or GPL Version 2 licenses.
      7 //            http://github.com/mwaylabs/The-M-Project/blob/master/MIT-LICENSE
      8 //            http://github.com/mwaylabs/The-M-Project/blob/master/GPL-LICENSE
      9 // ==========================================================================
     10
     11 m_require('core/foundation/object.js');
     12
     13 /**
     14  * A constant value for mathematical flooring.
     15  *
     16  * @type String
     17  */
     18 M.FLOOR = 'floor';
     19
     20 /**
     21  * A constant value for mathematical ceiling.
     22  *
     23  * @type String
     24  */
     25 M.CEIL = 'ceil';
     26
     27 /**
     28  * A constant value for mathematical rounding.
     29  *
     30  * @type String
     31  */
     32 M.ROUND = 'round';
     33
     34 /**
     35  * @class
     36  *
     37  * This prototype defines methods for simpler handling of mathematical operations.
     38  *
     39  * @extends M.Object
     40  */
     41 M.Math = M.Object.extend(
     42 /** @scope M.Math.prototype */ {
     43
     44     /**
     45      * The type of this object.
     46      *
     47      * @type String
     48      */
     49     type: 'M.Math',
     50
     51     /**
     52      * This method returns the value of the base to the power of the exponent. So e.g.
     53      * pow(2, 3) would return '2 to the power of 3' --> 8.
     54      *
     55      * @param base {Number} The base.
     56      * @param exponent {Number} The exponent.
     57      * @returns {Number} The result of the operation.
     58      */
     59     pow: function(base, exponent) {
     60         return Math.pow(base, exponent);
     61     },
     62
     63     /**
     64      * The method returns a random number within the range given by the min property
     65      * and the max property, including the min and max value.
     66      *
     67      * A test with 100.000 iterations for random(1, 3) created the following distribution:
     68      * - 1: 33.2%
     69      * - 2: 33.2%
     70      * - 3: 33.6%
     71      *
     72      * @param min {Number} The minimal value.
     73      * @param max {Number} The maximal value.
     74      * @returns {Number} The result of the operation.
     75      */
     76     random: function(min, max) {
     77         return Math.ceil(Math.random() * (max - min + 1) + min - 1);
     78     },
     79
     80     /**
     81      * The method returns rounded version of the given input number. There are three
     82      * types of rounding available:
     83      *
     84      * - M.FLOOR: Returns the next lower integer, so 2.1 and 2.9 both would return 2.
     85      * - M.CEIL: Returns the next higher integer, so 2.1 and 2.9 both would return 3.
     86      * - M.ROUND: Returns the nearest integer, so 2.1 would return 2 and 2.9 would return 3.
     87      *
     88      * With the optional third parameter 'decimals', you can specify the number of decimal digits to be
     89      * returned. For example round(1.2345, M.FLOOR, 3) would return 1.234. The default for this parameter
     90      * is 0.
     91      *
     92      * @param input {Number} The input value.
     93      * @param type {String} The type of rounding.
     94      * @param type {Number} The number of decimals (only available for M.ROUND).
     95      * @returns {Number} The result of the operation.
     96      */
     97     round: function(input, type, decimals) {
     98         if(decimals) {
     99             input = input * (Math.pow(10, decimals));
    100         }
    101         var output = 0;
    102         switch (type) {
    103             case M.FLOOR:
    104                 output = Math.floor(input);
    105                 break;
    106             case M.CEIL:
    107                 output = Math.ceil(input);
    108                 break;
    109             case M.ROUND:
    110                 default:
    111                 output = Math.round(input);
    112                 break;
    113         }
    114         if(decimals) {
    115             var outputStr = String(output / (Math.pow(10, decimals))).split('.');
    116             if(outputStr.length > 1) {
    117                 output = parseFloat(outputStr[0] + '.' + outputStr[1].substring(0, decimals));
    118             } else {
    119                 output = parseFloat(outputStr);
    120             }
    121         }
    122
    123         return output;
    124     }
    125
    126 });