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 });