docs/source/Number.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Number'>/**
  19 </span> * @class Number
  20  *
  21  * Creates a wrapper object to allow you to work with numerical values.
  22  *
  23  * The primary uses for the `Number` object are:
  24  *
  25  * If the argument cannot be converted into a number, it returns `NaN`.
  26  *
  27  * In a non-constructor context (i.e., without the `new` operator), `Number` can
  28  * be used to perform a type conversion.
  29  *
  30  * # Using the `Number` object to assign values to numeric variables
  31  *
  32  * The following example uses the `Number` object's properties to assign values to
  33  * several numeric variables:
  34  *
  35  *     biggestNum = Number.MAX_VALUE;
  36  *     smallestNum = Number.MIN_VALUE;
  37  *     infiniteNum = Number.POSITIVE_INFINITY;
  38  *     negInfiniteNum = Number.NEGATIVE_INFINITY;
  39  *     notANum = Number.NaN;
  40  *
  41  * # Using `Number` to convert a `Date` object
  42  *
  43  * The following example converts the `Date` object to a numerical value using
  44  * `Number` as a function:
  45  *
  46  *     var d = new Date(&quot;December 17, 1995 03:24:00&quot;);
  47  *     print(Number(d));
  48  *
  49  * This displays &quot;819199440000&quot;.
  50  *
  51  * The following example converts the Date object to a numerical value using
  52  * `Number` as a function:
  53  *
  54  * &lt;div class=&quot;notice&quot;&gt;
  55  * Documentation for this class comes from &lt;a href=&quot;https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number&quot;&gt;MDN&lt;/a&gt;
  56  * and is available under &lt;a href=&quot;http://creativecommons.org/licenses/by-sa/2.0/&quot;&gt;Creative Commons: Attribution-Sharealike license&lt;/a&gt;.
  57  * &lt;/div&gt;
  58  */
  59
  60 <span id='Number-method-constructor'>/**
  61 </span> * @method constructor
  62  * Creates new Number object.
  63  * @param value
  64  * The numeric value of the object being created.
  65  */
  66
  67 //Properties
  68
  69 <span id='Number-static-property-MAX_VALUE'>/**
  70 </span> * @property {Number} MAX_VALUE
  71  * @static
  72  * The largest positive representable number. The largest negative representable
  73  * number is `-MAX_VALUE`.
  74  *
  75  * The `MAX_VALUE` property has a value of approximately 1.79E+308. Values larger than `MAX_VALUE` are
  76  * represented as `&quot;Infinity&quot;`.
  77  *
  78  * Because `MAX_VALUE` is a static property of `Number`, you always use it as `Number.MAX_VALUE`,
  79  * rather than as a property of a `Number` object you created.
  80  *
  81  * The following code multiplies two numeric values. If the result is less than or equal to
  82  * `MAX_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.
  83  *
  84  *     if (num1 * num2 &lt;= Number.MAX_VALUE)
  85  *         func1();
  86  *     else
  87  *         func2();
  88  */
  89
  90 <span id='Number-static-property-MIN_VALUE'>/**
  91 </span> * @property {Number} MIN_VALUE
  92  * @static
  93  * The smallest positive representable number -- that is, the positive number
  94  * closest to zero (without actually being zero). The smallest negative
  95  * representable number is `-MIN_VALUE`.
  96  *
  97  * The `MIN_VALUE` property is the number closest to 0, not the most negative number, that JavaScript
  98  * can represent.
  99  *
 100  * `MIN_VALUE` has a value of approximately 5e-324. Values smaller than `MIN_VALUE` (&quot;underflow
 101  * values&quot;) are converted to 0.
 102  *
 103  * Because `MIN_VALUE` is a static property of `Number`, you always use it as `Number.MIN_VALUE`,
 104  * rather than as a property of a `Number` object you created.
 105  *
 106  * The following code divides two numeric values. If the result is greater than or equal to
 107  * `MIN_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.
 108  *
 109  *     if (num1 / num2 &gt;= Number.MIN_VALUE)
 110  *         func1()
 111  *     else
 112  *         func2()
 113  */
 114
 115 <span id='Number-static-property-NaN'>/**
 116 </span> * @property {Number} NaN
 117  * @static
 118  * Special &quot;not a number&quot; value.
 119  */
 120
 121 <span id='Number-property-NEGATIVE_INFINITY'>/**
 122 </span> * @property {Number} NEGATIVE_INFINITY
 123  * Special value representing negative infinity; returned on overflow.
 124  *
 125  * The value of `Number.NEGATIVE_INFINITY` is the same as the negative value of the global object's
 126  * Infinity property.
 127  *
 128  * This value behaves slightly differently than mathematical infinity:
 129  *
 130  * *   Any positive value, including POSITIVE_INFINITY, multiplied by NEGATIVE_INFINITY is NEGATIVE_INFINITY.
 131  * *   Any negative value, including NEGATIVE_INFINITY, multiplied by NEGATIVE_INFINITY is
 132  * POSITIVE_INFINITY.
 133  * *   Zero multiplied by NEGATIVE_INFINITY is NaN.
 134  * *   NaN multiplied by NEGATIVE_INFINITY is NaN.
 135  * *   NEGATIVE_INFINITY, divided by any negative value except NEGATIVE_INFINITY, is
 136  * POSITIVE_INFINITY.
 137  * *   NEGATIVE_INFINITY, divided by any positive value except POSITIVE_INFINITY, is
 138  * NEGATIVE_INFINITY.
 139  * *   NEGATIVE_INFINITY, divided by either NEGATIVE_INFINITY or POSITIVE_INFINITY, is NaN.
 140  * *   Any number divided by NEGATIVE_INFINITY is Zero.
 141  *
 142  * Several JavaScript methods (such as the `Number` constructor, `parseFloat`, and `parseInt`) return
 143  * `NaN` if the value specified in the parameter is significantly lower than `Number.MIN_VALUE`.
 144  *
 145  * You might use the `Number.NEGATIVE_INFINITY` property to indicate an error condition that returns a
 146  * finite number in case of success. Note, however, that `isFinite` would be more appropriate in such
 147  * a case.
 148  *
 149  * In the following example, the variable smallNumber is assigned a value that is smaller than the
 150  * minimum value. When the `if` statement executes, `smallNumber` has the value `&quot;-Infinity&quot;`, so
 151  * `smallNumber` is set to a more manageable value before continuing.
 152  *
 153  *     var smallNumber = (-Number.MAX_VALUE) * 2
 154  *     if (smallNumber == Number.NEGATIVE_INFINITY) {
 155  *         smallNumber = returnFinite();
 156  *     }
 157  */
 158
 159 <span id='Number-property-POSITIVE_INFINITY'>/**
 160 </span> * @property {Number} POSITIVE_INFINITY
 161  * Special value representing infinity; returned on overflow.
 162  *
 163  * The value of `Number.POSITIVE_INFINITY` is the same as the value of the global object's Infinity
 164  * property.
 165  *
 166  * This value behaves slightly differently than mathematical infinity:
 167  *
 168  * *   Any positive value, including POSITIVE_INFINITY, multiplied by POSITIVE_INFINITY is
 169  * POSITIVE_INFINITY.
 170  * *   Any negative value, including NEGATIVE_INFINITY, multiplied by POSITIVE_INFINITY is
 171  * NEGATIVE_INFINITY.
 172  * *   Zero multiplied by POSITIVE_INFINITY is NaN.
 173  * *   NaN multiplied by POSITIVE_INFINITY is NaN.
 174  * *   POSITIVE_INFINITY, divided by any negative value except NEGATIVE_INFINITY, is
 175  * NEGATIVE_INFINITY.
 176  * *   POSITIVE_INFINITY, divided by any positive value except POSITIVE_INFINITY, is
 177  * POSITIVE_INFINITY.
 178  * *   POSITIVE_INFINITY, divided by either NEGATIVE_INFINITY or POSITIVE_INFINITY, is NaN.
 179  * *   Any number divided by POSITIVE_INFINITY is Zero.
 180  *
 181  * Several JavaScript methods (such as the `Number` constructor, `parseFloat`, and `parseInt`) return
 182  * `NaN` if the value specified in the parameter is significantly higher than `Number.MAX_VALUE`.
 183  *
 184  * You might use the `Number.POSITIVE_INFINITY` property to indicate an error condition that returns a
 185  * finite number in case of success. Note, however, that `isFinite` would be more appropriate in such
 186  * a case.
 187  *
 188  * In the following example, the variable `bigNumber` is assigned a value that is larger than the
 189  * maximum value. When the if statement executes, `bigNumber` has the value &quot;Infinity&quot;, so `bigNumber`
 190  * is set to a more manageable value before continuing.
 191  *
 192  *     var bigNumber = Number.MAX_VALUE * 2
 193  *     if (bigNumber == Number.POSITIVE_INFINITY) {
 194  *         bigNumber = returnFinite();
 195  *     }
 196  */
 197
 198 //Methods
 199
 200 <span id='Number-method-toExponential'>/**
 201 </span> * @method toExponential
 202  * Returns a string representing the number in exponential notation.
 203  *
 204  * A string representing a `Number` object in exponential notation with one digit before the decimal
 205  * point, rounded to `fractionDigits` digits after the decimal point. If the `fractionDigits` argument
 206  * is omitted, the number of digits after the decimal point defaults to the number of digits necessary
 207  * to represent the value uniquely.
 208  *
 209  * If you use the `toExponential` method for a numeric literal and the numeric literal has no exponent
 210  * and no decimal point, leave a space before the dot that precedes the method call to prevent the dot
 211  * from being interpreted as a decimal point.
 212  *
 213  * If a number has more digits that requested by the `fractionDigits` parameter, the number is rounded
 214  * to the nearest number represented by `fractionDigits` digits. See the discussion of rounding in the
 215  * description of the `toFixed` method, which also applies to `toExponential`.
 216  *
 217  *     var num=77.1234;
 218  *
 219  *     alert(&quot;num.toExponential() is &quot; + num.toExponential()); //displays 7.71234e+1
 220  *
 221  *     alert(&quot;num.toExponential(4) is &quot; + num.toExponential(4)); //displays 7.7123e+1
 222  *
 223  *     alert(&quot;num.toExponential(2) is &quot; + num.toExponential(2)); //displays 7.71e+1
 224  *
 225  *     alert(&quot;77.1234.toExponential() is &quot; + 77.1234.toExponential()); //displays 7.71234e+1
 226  *
 227  *     alert(&quot;77 .toExponential() is &quot; + 77 .toExponential()); //displays 7.7e+1
 228  *
 229  * @param {Number} fractionDigits An integer specifying the number of digits after the decimal
 230  * point. Defaults to as many digits as necessary to specify the number.
 231  * @return {String} Exponential notation of number.
 232  */
 233
 234 <span id='Number-method-toFixed'>/**
 235 </span> * @method toFixed
 236  * Returns a string representing the number in fixed-point notation.
 237  *
 238  * @return {String} A string representation of `number` that does not use
 239  * exponential notation and has exactly `digits` digits after the decimal place.
 240  * The number is rounded if necessary, and the fractional part is padded with
 241  * zeros if necessary so that it has the specified length. If `number` is greater
 242  * than 1e+21, this method simply calls `Number.toString()` and returns a string
 243  * in exponential notation.
 244  *
 245  * @param {Number} digits The number of digits to appear after the decimal point; this may be a
 246  * value between 0 and 20, inclusive, and implementations may optionally support a larger range of
 247  * values. If this argument is omitted, it is treated as 0.
 248  */
 249
 250 <span id='Number-method-toLocaleString'>/**
 251 </span> * @method toLocaleString
 252  * Returns a human readable string representing the number using the locale of the
 253  * environment. Overrides the `Object.prototype.toLocaleString` method.
 254  *
 255  * This method available to numbers will convert the number into a string which is suitable for
 256  * presentation in the given locale.
 257  *
 258  *     var number = 3500
 259  *     console.log(number.toLocaleString()); // Displays &quot;3,500&quot; in English locale
 260  *
 261  * @return {String} String representing the number.
 262  */
 263
 264 <span id='Number-method-toPrecision'>/**
 265 </span> * @method toPrecision
 266  * Returns a string representing the number to a specified precision in fixed-
 267  * point or exponential notation.
 268  *
 269  * A string representing a `Number` object in fixed-point or
 270  * exponential notation rounded to precision significant digits. See the
 271  * discussion of rounding in the description of the `toFixed` method, which also
 272  * applies to `toPrecision`.
 273  *
 274  * If the precision argument is omitted, behaves as Number.toString. If it is a
 275  * non-integer value, it is rounded to the nearest integer. After rounding, if
 276  * that value is not between 1 and 100 (inclusive), a RangeError is thrown.
 277  *
 278  * @param {Number} precision An integer specifying the number of significant digits.
 279  * @return {String} String that represents `Number` object.
 280  */
 281
 282 <span id='Number-method-toString'>/**
 283 </span> * @method toString
 284  * Returns a string representing the specified object. Overrides the
 285  * `Object.prototype.toString` method.
 286  *
 287  * The `Number` object overrides the `toString` method of the `Object` object; it does not inherit
 288  * `Object.toString`. For `Number` objects, the toString method returns a string representation of the
 289  * object in the specified radix.
 290  *
 291  * The `toString` method parses its first argument, and attempts to return a string representation in
 292  * the specified radix (base). For radixes above 10, the letters of the alphabet indicate numerals
 293  * greater than 9. For example, for hexadecimal numbers (base 16), A through F are used.
 294  *
 295  * If `toString` is given a radix not between 2 and 36, an exception is thrown.
 296  *
 297  * If the radix is not specified, JavaScript assumes the preferred radix is 10.
 298  *
 299  *     var count = 10;
 300  *     print(count.toString());   // displays &quot;10&quot;
 301  *     print((17).toString());    // displays &quot;17&quot;
 302  *
 303  *     var x = 7;
 304  *     print(x.toString(2));      // displays &quot;111&quot;
 305  *
 306  * @param {Number} radix An integer between 2 and 36 specifying the base to use for representing
 307  * numeric values.
 308  * @return {String} The number represented as a string.
 309  */
 310
 311 <span id='Number-method-valueOf'>/**
 312 </span> * @method valueOf
 313  * Returns the primitive value of the specified object. Overrides the
 314  * `Object.prototype.valueOf` method.
 315  *
 316  * The `valueOf` method of `Number` returns the primitive value of a `Number` object as a number data
 317  * type.
 318  *
 319  * This method is usually called internally by JavaScript and not explicitly in code.
 320  *
 321  *     var x = new Number();
 322  *     print(x.valueOf());     // prints &quot;0&quot;
 323  *
 324  * @return {Number} The primitive value of the number.
 325  */</pre>
 326 </body>
 327 </html>