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