1<!DOCTYPE HTML> 2<html> 3<head> 4 <meta charset="utf-8"> 5 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 6 <meta name="Author" content="MMclaughlin"> 7 <title>decimal.js API</title> 8 <style> 9html{font-size:100%} 10body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px; 11 line-height:1.65em;min-height:100%;margin:0} 12body,i{color:#000} 13.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:210px;overflow-y:auto; 14 padding:15px 0 30px 15px} 15div.container{width:600px;margin:50px 0 50px 240px} 16p{margin:0 0 1em;width:600px} 17pre,ul{margin:1em 0} 18h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0} 19h1,h2{padding:.75em 0} 20h1{font:400 3em Consolas, monaco, monospace;color:#000;margin-bottom:1em} 21h2{font-size:2.25em;color:#f00} 22h3{font-size:1.75em;color:#69d2e7} 23h4{font-size:1.75em;color:#f00;padding-bottom:.75em} 24h5{font-size:1.2em;margin-bottom:.4em} 25h6{font-size:1.1em;margin-bottom:0.8em;padding:0.5em 0} 26dd dt{font-size:1.2em} 27dt{padding-top:.5em} 28dd{padding-top:.35em} 29b{font-weight:700} 30a,a:visited{color:#f00;text-decoration:none} 31a:active,a:hover{outline:0;text-decoration:underline} 32.nav a,.nav b,.nav a:visited{display:block;color:#f00;font-weight:700;margin-top:15px} 33.nav b{color:#69d2e7;margin-top:20px;cursor:default;width:auto} 34ul{list-style-type:none;padding:0 0 0 20px} 35.nav ul{line-height:14px;padding-left:0;margin:5px 0 0} 36.nav ul a,.nav ul a:visited,span{display:inline;color:#000;font-family:Verdana,Geneva,sans-serif; 37 font-size:11px;font-weight:400;margin:0} 38.inset{margin-left:20px;font-size:.9em} 39.nav li{width:auto;margin:0 0 3px} 40.alias{font-style:italic;margin-left:20px} 41table{border-collapse:collapse;border-spacing:0;border:2px solid #a7dbd8;margin:1.75em 0;padding:0} 42td,th{text-align:left;margin:0;padding:2px 5px;border:1px dotted #a7dbd8} 43th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#f00} 44code,pre{font-family:Consolas, monaco, monospace;font-weight:400} 45pre{background:#f5f5f5;white-space:pre-wrap;word-wrap:break-word;border-left:5px solid #a7dbd8; 46 padding:1px 0 1px 15px;margin:1.2em 0} 47code,.nav-title{color:#f00} 48.end{margin-bottom:25px} 49.centre{text-align:center} 50#modes,#configProps{color:#f00} 51.spacer{line-height:0px} 52#faq{margin:3em 0 0} 53li span{float:right;margin-right:10px;color:#c0c0c0} 54#js{font:inherit;color:#f00} 55 </style> 56</head> 57<body> 58 59 <div class="nav"> 60 61 <a class='nav-title' href="#">API</a> 62 63 <b>CONSTRUCTOR</b> 64 <ul><li><a href="#decimal"><strong>Decimal</strong></a></li></ul> 65 66 <a href="#methods">Methods</a> 67 <ul> 68 <li><a href="#Dabs" >abs</a></li> 69 <li><a href="#Dacos" >acos</a></li> 70 <li><a href="#Dacosh" >acosh</a></li> 71 <li><a href="#Dadd" >add</a></li> 72 <li><a href="#Dasin" >asin</a></li> 73 <li><a href="#Dasinh" >asinh</a></li> 74 <li><a href="#Datan" >atan</a></li> 75 <li><a href="#Datanh" >atanh</a></li> 76 <li><a href="#Datan2" >atan2</a></li> 77 <li><a href="#Dcbrt" >cbrt</a></li> 78 <li><a href="#Dceil" >ceil</a></li> 79 <li><a href="#Dclamp" >clamp</a></li> 80 <li><a href="#Dclone" >clone</a></li> 81 <li><a href="#Dcos" >cos</a></li> 82 <li><a href="#Dcosh" >cosh</a></li> 83 <li><a href="#Ddiv" >div</a></li> 84 <li><a href="#Dexp" >exp</a></li> 85 <li><a href="#Dfloor" >floor</a></li> 86 <li><a href="#Dhypot" >hypot</a></li> 87 <li><a href="#DisDecimal" >isDecimal</a></li> 88 <li><a href="#Dln" >ln</a></li> 89 <li><a href="#Dlog" >log</a></li> 90 <li><a href="#Dlog2" >log2</a></li> 91 <li><a href="#Dlog10" >log10</a></li> 92 <li><a href="#Dmax" >max</a></li> 93 <li><a href="#Dmin" >min</a></li> 94 <li><a href="#Dmod" >mod</a></li> 95 <li><a href="#Dmul" >mul</a></li> 96 <li><a href="#DnoConflict">noConflict</a></li> 97 <li><a href="#Dpow" >pow</a></li> 98 <li><a href="#Drandom" >random</a></li> 99 <li><a href="#Dround" >round</a></li> 100 <li><a href="#Dset" >set</a></li> 101 <li><a href="#Dsign" >sign</a></li> 102 <li><a href="#Dsin" >sin</a></li> 103 <li><a href="#Dsinh" >sinh</a></li> 104 <li><a href="#Dsqrt" >sqrt</a></li> 105 <li><a href="#Dsub" >sub</a></li> 106 <li><a href="#Dsum" >sum</a></li> 107 <li><a href="#Dtan" >tan</a></li> 108 <li><a href="#Dtanh" >tanh</a></li> 109 <li><a href="#Dtrunc" >trunc</a></li> 110 </ul> 111 112 <a href="#constructor-properties">Properties</a> 113 <ul> 114 <li><a href="#precision">precision</a></li> 115 <li><a href="#rounding" >rounding</a></li> 116 <li><a href="#minE" >minE</a></li> 117 <li><a href="#maxE" >maxE</a></li> 118 <li><a href="#toExpNeg" >toExpNeg</a></li> 119 <li><a href="#toExpPos" >toExpPos</a></li> 120 <li><a href="#modulo" >modulo</a></li> 121 <li><a href="#crypto" >crypto</a></li> 122 <li class='spacer'> </li> 123 <li><a href="#modes">ROUND_UP</a></li> 124 <li><a href="#modes">ROUND_DOWN</a></li> 125 <li><a href="#modes">ROUND_CEIL</a></li> 126 <li><a href="#modes">ROUND_FLOOR</a></li> 127 <li><a href="#modes">ROUND_HALF_UP</a></li> 128 <li><a href="#modes">ROUND_HALF_DOWN</a></li> 129 <li><a href="#modes">ROUND_HALF_EVEN</a></li> 130 <li><a href="#modes">ROUND_HALF_CEIL</a></li> 131 <li><a href="#modes">ROUND_HALF_FLOOR</a></li> 132 <li><a href="#modes">EUCLID</a></li> 133 </ul> 134 135 <b> INSTANCE </b> 136 137 <a href="#prototype-methods">Methods</a> 138 <ul> 139 <li><a href="#abs" >absoluteValue </a><span>abs</span> </li> 140 <li><a href="#ceil" >ceil </a> </li> 141 <li><a href="#cmp" >comparedTo </a><span>cmp</span> </li> 142 <li><a href="#clamp" >clampedTo </a><span>clamp</span> </li> 143 <li><a href="#cos" >cosine </a><span>cos</span> </li> 144 <li><a href="#cbrt" >cubeRoot </a><span>cbrt</span> </li> 145 <li><a href="#dp" >decimalPlaces </a><span>dp</span> </li> 146 <li><a href="#div" >dividedBy </a><span>div</span> </li> 147 <li><a href="#divToInt" >dividedToIntegerBy </a><span>divToInt</span></li> 148 <li><a href="#eq" >equals </a><span>eq</span> </li> 149 <li><a href="#floor" >floor </a> </li> 150 <li><a href="#gt" >greaterThan </a><span>gt</span> </li> 151 <li><a href="#gte" >greaterThanOrEqualTo </a><span>gte</span> </li> 152 <li><a href="#cosh" >hyperbolicCosine </a><span>cosh</span> </li> 153 <li><a href="#sinh" >hyperbolicSine </a><span>sinh</span> </li> 154 <li><a href="#tanh" >hyperbolicTangent </a><span>tanh</span> </li> 155 <li><a href="#acos" >inverseCosine </a><span>acos</span> </li> 156 <li><a href="#acosh" >inverseHyperbolicCosine </a><span>acosh</span> </li> 157 <li><a href="#asinh" >inverseHyperbolicSine </a><span>asinh</span> </li> 158 <li><a href="#atanh" >inverseHyperbolicTangent</a><span>atanh</span> </li> 159 <li><a href="#asin" >inverseSine </a><span>asin</span> </li> 160 <li><a href="#atan" >inverseTangent </a><span>atan</span> </li> 161 <li><a href="#isFinite" >isFinite </a> </li> 162 <li><a href="#isInt" >isInteger </a><span>isInt</span> </li> 163 <li><a href="#isNaN" >isNaN </a> </li> 164 <li><a href="#isNeg" >isNegative </a><span>isNeg</span> </li> 165 <li><a href="#isPos" >isPositive </a><span>isPos</span> </li> 166 <li><a href="#isZero" >isZero </a> </li> 167 <li><a href="#lt" >lessThan </a><span>lt</span> </li> 168 <li><a href="#lte" >lessThanOrEqualTo </a><span>lte</span> </li> 169 <li><a href="#log" >logarithm </a><span>log</span> </li> 170 <li><a href="#sub" >minus </a><span>sub</span> </li> 171 <li><a href="#mod" >modulo </a><span>mod</span> </li> 172 <li><a href="#exp" >naturalExponential </a><span>exp</span> </li> 173 <li><a href="#ln" >naturalLogarithm </a><span>ln</span> </li> 174 <li><a href="#neg" >negated </a><span>neg</span> </li> 175 <li><a href="#add" >plus </a><span>add</span> </li> 176 <li><a href="#sd" >precision </a><span>sd</span> </li> 177 <li><a href="#round" >round </a> </li> 178 <li><a href="#sin" >sine </a><span>sin</span> </li> 179 <li><a href="#sqrt" >squareRoot </a><span>sqrt</span> </li> 180 <li><a href="#tan" >tangent </a><span>tan</span> </li> 181 <li><a href="#mul" >times </a><span>mul</span> </li> 182 <li><a href="#toBinary" >toBinary </a> </li> 183 <li><a href="#toDP" >toDecimalPlaces </a><span>toDP</span> </li> 184 <li><a href="#toExponential">toExponential </a> </li> 185 <li><a href="#toFixed" >toFixed </a> </li> 186 <li><a href="#toFraction" >toFraction </a> </li> 187 <li><a href="#toHex" >toHexadecimal </a><span>toHex</span> </li> 188 <li><a href="#toJSON" >toJSON </a> </li> 189 <li><a href="#toNearest" >toNearest </a> </li> 190 <li><a href="#toNumber" >toNumber </a> </li> 191 <li><a href="#toOctal" >toOctal </a> </li> 192 <li><a href="#pow" >toPower </a><span>pow</span> </li> 193 <li><a href="#toPrecision" >toPrecision </a> </li> 194 <li><a href="#toSD" >toSignificantDigits </a><span>toSD</span> </li> 195 <li><a href="#toString" >toString </a> </li> 196 <li><a href="#trunc" >truncated </a><span>trunc</span> </li> 197 <li><a href="#valueOf" >valueOf </a> </li> 198 </ul> 199 200 <a href="#instance-properties">Properties</a> 201 <ul> 202 <li><a href="#digits" >d</a><span>digits</span></li> 203 <li><a href="#exponent" >e</a><span>exponent</span></li> 204 <li><a href="#sign" >s</a><span>sign</span></li> 205 </ul> 206 207 <a href="#zero-nan-infinity">Zero, NaN & Infinity</a> 208 <a href="#Errors">Errors</a> 209 <a href="#Pi">Pi</a> 210 <a class='end' href="#faq">FAQ</a> 211 212 </div> 213 214 <div class="container"> 215 216 <h1>decimal<span id='js'>.js</span></h1> 217 218 <p>An arbitrary-precision Decimal type for JavaScript.</p> 219 <p><a href='https://github.com/MikeMcl/decimal.js'>Hosted on GitHub</a>.</p> 220 221 <h2>API</h2> 222 223 <p> 224 See the <a href='https://github.com/MikeMcl/decimal.js'>README</a> on GitHub for a quick-start 225 introduction. 226 </p> 227 <p> 228 In all examples below, <code>var</code> and semicolons are not shown, and if a commented-out 229 value is in quotes it means <code>toString</code> has been called on the preceding expression. 230 </p><br /> 231 <p> 232 When the library is loaded, it defines a single function object, 233 <a href='#decimal'><code>Decimal</code></a>, the constructor of Decimal instances. 234 </p> 235 <p> 236 <i> 237 If necessary, multiple Decimal constructors can be created, each with their own independent 238 configuration, e.g. precision and range, which applies to all Decimal instances created from 239 it. 240 </i> 241 </p> 242 <p> 243 <i> 244 A new Decimal constructor is created by calling the <code><a href='#Dclone'>clone</a></code> 245 method of an already existing Decimal constructor. 246 </i> 247 </p> 248 249 250 251 <h3 class='end'>CONSTRUCTOR</h3> 252 253 <h5 id="decimal"> 254 Decimal<code class='inset'>Decimal(value) <i>⇒ Decimal</i></code> 255 </h5> 256 <dl> 257 <dt><code>value</code>: <i>number|string|Decimal</i></dt> 258 <dd> 259 A legitimate <code>value</code> is an integer or float, including <code>±0</code>, or 260 is <code>±Infinity</code>, or <code>NaN</code>. 261 </dd> 262 <dd> 263 The number of digits of <code>value</code> is not limited, except by JavaScript's maximum 264 array size and, in practice, the processing time required. 265 </dd> 266 <dd> 267 The allowable range of <code>value</code> is defined in terms of a maximum exponent, see 268 <a href='#maxE'>maxE</a>, and a minimum exponent, see <a href='#minE'>minE</a>. 269 </dd> 270 <dd> 271 As well as in decimal, a string <code>value</code> may be expressed in binary, hexadecimal 272 or octal, if the appropriate prefix is included: <code>0x</code> or <code>0X</code> for 273 hexadecimal, <code>0b</code> or <code>0B</code> for binary, and <code>0o</code> or 274 <code>0O</code> for octal. 275 </dd> 276 <dd> 277 Both decimal and non-decimal string values may use exponential (floating-point), as well as 278 normal (fixed-point) notation. 279 </dd> 280 <dd> 281 In exponential notation, <code>e</code> or <code>E</code> defines a power-of-ten exponent 282 for decimal values, and <code>p</code> or <code>P</code> defines a power-of-two exponent for 283 non-decimal values, i.e. binary, hexadecimal or octal. 284 </dd> 285 </dl> 286 <p>Returns a new Decimal object instance.</p> 287 <p>Throws on an invalid <code>value</code>.</p> 288 <pre> 289x = new Decimal(9) // '9' 290y = new Decimal(x) // '9' 291 292new Decimal('5032485723458348569331745.33434346346912144534543') 293new Decimal('4.321e+4') // '43210' 294new Decimal('-735.0918e-430') // '-7.350918e-428' 295new Decimal('5.6700000') // '5.67' 296new Decimal(Infinity) // 'Infinity' 297new Decimal(NaN) // 'NaN' 298new Decimal('.5') // '0.5' 299new Decimal('-0b10110100.1') // '-180.5' 300new Decimal('0xff.8') // '255.5' 301 302new Decimal(0.046875) // '0.046875' 303new Decimal('0.046875000000') // '0.046875' 304new Decimal('0.046_875_000_000') // '0.046875' 305 306new Decimal(4.6875e-2) // '0.046875' 307new Decimal('468.75e-4') // '0.046875' 308 309new Decimal('0b0.000011') // '0.046875' 310new Decimal('0o0.03') // '0.046875' 311new Decimal('0x0.0c') // '0.046875' 312 313new Decimal('0b1.1p-5') // '0.046875' 314new Decimal('0o1.4p-5') // '0.046875' 315new Decimal('0x1.8p-5') // '0.046875'</pre> 316 317 318 319 <h4 id="methods">Methods</h4> 320 <p>The methods of a Decimal constructor.</p> 321 322 323 324 <h5 id="Dabs">abs<code class='inset'>.abs(x) <i>⇒ Decimal</i></code></h5> 325 <p><code>x</code>: <i>number|string|Decimal</i></p> 326 <p>See <code><a href='#abs'>absoluteValue</a></code>.</p> 327 <pre>a = Decimal.abs(x) 328b = new Decimal(x).abs() 329a.equals(b) // true</pre> 330 331 332 333 <h5 id="Dacos">acos<code class='inset'>.acos(x) <i>⇒ Decimal</i></code></h5> 334 <p><code>x</code>: <i>number|string|Decimal</i></p> 335 <p>See <code><a href='#acos'>inverseCosine</a></code>.</p> 336 <pre>a = Decimal.acos(x) 337b = new Decimal(x).acos() 338a.equals(b) // true</pre> 339 340 341 342 <h5 id="Dacosh">acosh<code class='inset'>.acosh(x) <i>⇒ Decimal</i></code></h5> 343 <p><code>x</code>: <i>number|string|Decimal</i></p> 344 <p>See <code><a href='#acos'>inverseHyperbolicCosine</a></code>.</p> 345 <pre>a = Decimal.acosh(x) 346b = new Decimal(x).acosh() 347a.equals(b) // true</pre> 348 349 350 351 <h5 id="Dadd">add<code class='inset'>.add(x, y) <i>⇒ Decimal</i></code></h5> 352 <p> 353 <code>x</code>: <i>number|string|Decimal</i><br /> 354 <code>y</code>: <i>number|string|Decimal</i> 355 </p> 356 <p>See <code><a href='#add'>plus</a></code>.</p> 357 <pre>a = Decimal.add(x, y) 358b = new Decimal(x).plus(y) 359a.equals(b) // true</pre> 360 361 362 363 <h5 id="Dasin">asin<code class='inset'>.asin(x) <i>⇒ Decimal</i></code></h5> 364 <p><code>x</code>: <i>number|string|Decimal</i></p> 365 <p>See <code><a href='#asin'>inverseSine</a></code>.</p> 366 <pre>a = Decimal.asin(x) 367b = new Decimal(x).asin() 368a.equals(b) // true</pre> 369 370 371 372 <h5 id="Dasinh">asinh<code class='inset'>.asinh(x) <i>⇒ Decimal</i></code></h5> 373 <p><code>x</code>: <i>number|string|Decimal</i></p> 374 <p>See <code><a href='#asin'>inverseHyperbolicSine</a></code>.</p> 375 <pre>a = Decimal.asinh(x) 376b = new Decimal(x).asinh() 377a.equals(b) // true</pre> 378 379 380 381 <h5 id="Datan">atan<code class='inset'>.atan(x) <i>⇒ Decimal</i></code></h5> 382 <p><code>x</code>: <i>number|string|Decimal</i></p> 383 <p>See <code><a href='#atan'>inverseTangent</a></code>.</p> 384 <pre>a = Decimal.atan(x) 385b = new Decimal(x).atan() 386a.equals(b) // true</pre> 387 388 389 390 <h5 id="Datanh">atanh<code class='inset'>.atanh(x) <i>⇒ Decimal</i></code></h5> 391 <p><code>x</code>: <i>number|string|Decimal</i></p> 392 <p>See <code><a href='#atan'>inverseHyperbolicTangent</a></code>.</p> 393 <pre>a = Decimal.atanh(x) 394b = new Decimal(x).atanh() 395a.equals(b) // true</pre> 396 397 398 399 <h5 id="Datan2">atan2<code class='inset'>.atan2(y, x) <i>⇒ Decimal</i></code></h5> 400 <p> 401 <code>y</code>: <i>number|string|Decimal</i><br /> 402 <code>x</code>: <i>number|string|Decimal</i> 403 </p> 404 <p> 405 Returns a new Decimal whose value is the inverse tangent in radians of the quotient of 406 <code>y</code> and <code>x</code>, rounded to <a href='#precision'><code>precision</code></a> 407 significant digits using rounding mode <a href='#rounding'><code>rounding</code></a>. 408 </p> 409 <p> 410 The signs of <code>y</code> and <code>x</code> are used to determine the quadrant of the 411 result. 412 </p> 413 <p> 414 Domain: [<code>-Infinity, Infinity</code>]<br /> 415 Range: [<code>-pi, pi</code>] 416 </p> 417 <p> 418 See <a href='#Pi'><code>Pi</code></a> and 419 <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2'><code>Math.atan2()</code>.</a> 420 </p> 421 <pre>r = Decimal.atan2(y, x)</pre> 422 423 424 425 <h5 id="Dcbrt">cbrt<code class='inset'>.cbrt(x) <i>⇒ Decimal</i></code></h5> 426 <p><code>x</code>: <i>number|string|Decimal</i></p> 427 <p>See <code><a href='#cbrt'>cubeRoot</a></code>.</p> 428 <pre>a = Decimal.cbrt(x) 429b = new Decimal(x).cbrt() 430a.equals(b) // true</pre> 431 432 433 434 <h5 id="Dceil">ceil<code class='inset'>.ceil(x) <i>⇒ Decimal</i></code></h5> 435 <p><code>x</code>: <i>number|string|Decimal</i></p> 436 <p>See <code><a href='#ceil'>ceil</a></code>.</p> 437 <pre>a = Decimal.ceil(x) 438b = new Decimal(x).ceil() 439a.equals(b) // true</pre> 440 441 442 443 <h5 id="Dclamp">clamp<code class='inset'>.clamp(min, max) <i>⇒ Decimal</i></code></h5> 444 <p> 445 <code>min</code>: <i>number|string|Decimal</i><br /> 446 <code>max</code>: <i>number|string|Decimal</i> 447 </p> 448 <p>See <code><a href='#clamp'>clampedTo</a></code>.</p> 449 <pre>Decimal.clamp(10.1, 0, 10) // '10'</pre> 450 451 452 453 <h5 id="Dclone"> 454 clone 455 <code class='inset'>.clone([object]) <i>⇒ Decimal constructor</i></code> 456 </h5> 457 <p><code>object</code>: <i>object</i></p> 458 <p> 459 Returns a new independent Decimal constructor with configuration settings as described by 460 <code>object</code> (see <a href='#Dset'><code>set</code></a>), or with the same 461 settings as <code>this</code> Decimal constructor if <code>object</code> is omitted. 462 </p> 463 <pre>Decimal.set({ precision: 5 }) 464Decimal9 = Decimal.clone({ precision: 9 }) 465 466a = new Decimal(1) 467b = new Decimal9(1) 468 469a.div(3) // 0.33333 470b.div(3) // 0.333333333 471 472// Decimal9 = Decimal.clone({ precision: 9 }) is equivalent to: 473Decimal9 = Decimal.clone() 474Decimal9.set({ precision: 9 })</pre> 475 <p> 476 If <code>object</code> has a <code>'defaults'</code> property with value <code>true</code> 477 then the new constructor will use the default configuration. 478 </p> 479 <pre> 480D1 = Decimal.clone({ defaults: true }) 481 482// Use the defaults except for precision 483D2 = Decimal.clone({ defaults: true, precision: 50 })</pre> 484 <p> 485 It is not inefficient in terms of memory usage to use multiple Decimal constructors as 486 functions are shared between them. 487 </p> 488 489 490 <h5 id="Dcos">cos<code class='inset'>.cos(x) <i>⇒ Decimal</i></code></h5> 491 <p><code>x</code>: <i>number|string|Decimal</i></p> 492 <p>See <code><a href='#cos'>cosine</a></code>.</p> 493 <pre>a = Decimal.cos(x) 494b = new Decimal(x).cos() 495a.equals(b) // true</pre> 496 497 498 499 <h5 id="Dcosh">cosh<code class='inset'>.cosh(x) <i>⇒ Decimal</i></code></h5> 500 <p><code>x</code>: <i>number|string|Decimal</i></p> 501 <p>See <code><a href='#cos'>hyperbolicCosine</a></code>.</p> 502 <pre>a = Decimal.cosh(x) 503b = new Decimal(x).cosh() 504a.equals(b) // true</pre> 505 506 507 508 <h5 id="Ddiv">div<code class='inset'>.div(x, y) <i>⇒ Decimal</i></code></h5> 509 <p> 510 <code>x</code>: <i>number|string|Decimal</i><br /> 511 <code>y</code>: <i>number|string|Decimal</i> 512 </p> 513 <p>See <code><a href='#div'>dividedBy</a></code>.</p> 514 <pre>a = Decimal.div(x, y) 515b = new Decimal(x).div(y) 516a.equals(b) // true</pre> 517 518 519 520 <h5 id="Dexp">exp<code class='inset'>.exp(x) <i>⇒ Decimal</i></code></h5> 521 <p><code>x</code>: <i>number|string|Decimal</i></p> 522 <p>See <code><a href='#exp'>naturalExponential</a></code>.</p> 523 <pre>a = Decimal.exp(x) 524b = new Decimal(x).exp() 525a.equals(b) // true</pre> 526 527 528 529 <h5 id="Dfloor">floor<code class='inset'>.floor(x) <i>⇒ Decimal</i></code></h5> 530 <p><code>x</code>: <i>number|string|Decimal</i></p> 531 <p>See <code><a href='#floor'>floor</a></code>.</p> 532 <pre>a = Decimal.floor(x) 533b = new Decimal(x).floor() 534a.equals(b) // true</pre> 535 536 537 538 <h5 id="Dhypot"> 539 hypot<code class='inset'>.hypot([x [, y, ...]]) <i>⇒ Decimal</i></code> 540 </h5> 541 <p> 542 <code>x</code>: <i>number|string|Decimal</i><br /> 543 <code>y</code>: <i>number|string|Decimal</i> 544 </p> 545 <p> 546 Returns a new Decimal whose value is the square root of the sum of the squares of the 547 arguments, rounded to <a href='#precision'><code>precision</code></a> significant digits using 548 rounding mode <a href='#rounding'><code>rounding</code></a>. 549 </p> 550 <pre>r = Decimal.hypot(x, y)</pre> 551 552 553 554 <h5 id="Dln">ln<code class='inset'>.ln(x) <i>⇒ Decimal</i></code></h5> 555 <p><code>x</code>: <i>number|string|Decimal</i></p> 556 <p>See <code><a href='#ln'>naturalLogarithm</a></code>.</p> 557 <pre>a = Decimal.ln(x) 558b = new Decimal(x).ln() 559a.equals(b) // true</pre> 560 561 562 563 <h5 id="DisDecimal"> 564 isDecimal<code class='inset'>.isDecimal(object) <i>⇒ boolean</i></code> 565 </h5> 566 <p><code>object</code>: <i>any</i></p> 567 <p> 568 Returns <code>true</code> if <code>object</code> is a Decimal instance (where Decimal is any 569 Decimal constructor), or <code>false</code> if it is not. 570 </p> 571 <pre>a = new Decimal(1) 572b = {} 573a instanceof Decimal // true 574Decimal.isDecimal(a) // true 575Decimal.isDecimal(b) // false</pre> 576 577 578 579 <h5 id="Dlog">log<code class='inset'>.log(x [, base]) <i>⇒ Decimal</i></code></h5> 580 <p> 581 <code>x</code>: <i>number|string|Decimal</i><br /> 582 <code>base</code>: <i>number|string|Decimal</i> 583 </p> 584 <p>See <code><a href='#log'>logarithm</a></code>.</p> 585 <p> 586 The default base is <code>10</code>, which is not the same as JavaScript's 587 <code>Math.log()</code>, which returns the natural logarithm (base <code>e</code>). 588 </p> 589 <pre>a = Decimal.log(x, y) 590b = new Decimal(x).log(y) 591a.equals(b) // true</pre> 592 593 594 595 <h5 id="Dlog2">log2<code class='inset'>.log2(x) <i>⇒ Decimal</i></code></h5> 596 <p><code>x</code>: <i>number|string|Decimal</i></p> 597 <p> 598 Returns a new Decimal whose value is the base <code>2</code> logarithm of <code>x</code>, 599 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 600 mode <a href='#rounding'><code>rounding</code></a>. 601 </p> 602 <pre>r = Decimal.log2(x)</pre> 603 604 605 606 <h5 id="Dlog10">log10<code class='inset'>.log10(x) <i>⇒ Decimal</i></code></h5> 607 <p><code>x</code>: <i>number|string|Decimal</i></p> 608 <p> 609 Returns a new Decimal whose value is the base <code>10</code> logarithm of <code>x</code>, 610 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 611 mode <a href='#rounding'><code>rounding</code></a>. 612 </p> 613 <pre>r = Decimal.log10(x)</pre> 614 615 616 617 <h5 id="Dmax"> 618 max<code class='inset'>.max(x [, y, ...]) <i>⇒ Decimal</i></code> 619 </h5> 620 <p> 621 <code>x</code>: <i>number|string|Decimal</i><br /> 622 <code>y</code>: <i>number|string|Decimal</i> 623 </p> 624 <p>Returns a new Decimal whose value is the maximum of the <code>arguments</code>.</p> 625 <pre>r = Decimal.max(x, y, z)</pre> 626 627 628 629 <h5 id="Dmin"> 630 min<code class='inset'>.min(x [, y, ...]) <i>⇒ Decimal</i></code> 631 </h5> 632 <p> 633 <code>x</code>: <i>number|string|Decimal</i><br /> 634 <code>y</code>: <i>number|string|Decimal</i> 635 </p> 636 <p>Returns a new Decimal whose value is the minimum of the <code>arguments</code>.</p> 637 <pre>r = Decimal.min(x, y, z)</pre> 638 639 640 641 <h5 id="Dmod">mod<code class='inset'>.mod(x, y) <i>⇒ Decimal</i></code></h5> 642 <p> 643 <code>x</code>: <i>number|string|Decimal</i><br /> 644 <code>y</code>: <i>number|string|Decimal</i> 645 </p> 646 <p>See <code><a href='#mod'>modulo</a></code>.</p> 647 <pre>a = Decimal.mod(x, y) 648b = new Decimal(x).mod(y) 649a.equals(b) // true</pre> 650 651 652 653 <h5 id="Dmul">mul<code class='inset'>.mul(x, y) <i>⇒ Decimal</i></code></h5> 654 <p> 655 <code>x</code>: <i>number|string|Decimal</i><br /> 656 <code>y</code>: <i>number|string|Decimal</i> 657 </p> 658 <p>See <code><a href='#mul'>times</a></code>.</p> 659 <pre>a = Decimal.mul(x, y) 660b = new Decimal(x).mul(y) 661a.equals(b) // true</pre> 662 663 664 665 <h5 id="DnoConflict"> 666 noConflict<code class='inset'>.noConflict() <i>⇒ Decimal constructor</i></code> 667 </h5> 668 <p><i>Browsers only.</i></p> 669 <p> 670 Reverts the <code>Decimal</code> variable to the value it had before this library was loaded 671 and returns a reference to the original Decimal constructor so it can be assigned to a 672 variable with a different name. 673 </p> 674 <pre> 675<script> Decimal = 1 </script> 676<script src='/path/to/decimal.js'></script> 677<script> 678 a = new Decimal(2) // '2' 679 D = Decimal.noConflict() 680 Decimal // 1 681 b = new D(3) // '3' 682</script></pre> 683 684 685 686 <h5 id="Dpow">pow<code class='inset'>.pow(base, exponent) <i>⇒ Decimal</i></code></h5> 687 <p> 688 <code>base</code>: <i>number|string|Decimal</i><br /> 689 <code>exponent</code>: <i>number|string|Decimal</i> 690 </p> 691 <p>See <code><a href="#pow">toPower</a></code>.</p> 692 <pre>a = Decimal.pow(x, y) 693b = new Decimal(x).pow(y) 694a.equals(b) // true</pre> 695 696 697 698 <h5 id="Drandom"> 699 random<code class='inset'>.random([dp]) <i>⇒ Decimal</i></code> 700 </h5> 701 <p><code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive</p> 702 <p> 703 Returns a new Decimal with a pseudo-random value equal to or greater than <code>0</code> and 704 less than <code>1</code>. 705 </p> 706 <p> 707 The return value will have <code>dp</code> decimal places (or less if trailing zeros are 708 produced). If <code>dp</code> is omitted then the number of decimal places will 709 default to the current <a href='#precision'><code>precision</code></a> setting. 710 </p> 711 <p> 712 If the value of <code>this</code> Decimal constructor's 713 <a href='#crypto'><code>crypto</code></a> property is <code>true</code>, and the 714 <code>crypto</code> object is available globally in the host environment, the random digits of 715 the return value are generated by either <code>crypto.getRandomValues</code> (Web Cryptography 716 API in modern browsers) or <code>crypto.randomBytes</code> (Node.js), otherwise, if the the 717 value of the property is <code>false</code> the return value is generated by 718 <code>Math.random</code> (fastest). 719 </p> 720 <p>To make the <code>crypto</code> object available globally in Node.js use</p> 721 <pre>global.crypto = require('crypto')</pre> 722 <p> 723 If the value of <code>this</code> Decimal constructor's 724 <a href='#crypto'><code>crypto</code></a> property is set <code>true</code> and the 725 <code>crypto</code> object and associated method are not available, an exception will be 726 thrown. 727 </p> 728 <p> 729 If one of the <code>crypto</code> methods is used, the value of the returned Decimal should be 730 cryptographically-secure and statistically indistinguishable from a random value. 731 </p> 732 <pre>Decimal.set({ precision: 10 }) 733Decimal.random() // '0.4117936847' 734Decimal.random(20) // '0.78193327636914089009'</pre> 735 736 737 <h5 id="Dround">round<code class='inset'>.round(x) <i>⇒ Decimal</i></code></h5> 738 <p><code>x</code>: <i>number|string|Decimal</i></p> 739 <p>See <code><a href='#round'>round</a></code>.</p> 740 <pre>a = Decimal.round(x) 741b = new Decimal(x).round() 742a.equals(b) // true</pre> 743 744 745 746 <h5 id="Dset">set<code class='inset'>.set(object) <i>⇒ Decimal constructor</i></code></h5> 747 <p><code>object</code>: <i>object</i></p> 748 <p> 749 Configures the 'global' settings for <code>this</code> particular Decimal constructor, i.e. 750 the settings which apply to operations performed on the Decimal instances created by it. 751 </p> 752 <p>Returns <code>this</code> Decimal constructor.</p> 753 <p> 754 The configuration object, <code>object</code>, can contain some or all of the properties 755 described in detail at <a href="#constructor-properties">Properties</a> and shown in the 756 example below. 757 </p> 758 <p> 759 The values of the configuration object properties are checked for validity and then stored as 760 equivalently-named properties of <code>this</code> Decimal constructor. 761 </p> 762 <p> 763 If <code>object</code> has a <code>'defaults'</code> property with value <code>true</code> 764 then any unspecified properties will be reset to their default values. 765 </p> 766 <p>Throws on an invalid <code>object</code> or configuration property value.</p> 767 <pre> 768// Defaults 769Decimal.set({ 770 precision: 20, 771 rounding: 4, 772 toExpNeg: -7, 773 toExpPos: 21, 774 maxE: 9e15, 775 minE: -9e15, 776 modulo: 1, 777 crypto: false 778}) 779 780// Reset all properties to their default values 781Decimal.set({ defaults: true }) 782 783// Set precision to 50 and all other properties to their default values 784Decimal.set({ precision: 50, defaults: true })</pre> 785 <p> 786 The properties of a Decimal constructor can also be set by direct assignment, but that will 787 by-pass the validity checking that this method performs - this is not a problem if the user 788 knows that the assignment is valid. 789 </p> 790 <pre>Decimal.precision = 40</pre> 791 792 793 794 <h5 id="Dsign">sign<code class='inset'>.sign(x) <i>⇒ number</i></code></h5> 795 <p><code>x</code>: <i>number|string|Decimal</i></p> 796 <table> 797 <tr><th>Returns</th><th> </th></tr> 798 <tr> 799 <td class='centre'><code>1</code></td> 800 <td>if the value of <code>x</code> is non-zero and its sign is positive</td> 801 </tr> 802 <tr> 803 <td class='centre'><code>-1</code></td> 804 <td>if the value of <code>x</code> is non-zero and its sign is negative</td> 805 </tr> 806 <tr> 807 <td class='centre'><code>0</code></td> 808 <td>if the value of <code>x</code> is positive zero</td> 809 </tr> 810 <tr> 811 <td class='centre'><code>-0</code></td> 812 <td>if the value of <code>x</code> is negative zero</td> 813 </tr> 814 <tr> 815 <td class='centre'><code>NaN</code></td> 816 <td>if the value of <code>x</code> is <code>NaN</code></td> 817 </tr> 818 </table> 819 <pre>r = Decimal.sign(x)</pre> 820 821 822 823 <h5 id="Dsin">sin<code class='inset'>.sin(x) <i>⇒ Decimal</i></code></h5> 824 <p><code>x</code>: <i>number|string|Decimal</i></p> 825 <p>See <code><a href='#sin'>sine</a></code>.</p> 826 <pre>a = Decimal.sin(x) 827b = new Decimal(x).sin() 828a.equals(b) // true</pre> 829 830 831 832 <h5 id="Dsinh">sinh<code class='inset'>.sinh(x) <i>⇒ Decimal</i></code></h5> 833 <p><code>x</code>: <i>number|string|Decimal</i></p> 834 <p>See <code><a href='#sin'>hyperbolicSine</a></code>.</p> 835 <pre>a = Decimal.sinh(x) 836b = new Decimal(x).sinh() 837a.equals(b) // true</pre> 838 839 840 841 <h5 id="Dsqrt">sqrt<code class='inset'>.sqrt(x) <i>⇒ Decimal</i></code></h5> 842 <p><code>x</code>: <i>number|string|Decimal</i></p> 843 <p>See <a href='#sqrt'>squareRoot</a>.</p> 844 <pre>a = Decimal.sqrt(x) 845b = new Decimal(x).sqrt() 846a.equals(b) // true</pre> 847 848 849 850 <h5 id="Dsub">sub<code class='inset'>.sub(x, y) <i>⇒ Decimal</i></code></h5> 851 <p> 852 <code>x</code>: <i>number|string|Decimal</i><br /> 853 <code>y</code>: <i>number|string|Decimal</i> 854 </p> 855 <p>See <code><a href='#sub'>minus</a></code>.</p> 856 <pre>a = Decimal.sub(x, y) 857b = new Decimal(x).sub(y) 858a.equals(b) // true</pre> 859 860 861 862 <h5 id="Dsum">sum<code class='inset'>.sum(x [, y, ...]) <i>⇒ Decimal</i></code></h5> 863 <p> 864 <code>x</code>: <i>number|string|Decimal</i><br /> 865 <code>y</code>: <i>number|string|Decimal</i> 866 </p> 867 <p> 868 Returns a new Decimal whose value is the sum of the <code>arguments</code>, 869 rounded to <a href='#precision'><code>precision</code></a> significant digits using 870 rounding mode <a href='#rounding'><code>rounding</code></a>.<br /> 871 Only the result is rounded, not the intermediate summations. 872 </p> 873 <pre> 874x = 5 875y = '16' 876z = new Decimal(-11) 877Decimal.sum(x, y, z) // '10'</pre> 878 879 880 881 <h5 id="Dtan">tan<code class='inset'>.tan(x) <i>⇒ Decimal</i></code></h5> 882 <p><code>x</code>: <i>number|string|Decimal</i></p> 883 <p>See <code><a href='#tan'>tangent</a></code>.</p> 884 <pre>a = Decimal.tan(x) 885b = new Decimal(x).tan() 886a.equals(b) // true</pre> 887 888 889 890 <h5 id="Dtanh">tanh<code class='inset'>.tanh(x) <i>⇒ Decimal</i></code></h5> 891 <p><code>x</code>: <i>number|string|Decimal</i></p> 892 <p>See <code><a href='#tan'>hyperbolicTangent</a></code>.</p> 893 <pre>a = Decimal.tanh(x) 894b = new Decimal(x).tanh() 895a.equals(b) // true</pre> 896 897 898 899 <h5 id="Dtrunc">trunc<code class='inset'>.trunc(x) <i>⇒ Decimal</i></code></h5> 900 <p><code>x</code>: <i>number|string|Decimal</i></p> 901 <p>See <code><a href='#trunc'>truncated</a></code>.</p> 902 <pre>a = Decimal.trunc(x) 903b = new Decimal(x).trunc() 904a.equals(b) // true</pre> 905 906 907 908 909 <h4 id="constructor-properties">Properties</h4> 910 <p>The properties of a Decimal constructor.</p> 911 912 913 914 <h6 id='configProps'>Configuration properties</h6> 915 <p> 916 The values of the configuration properties <a href='#precision'><code>precision</code></a>, 917 <a href='#rounding'><code>rounding</code></a>, <a href='#minE'><code>minE</code></a>, 918 <a href='#maxE'><code>maxE</code></a>, <a href='#toExpNeg'><code>toExpNeg</code></a>, 919 <a href='#toExpPos'><code>toExpPos</code></a>, <a href='#modulo'><code>modulo</code></a>, and 920 <a href='#crypto'><code>crypto</code></a> are set using the 921 <a href='#Dset'><code>set</code></a> method. 922 </p> 923 <p> 924 As simple object properties they can be set directly without using 925 <a href='#Dset'><code>set</code></a>, and it is fine to do so, but the values assigned 926 will not then be checked for validity. For example: 927 </p> 928 <pre>Decimal.set({ precision: 0 }) 929// '[DecimalError] Invalid argument: precision: 0' 930 931Decimal.precision = 0 932// No error is thrown and the results of calculations are unreliable</pre> 933 934 935 936 <h5 id="precision">precision</h5> 937 <p> 938 <i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br /> 939 Default value: <code>20</code> 940 </p> 941 <p>The <i>maximum</i> number of significant digits of the result of an operation.</p> 942 <p> 943 All functions which return a Decimal will round the return value to <code>precision</code> 944 significant digits except <a href='#decimal'><code>Decimal</code></a>, 945 <a href='#abs'><code>absoluteValue</code></a>, 946 <a href='#ceil'><code>ceil</code></a>, 947 <a href='#clamp'><code>clampedTo</code></a>, 948 <a href='#floor'><code>floor</code></a>, 949 <a href='#neg'><code>negated</code></a>, 950 <a href='#round'><code>round</code></a>, 951 <a href='#toDP'><code>toDecimalPlaces</code></a>, 952 <a href='#toNearest'><code>toNearest</code></a> and 953 <a href='#trunc'><code>truncated</code></a>. 954 </p> 955 <p> 956 See <code><a href='#Pi'>Pi</a></code> for the precision limit of the trigonometric methods. 957 </p> 958 <pre>Decimal.set({ precision: 5 }) 959Decimal.precision // 5</pre> 960 961 962 963 <h5 id="rounding">rounding</h5> 964 <p> 965 <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive<br /> 966 Default value: <code>4</code> <a href="#modes">(<code>ROUND_HALF_UP</code>)</a> 967 </p> 968 <p> 969 The default rounding mode used when rounding the result of an operation to 970 <code><a href='#precision'>precision</a></code> significant digits, and when rounding the 971 return value of the <a href='#round'><code>round</code></a>, 972 <a href='#toBinary'><code>toBinary</code></a>, 973 <a href='#toDP'><code>toDecimalPlaces</code></a>, 974 <a href='#toExponential'><code>toExponential</code></a>, 975 <a href='#toFixed'><code>toFixed</code></a>, 976 <a href='#toHexadecimal'><code>toHexadecimal</code></a>, 977 <a href='#toNearest'><code>toNearest</code></a>, 978 <a href='#toOctal'><code>toOctal</code></a>, 979 <a href='#toPrecision'><code>toPrecision</code></a> and 980 <a href='#toSD'><code>toSignificantDigits</code></a> methods. 981 </p> 982 <p> 983 The <a href='#modes'>rounding modes</a> are available as enumerated properties of the 984 constructor. 985 </p> 986 <pre>Decimal.set({ rounding: Decimal.ROUND_UP }) 987Decimal.set({ rounding: 0 }) // equivalent 988Decimal.rounding // 0</pre> 989 990 991 992 <h5 id="minE">minE</h5> 993 <p> 994 <i>number</i>: integer, <code>-9e15</code> to <code>0</code> inclusive<br /> 995 Default value: <code>-9e15</code> 996 </p> 997 <p> 998 The negative exponent limit, i.e. the exponent value below which underflow to zero occurs. 999 </p> 1000 <p> 1001 If the <code>Decimal</code> to be returned by a calculation would have an exponent lower than 1002 <code>minE</code> then the value of that <code>Decimal</code> becomes zero. 1003 <p> 1004 JavaScript numbers underflow to zero for exponents below <code>-324</code>. 1005 </p> 1006 <pre>Decimal.set({ minE: -500 }) 1007Decimal.minE // -500 1008new Decimal('1e-500') // '1e-500' 1009new Decimal('9.9e-501') // '0' 1010 1011Decimal.set({ minE: -3 }) 1012new Decimal(0.001) // '0.001' e is -3 1013new Decimal(0.0001) // '0' e is -4</pre> 1014 <p> 1015 The smallest possible magnitude of a non-zero Decimal is <code>1e-9000000000000000</code> 1016 </p> 1017 1018 1019 1020 <h5 id="maxE">maxE</h5> 1021 <p> 1022 <i>number</i>: integer, <code>0</code> to <code>9e15</code> inclusive<br /> 1023 Default value: <code>9e15</code> 1024 </p> 1025 <p> 1026 The positive exponent limit, i.e. the exponent value above which overflow to 1027 <code>Infinity</code> occurs. 1028 </p> 1029 <p> 1030 If the <code>Decimal</code> to be returned by a calculation would have an exponent higher than 1031 <code>maxE</code> then the value of that <code>Decimal</code> becomes <code>Infinity</code>. 1032 <p> 1033 JavaScript numbers overflow to <code>Infinity</code> for exponents above <code>308</code>. 1034 </p> 1035 <pre>Decimal.set({ maxE: 500 }) 1036Decimal.maxE // 500 1037new Decimal('9.999e500') // '9.999e+500' 1038new Decimal('1e501') // 'Infinity' 1039 1040Decimal.set({ maxE: 4 }) 1041new Decimal(99999) // '99999' e is 4 1042new Decimal(100000) // 'Infinity'</pre> 1043 <p> 1044 The largest possible magnitude of a finite Decimal is <code>9.999...e+9000000000000000</code> 1045 </p> 1046 1047 1048 1049 <h5 id="toExpNeg">toExpNeg</h5> 1050 <p> 1051 <i>number</i>: integer, <code>-9e15</code> to <code>0</code> inclusive<br /> 1052 Default value: <code>-7</code> 1053 </p> 1054 <p> 1055 The negative exponent value at and below which <a href='#toString'><code>toString</code></a> 1056 returns exponential notation. 1057 </p> 1058 <pre>Decimal.set({ toExpNeg: -7 }) 1059Decimal.toExpNeg // -7 1060new Decimal(0.00000123) // '0.00000123' e is -6 1061new Decimal(0.000000123) // '1.23e-7' 1062 1063// Always return exponential notation: 1064Decimal.set({ toExpNeg: 0 })</pre> 1065 <p> 1066 JavaScript numbers use exponential notation for negative exponents of <code>-7</code> and 1067 below. 1068 </p> 1069 <p> 1070 Regardless of the value of <code>toExpNeg</code>, the 1071 <a href='#toFixed'><code>toFixed</code></a> method will always return a value in normal 1072 notation and the <a href='#toExponential'><code>toExponential</code></a> method will always 1073 return a value in exponential form. 1074 </p> 1075 1076 1077 1078 <h5 id="toExpPos">toExpPos</h5> 1079 <p> 1080 <i>number</i>: integer, <code>0</code> to <code>9e15</code> inclusive<br /> 1081 Default value: <code>20</code> 1082 </p> 1083 <p> 1084 The positive exponent value at and above which <a href='#toString'><code>toString</code></a> 1085 returns exponential notation. 1086 </p> 1087 <pre>Decimal.set({ toExpPos: 2 }) 1088Decimal.toExpPos // 2 1089new Decimal(12.3) // '12.3' e is 1 1090new Decimal(123) // '1.23e+2' 1091 1092// Always return exponential notation: 1093Decimal.set({ toExpPos: 0 })</pre> 1094 <p> 1095 JavaScript numbers use exponential notation for positive exponents of <code>20</code> and 1096 above. 1097 </p> 1098 <p> 1099 Regardless of the value of <code>toExpPos</code>, the 1100 <a href='#toFixed'><code>toFixed</code></a> method will always return a value in normal 1101 notation and the <a href='#toExponential'><code>toExponential</code></a> method will always 1102 return a value in exponential form. 1103 </p> 1104 1105 1106 1107 <h5 id="modulo">modulo</h5> 1108 <p> 1109 <i>number</i>: integer, <code>0</code> to <code>9</code> inclusive<br /> 1110 Default value: <code>1</code> (<code>ROUND_DOWN</code>) 1111 </p> 1112 <p>The modulo mode used when calculating the modulus: <code>a mod n</code>.</p> 1113 <p> 1114 The quotient, <code>q = a / n</code>, is calculated according to the 1115 <a href='#rounding'><code>rounding</code></a> mode that corresponds to the chosen 1116 <code>modulo</code> mode. 1117 </p> 1118 <p>The remainder, <code>r</code>, is calculated as: <code>r = a - n * q</code>.</p> 1119 <p> 1120 The modes that are most commonly used for the modulus/remainder operation are shown in the 1121 following table. Although the other <a href='#rounding'><code>rounding</code></a> modes can 1122 be used, they may not give useful results. 1123 </p> 1124 <table> 1125 <tr><th>Property</th><th>Value</th><th>Description</th></tr> 1126 <tr> 1127 <td>ROUND_UP</td><td class='centre'>0</td> 1128 <td>The remainder is positive if the dividend is negative, else is negative</td> 1129 </tr> 1130 <tr> 1131 <td>ROUND_DOWN</td><td class='centre'>1</td> 1132 <td> 1133 The remainder has the same sign as the dividend.<br /> 1134 This uses truncating division and matches the behaviour of JavaScript's remainder 1135 operator <code>%</code>. 1136 </td> 1137 </tr> 1138 <tr> 1139 <td>ROUND_FLOOR</td><td class='centre'>3</td> 1140 <td> 1141 The remainder has the same sign as the divisor.<br /> 1142 (This matches Python's <code>%</code> operator) 1143 </td> 1144 </tr> 1145 <tr> 1146 <td>ROUND_HALF_EVEN</td><td class='centre'>6</td> 1147 <td>The <i>IEEE 754</i> remainder function</td> 1148 </tr> 1149 <tr> 1150 <td>EUCLID</td><td class='centre'>9</td> 1151 <td> 1152 The remainder is always positive.<br /> 1153 Euclidian division: <code>q = sign(x) * floor(a / abs(x))</code>. 1154 </td> 1155 </tr> 1156 </table> 1157 <p> 1158 The rounding/modulo modes are available as enumerated properties of the Decimal constructor. 1159 </p> 1160 <pre>Decimal.set({ modulo: Decimal.EUCLID }) 1161Decimal.set({ modulo: 9 }) // equivalent 1162Decimal.modulo // 9</pre> 1163 1164 1165 1166 <h5 id="crypto">crypto</h5> 1167 <p> 1168 <i>boolean</i>: <code>true/false</code><br /> Default value: <code>false</code> 1169 </p> 1170 <p> 1171 The value that determines whether cryptographically-secure pseudo-random number generation is 1172 used. 1173 </p> 1174 <p>See <a href='#Drandom'><code>random</code></a>.</p> 1175 <pre> 1176// Node.js 1177global.crypto = require('crypto') 1178 1179Decimal.crypto // false 1180Decimal.set({ crypto: true }) 1181Decimal.crypto // true</pre> 1182 1183 1184 1185 <h6 id="modes">Rounding modes</h6> 1186 <p> 1187 The library's enumerated rounding modes are stored as properties of the Decimal constructor. 1188 <br />They are not referenced internally by the library itself. 1189 </p> 1190 <p>Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.</p> 1191 <table> 1192 <tr><th>Property</th><th>Value</th><th>Description</th></tr> 1193 <tr><td><b>ROUND_UP</b></td><td class='centre'>0</td><td>Rounds away from zero</td></tr> 1194 <tr><td><b>ROUND_DOWN</b></td><td class='centre'>1</td><td>Rounds towards zero</td></tr> 1195 <tr><td><b>ROUND_CEIL</b></td><td class='centre'>2</td><td>Rounds towards Infinity</td></tr> 1196 <tr><td><b>ROUND_FLOOR</b></td><td class='centre'>3</td><td>Rounds towards -Infinity</td></tr> 1197 <tr> 1198 <td><b>ROUND_HALF_UP</b></td><td class='centre'>4</td> 1199 <td>Rounds towards nearest neighbour.<br />If equidistant, rounds away from zero</td> 1200 </tr> 1201 <tr> 1202 <td><b>ROUND_HALF_DOWN</b></td><td class='centre'>5</td> 1203 <td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards zero</td> 1204 </tr> 1205 <tr> 1206 <td><b>ROUND_HALF_EVEN</b></td><td class='centre'>6</td> 1207 <td> 1208 Rounds towards nearest neighbour.<br />If equidistant, rounds towards even neighbour 1209 </td> 1210 </tr> 1211 <tr> 1212 <td><b>ROUND_HALF_CEIL</b></td><td class='centre'>7</td> 1213 <td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards Infinity</td> 1214 </tr> 1215 <tr> 1216 <td><b>ROUND_HALF_FLOOR</b></td><td class='centre'>8</td> 1217 <td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards -Infinity</td> 1218 </tr> 1219 <tr> 1220 <td><b>EUCLID</b></td><td class='centre'>9</td> 1221 <td>Not a rounding mode, see <a href='#modulo'>modulo</a></td> 1222 </tr> 1223 </table> 1224 <pre>Decimal.set({ rounding: Decimal.ROUND_CEIL }) 1225Decimal.set({ rounding: 2 }) // equivalent 1226Decimal.rounding // 2</pre> 1227 1228 1229 1230 1231 <h3>INSTANCE</h3> 1232 1233 <h4 id="prototype-methods">Methods</h4> 1234 <p>The methods inherited by a Decimal instance from its constructor's prototype object.</p> 1235 <p>A Decimal instance is immutable in the sense that it is not changed by its methods.</p> 1236 <p>Methods that return a Decimal can be chained:</p> 1237 <pre>x = new Decimal(2).times('999.999999999999999').dividedBy(4).ceil()</pre> 1238 <p>Methods do not round their arguments before execution.</p> 1239 <p> 1240 The treatment of <code>±0</code>, <code>±Infinity</code> and <code>NaN</code> 1241 is consistent with how JavaScript treats these values. 1242 </p> 1243 <p> 1244 Many method names have a shorter alias. (Internally, the library always uses the shorter 1245 method names.) 1246 </p> 1247 1248 1249 1250 <h5 id="abs">absoluteValue<code class='inset'>.abs() <i>⇒ Decimal</i></code></h5> 1251 <p> 1252 Returns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of 1253 this Decimal. 1254 </p> 1255 <p> 1256 The return value is not affected by the value of the 1257 <a href='#precision'><code>precision</code></a> setting. 1258 </p> 1259 <pre> 1260x = new Decimal(-0.8) 1261y = x.absoluteValue() // '0.8' 1262z = y.abs() // '0.8'</pre> 1263 1264 1265 1266 <h5 id="ceil">ceil<code class='inset'>.ceil() <i>⇒ Decimal</i></code></h5> 1267 <p> 1268 Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in 1269 the direction of positive <code>Infinity</code>. 1270 </p> 1271 <p> 1272 The return value is not affected by the value of the 1273 <a href='#precision'><code>precision</code></a> setting. 1274 </p> 1275 <pre> 1276x = new Decimal(1.3) 1277x.ceil() // '2' 1278y = new Decimal(-1.8) 1279y.ceil() // '-1'</pre> 1280 1281 1282 1283 <h5 id="clamp">clampedTo<code class='inset'>.clamp(min, max) <i>⇒ Decimal</i></code></h5> 1284 <p> 1285 <code>min</code>: <i>number|string|Decimal</i><br /> 1286 <code>max</code>: <i>number|string|Decimal</i> 1287 </p> 1288 <p> 1289 Returns a new Decimal whose value is the value of this Decimal clamped to the range 1290 delineated by <code>min</code> and <code>max</code>. 1291 </p> 1292 <p> 1293 The return value is not affected by the value of the 1294 <a href='#precision'><code>precision</code></a> setting. 1295 </p> 1296 <pre> 1297x = new Decimal(5) 1298min = new Decimal(100) 1299max = new Decimal(Infinity) 1300x.clampedTo(min, max) // '100' 1301x.clamp(-10, -0.1) // '-0.1'</pre> 1302 1303 1304 1305 <h5 id="cmp">comparedTo<code class='inset'>.cmp(x) <i>⇒ number</i></code></h5> 1306 <p><code>x</code>: <i>number|string|Decimal</i></p> 1307 <table> 1308 <tr><th>Returns</th><th> </th></tr> 1309 <tr> 1310 <td class='centre'><code>1</code></td> 1311 <td>if the value of this Decimal is greater than the value of <code>x</code></td> 1312 </tr> 1313 <tr> 1314 <td class='centre'><code>-1</code></td> 1315 <td>if the value of this Decimal is less than the value of <code>x</code></td> 1316 </tr> 1317 <tr> 1318 <td class='centre'><code>0</code></td> 1319 <td>if this Decimal and <code>x</code> have the same value</td> 1320 </tr> 1321 <tr> 1322 <td class='centre'><code>NaN</code></td> 1323 <td>if the value of either this Decimal or <code>x</code> is <code>NaN</code> </td> 1324 </tr> 1325 </table> 1326 <pre> 1327x = new Decimal(Infinity) 1328y = new Decimal(5) 1329x.comparedTo(y) // 1 1330x.comparedTo(x.minus(1)) // 0 1331y.cmp(NaN) // NaN</pre> 1332 1333 1334 1335 <h5 id="cos">cosine<code class='inset'>.cos() <i>⇒ Decimal</i></code></h5> 1336 <p> 1337 Returns a new Decimal whose value is the cosine of the value in radians of this Decimal, 1338 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1339 mode <a href='#rounding'><code>rounding</code></a>. 1340 </p> 1341 <p> 1342 Domain: [<code>-Infinity, Infinity</code>]<br /> 1343 Range: [<code>-1, 1</code>] 1344 </p> 1345 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1346 <pre> 1347x = new Decimal(0.25) 1348x.cosine() // '0.96891242171064478414' 1349y = new Decimal(-0.25) 1350y.cos() // '0.96891242171064478414'</pre> 1351 1352 1353 1354 <h5 id="cbrt">cubeRoot<code class='inset'>.cbrt() <i>⇒ Decimal</i></code></h5> 1355 <p> 1356 Returns a new Decimal whose value is the cube root of this Decimal, rounded to 1357 <a href='#precision'><code>precision</code></a> significant digits using rounding mode 1358 <a href='#rounding'><code>rounding</code></a>. 1359 </p> 1360 <p> 1361 The return value will be correctly rounded, i.e. rounded as if the result was first calculated 1362 to an infinite number of correct digits before rounding. 1363 </p> 1364 <pre> 1365x = new Decimal(125) 1366x.cubeRoot() // '5' 1367y = new Decimal(3) 1368y.cbrt() // '1.4422495703074083823'</pre> 1369 1370 1371 1372 <h5 id="dp">decimalPlaces<code class='inset'>.dp() <i>⇒ number</i></code></h5> 1373 <p> 1374 Returns the number of decimal places, i.e. the number of digits after the decimal point, of 1375 the value of this Decimal. 1376 </p> 1377 <pre> 1378x = new Decimal(1.234) 1379x.decimalPlaces() // '3' 1380y = new Decimal(987.654321) 1381y.dp() // '6'</pre> 1382 1383 1384 1385 <h5 id="div">dividedBy<code class='inset'>.div(x) <i>⇒ Decimal</i></code></h5> 1386 <p><code>x</code>: <i>number|string|Decimal</i></p> 1387 <p> 1388 Returns a new Decimal whose value is the value of this Decimal divided by <code>x</code>, 1389 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1390 mode <a href='#rounding'><code>rounding</code></a>. 1391 </p> 1392 <pre> 1393x = new Decimal(355) 1394y = new Decimal(113) 1395x.dividedBy(y) // '3.14159292035398230088' 1396x.div(5) // '71'</pre> 1397 1398 1399 1400 <h5 id="divToInt"> 1401 dividedToIntegerBy<code class='inset'>.divToInt(x) <i>⇒ Decimal</i></code> 1402 </h5> 1403 <p><code>x</code>: <i>number|string|Decimal</i></p> 1404 <p> 1405 Return a new Decimal whose value is the integer part of dividing this Decimal by 1406 <code>x</code>, rounded to <code><a href='#precision'>precision</a></code> significant digits 1407 using rounding mode <a href='#rounding'><code>rounding</code></a>. 1408 </p> 1409 <pre> 1410x = new Decimal(5) 1411y = new Decimal(3) 1412x.dividedToIntegerBy(y) // '1' 1413x.divToInt(0.7) // '7'</pre> 1414 1415 1416 1417 <h5 id="eq">equals<code class='inset'>.eq(x) <i>⇒ boolean</i></code></h5> 1418 <p><code>x</code>: <i>number|string|Decimal</i></p> 1419 <p> 1420 Returns <code>true</code> if the value of this Decimal equals the value of <code>x</code>, 1421 otherwise returns <code>false</code>.<br /> As with JavaScript, <code>NaN</code> does not 1422 equal <code>NaN</code>. 1423 </p> 1424 <p>Note: This method uses the <code>cmp</code> method internally.</p> 1425 <pre> 14260 === 1e-324 // true 1427x = new Decimal(0) 1428x.equals('1e-324') // false 1429new Decimal(-0).eq(x) // true ( -0 === 0 ) 1430 1431y = new Decimal(NaN) 1432y.equals(NaN) // false</pre> 1433 1434 1435 1436 <h5 id="floor">floor<code class='inset'>.floor() <i>⇒ Decimal</i></code></h5> 1437 <p> 1438 Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in 1439 the direction of negative <code>Infinity</code>. 1440 </p> 1441 <p> 1442 The return value is not affected by the value of the 1443 <a href='#precision'><code>precision</code></a> setting. 1444 </p> 1445 <pre> 1446x = new Decimal(1.8) 1447x.floor() // '1' 1448y = new Decimal(-1.3) 1449y.floor() // '-2'</pre> 1450 1451 1452 1453 <h5 id="gt">greaterThan<code class='inset'>.gt(x) <i>⇒ boolean</i></code></h5> 1454 <p><code>x</code>: <i>number|string|Decimal</i></p> 1455 <p> 1456 Returns <code>true</code> if the value of this Decimal is greater than the value of 1457 <code>x</code>, otherwise returns <code>false</code>. 1458 </p> 1459 <p>Note: This method uses the <code>cmp</code> method internally.</p> 1460 <pre> 14610.1 > (0.3 - 0.2) // true 1462x = new Decimal(0.1) 1463x.greaterThan(Decimal(0.3).minus(0.2)) // false 1464new Decimal(0).gt(x) // false</pre> 1465 1466 1467 1468 <h5 id="gte"> 1469 greaterThanOrEqualTo<code class='inset'>.gte(x) <i>⇒ boolean</i></code> 1470 </h5> 1471 <p><code>x</code>: <i>number|string|Decimal</i></p> 1472 <p> 1473 Returns <code>true</code> if the value of this Decimal is greater than or equal to the value 1474 of <code>x</code>, otherwise returns <code>false</code>. 1475 </p> 1476 <p>Note: This method uses the <code>cmp</code> method internally.</p> 1477 <pre> 1478(0.3 - 0.2) >= 0.1 // false 1479x = new Decimal(0.3).minus(0.2) 1480x.greaterThanOrEqualTo(0.1) // true 1481new Decimal(1).gte(x) // true</pre> 1482 1483 1484 1485 <h5 id="cosh">hyperbolicCosine<code class='inset'>.cosh() <i>⇒ Decimal</i></code></h5> 1486 <p> 1487 Returns a new Decimal whose value is the hyperbolic cosine of the value in radians of this 1488 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1489 rounding mode <a href='#rounding'><code>rounding</code></a>. 1490 </p> 1491 <p> 1492 Domain: [<code>-Infinity, Infinity</code>]<br /> 1493 Range: [<code>1, Infinity</code>] 1494 </p> 1495 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1496 <pre> 1497x = new Decimal(1) 1498x.hyperbolicCosine() // '1.5430806348152437785' 1499y = new Decimal(0.5) 1500y.cosh() // '1.1276259652063807852'</pre> 1501 1502 1503 1504 <h5 id="sinh">hyperbolicSine<code class='inset'>.sinh() <i>⇒ Decimal</i></code></h5> 1505 <p> 1506 Returns a new Decimal whose value is the hyperbolic sine of the value in radians of this 1507 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1508 rounding mode <a href='#rounding'><code>rounding</code></a>. 1509 </p> 1510 <p> 1511 Domain: [<code>-Infinity, Infinity</code>]<br /> 1512 Range: [<code>-Infinity, Infinity</code>] 1513 </p> 1514 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1515 <pre> 1516x = new Decimal(1) 1517x.hyperbolicSine() // '1.1752011936438014569' 1518y = new Decimal(0.5) 1519y.sinh() // '0.52109530549374736162'</pre> 1520 1521 1522 1523 <h5 id="tanh">hyperbolicTangent<code class='inset'>.tanh() <i>⇒ Decimal</i></code></h5> 1524 <p> 1525 Returns a new Decimal whose value is the hyperbolic tangent of the value in radians of this 1526 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1527 rounding mode <a href='#rounding'><code>rounding</code></a>. 1528 </p> 1529 <p> 1530 Domain: [<code>-Infinity, Infinity</code>]<br /> 1531 Range: [<code>-1, 1</code>] 1532 </p> 1533 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1534 <pre> 1535x = new Decimal(1) 1536x.hyperbolicTangent() // '0.76159415595576488812' 1537y = new Decimal(0.5) 1538y.tanh() // '0.4621171572600097585'</pre> 1539 1540 1541 1542 <h5 id="acos">inverseCosine<code class='inset'>.acos() <i>⇒ Decimal</i></code></h5> 1543 <p> 1544 Returns a new Decimal whose value is the inverse cosine in radians of the value of this 1545 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1546 rounding mode <a href='#rounding'><code>rounding</code></a>. 1547 </p> 1548 <p> 1549 Domain: [<code>-1, 1</code>]<br /> 1550 Range: [<code>0, pi</code>] 1551 </p> 1552 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1553 <pre> 1554x = new Decimal(0) 1555x.inverseCosine() // '1.5707963267948966192' 1556y = new Decimal(0.5) 1557y.acos() // '1.0471975511965977462'</pre> 1558 1559 1560 1561 <h5 id="acosh"> 1562 inverseHyperbolicCosine<code class='inset'>.acosh() <i>⇒ Decimal</i></code> 1563 </h5> 1564 <p> 1565 Returns a new Decimal whose value is the inverse hyperbolic cosine in radians of the value of 1566 this Decimal, rounded to <a href='#precision'><code>precision</code></a> significant 1567 digits using rounding mode <a href='#rounding'><code>rounding</code></a>. 1568 </p> 1569 <p> 1570 Domain: [<code>1, Infinity</code>]<br /> 1571 Range: [<code>0, Infinity</code>] 1572 </p> 1573 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1574 <pre> 1575x = new Decimal(5) 1576x.inverseHyperbolicCosine() // '2.2924316695611776878' 1577y = new Decimal(50) 1578y.acosh() // '4.6050701709847571595'</pre> 1579 1580 1581 1582 <h5 id="asinh"> 1583 inverseHyperbolicSine<code class='inset'>.asinh() <i>⇒ Decimal</i></code> 1584 </h5> 1585 <p> 1586 Returns a new Decimal whose value is the inverse hyperbolic sine in radians of the value of 1587 this Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits 1588 using rounding mode <a href='#rounding'><code>rounding</code></a>. 1589 </p> 1590 <p> 1591 Domain: [<code>-Infinity, Infinity</code>]<br /> 1592 Range: [<code>-Infinity, Infinity</code>] 1593 </p> 1594 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1595 <pre> 1596x = new Decimal(5) 1597x.inverseHyperbolicSine() // '2.3124383412727526203' 1598y = new Decimal(50) 1599y.asinh() // '4.6052701709914238266'</pre> 1600 1601 1602 1603 <h5 id="atanh"> 1604 inverseHyperbolicTangent<code class='inset'>.atanh() <i>⇒ Decimal</i></code> 1605 </h5> 1606 <p> 1607 Returns a new Decimal whose value is the inverse hyperbolic tangent in radians of the value of 1608 this Decimal, rounded to <a href='#precision'><code>precision</code></a> significant 1609 digits using rounding mode <a href='#rounding'><code>rounding</code></a>. 1610 </p> 1611 <p> 1612 Domain: [<code>-1, 1</code>]<br /> 1613 Range: [<code>-Infinity, Infinity</code>] 1614 </p> 1615 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1616 <pre> 1617x = new Decimal(0.5) 1618x.inverseHyperbolicTangent() // '0.5493061443340548457' 1619y = new Decimal(0.75) 1620y.atanh() // '0.97295507452765665255'</pre> 1621 1622 1623 1624 <h5 id="asin">inverseSine<code class='inset'>.asin() <i>⇒ Decimal</i></code></h5> 1625 <p> 1626 Returns a new Decimal whose value is the inverse sine in radians of the value of this Decimal, 1627 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1628 mode <a href='#rounding'><code>rounding</code></a>. 1629 </p> 1630 <p> 1631 Domain: [<code>-1, 1</code>]<br /> 1632 Range: [<code>-pi/2, pi/2</code>] 1633 </p> 1634 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1635 <pre> 1636x = new Decimal(0.5) 1637x.inverseSine() // '0.52359877559829887308' 1638y = new Decimal(0.75) 1639y.asin() // '0.84806207898148100805'</pre> 1640 1641 1642 1643 <h5 id="atan">inverseTangent<code class='inset'>.atan() <i>⇒ Decimal</i></code></h5> 1644 <p> 1645 Returns a new Decimal whose value is the inverse tangent in radians of the value of this 1646 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1647 rounding mode <a href='#rounding'><code>rounding</code></a>. 1648 </p> 1649 <p> 1650 Domain: [<code>-Infinity, Infinity</code>]<br /> 1651 Range: [<code>-pi/2, pi/2</code>] 1652 </p> 1653 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1654 <pre> 1655x = new Decimal(0.5) 1656x.inverseTangent() // '0.46364760900080611621' 1657y = new Decimal(0.75) 1658y.atan() // '0.6435011087932843868'</pre> 1659 1660 1661 1662 <h5 id="isFinite">isFinite<code class='inset'>.isFinite() <i>⇒ boolean</i></code></h5> 1663 <p> 1664 Returns <code>true</code> if the value of this Decimal is a finite number, otherwise returns 1665 <code>false</code>.<br /> 1666 The only possible non-finite values of a Decimal are <code>NaN</code>, <code>Infinity</code> 1667 and <code>-Infinity</code>. 1668 </p> 1669 <pre> 1670x = new Decimal(1) 1671x.isFinite() // true 1672y = new Decimal(Infinity) 1673y.isFinite() // false</pre> 1674 1675 1676 1677 <h5 id="isInt">isInteger<code class='inset'>.isInt() <i>⇒ boolean</i></code></h5> 1678 <p> 1679 Returns <code>true</code> if the value of this Decimal is a whole number, otherwise returns 1680 <code>false</code>. 1681 </p> 1682 <pre> 1683x = new Decimal(1) 1684x.isInteger() // true 1685y = new Decimal(123.456) 1686y.isInt() // false</pre> 1687 1688 1689 1690 <h5 id="isNaN">isNaN<code class='inset'>.isNaN() <i>⇒ boolean</i></code></h5> 1691 <p> 1692 Returns <code>true</code> if the value of this Decimal is <code>NaN</code>, otherwise returns 1693 <code>false</code>. 1694 </p> 1695 <pre> 1696x = new Decimal(NaN) 1697x.isNaN() // true 1698y = new Decimal('Infinity') 1699y.isNaN() // false</pre> 1700 1701 1702 1703 <h5 id="isNeg">isNegative<code class='inset'>.isNeg() <i>⇒ boolean</i></code></h5> 1704 <p> 1705 Returns <code>true</code> if the value of this Decimal is negative, otherwise returns 1706 <code>false</code>. 1707 </p> 1708 <pre> 1709x = new Decimal(-0) 1710x.isNegative() // true 1711y = new Decimal(2) 1712y.isNeg // false</pre> 1713 <p>Note that zero is signed.</p> 1714 <pre> 1715new Decimal(0).valueOf() // '0' 1716new Decimal(0).isNegative() // false 1717new Decimal(0).negated().valueOf() // '-0' 1718new Decimal(0).negated().isNegative() // true 1719new Decimal(-0).isNegative() // true 1720 </pre> 1721 1722 1723 1724 <h5 id="isPos">isPositive<code class='inset'>.isPos() <i>⇒ boolean</i></code></h5> 1725 <p> 1726 Returns <code>true</code> if the value of this Decimal is positive, otherwise returns 1727 <code>false</code>. 1728 </p> 1729 <pre> 1730x = new Decimal(0) 1731x.isPositive() // true 1732y = new Decimal(-2) 1733y.isPos // false</pre> 1734 1735 1736 1737 <h5 id="isZero">isZero<code class='inset'>.isZero() <i>⇒ boolean</i></code></h5> 1738 <p> 1739 Returns <code>true</code> if the value of this Decimal is zero or minus zero, otherwise 1740 returns <code>false</code>. 1741 </p> 1742 <pre> 1743x = new Decimal(-0) 1744x.isZero() && x.isNeg() // true 1745y = new Decimal(Infinity) 1746y.isZero() // false</pre> 1747 1748 1749 1750 <h5 id="lt">lessThan<code class='inset'>.lt(x) <i>⇒ boolean</i></code></h5> 1751 <p><code>x</code>: <i>number|string|Decimal</i></p> 1752 <p> 1753 Returns <code>true</code> if the value of this Decimal is less than the value of 1754 <code>x</code>, otherwise returns <code>false</code>. 1755 </p> 1756 <p>Note: This method uses the <code>cmp</code> method internally.</p> 1757 <pre> 1758(0.3 - 0.2) < 0.1 // true 1759x = new Decimal(0.3).minus(0.2) 1760x.lessThan(0.1) // false 1761new Decimal(0).lt(x) // true</pre> 1762 1763 1764 1765 <h5 id="lte">lessThanOrEqualTo<code class='inset'>.lte(x) <i>⇒ boolean</i></code></h5> 1766 <p><code>x</code>: <i>number|string|Decimal</i></p> 1767 <p> 1768 Returns <code>true</code> if the value of this Decimal is less than or equal to the value of 1769 <code>x</code>, otherwise returns <code>false</code>. 1770 </p> 1771 <p>Note: This method uses the <code>cmp</code> method internally.</p> 1772 <pre> 17730.1 <= (0.3 - 0.2) // false 1774x = new Decimal(0.1) 1775x.lessThanOrEqualTo(Decimal(0.3).minus(0.2)) // true 1776new Decimal(-1).lte(x) // true</pre> 1777 1778 1779 1780 <h5 id="log">logarithm<code class='inset'>.log(x) <i>⇒ Decimal</i></code></h5> 1781 <p><code>x</code>: <i>number|string|Decimal</i></p> 1782 <p> 1783 Returns a new Decimal whose value is the base <code>x</code> logarithm of the value of this 1784 Decimal, rounded to <a href='#precision'><code>precision</code></a> significant digits using 1785 rounding mode <a href='#rounding'><code>rounding</code></a>. 1786 </p> 1787 <p> 1788 If <code>x</code> is omitted, the base 10 logarithm of the value of this Decimal will be 1789 returned. 1790 </p> 1791 <pre> 1792x = new Decimal(1000) 1793x.logarithm() // '3' 1794y = new Decimal(256) 1795y.log(2) // '8'</pre> 1796 <p> 1797 The return value will <i>almost always</i> be correctly rounded, i.e. rounded as if the result 1798 was first calculated to an infinite number of correct digits before rounding. If a result is 1799 incorrectly rounded the maximum error will be <code>1</code> <i>ulp</i> (unit in the last 1800 place). 1801 </p> 1802 <p>Logarithms to base <code>2</code> or <code>10</code> will always be correctly rounded.</p> 1803 <p> 1804 See <a href='#pow'><code>toPower</code></a> for the circumstances in which this method may 1805 return an incorrectly rounded result, and see <a href='#ln'><code>naturalLogarithm</code></a> 1806 for the precision limit. 1807 </p> 1808 <p>The performance of this method degrades exponentially with increasing digits.</p> 1809 1810 1811 1812 <h5 id="sub">minus<code class='inset'>.minus(x) <i>⇒ Decimal</i></code></h5> 1813 <p><code>x</code>: <i>number|string|Decimal</i></p> 1814 <p> 1815 Returns a new Decimal whose value is the value of this Decimal minus <code>x</code>, rounded 1816 to <a href='#precision'><code>precision</code></a> significant digits using rounding mode 1817 <a href='#rounding'><code>rounding</code></a>. 1818 </p> 1819 <pre> 18200.3 - 0.1 // 0.19999999999999998 1821x = new Decimal(0.3) 1822x.minus(0.1) // '0.2'</pre> 1823 1824 1825 1826 <h5 id="mod">modulo<code class='inset'>.mod(x) <i>⇒ Decimal</i></code></h5> 1827 <p><code>x</code>: <i>number|string|Decimal</i></p> 1828 <p> 1829 Returns a new Decimal whose value is the value of this Decimal modulo <code>x</code>, 1830 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1831 mode <a href='#rounding'><code>rounding</code></a>. 1832 </p> 1833 <p> 1834 The value returned, and in particular its sign, is dependent on the value of the 1835 <a href='#modulo'><code>modulo</code></a> property of this Decimal's constructor. If it is 1836 <code>1</code> (default value), the result will have the same sign as this Decimal, and it 1837 will match that of Javascript's <code>%</code> operator (within the limits of double 1838 precision) and BigDecimal's <code>remainder</code> method. 1839 </p> 1840 <p> 1841 See <a href='#modulo'><code>modulo</code></a> for a description of the other modulo modes. 1842 </p> 1843 <pre> 18441 % 0.9 // 0.09999999999999998 1845x = new Decimal(1) 1846x.modulo(0.9) // '0.1' 1847 1848y = new Decimal(8) 1849z = new Decimal(-3) 1850Decimal.modulo = 1 1851y.mod(z) // '2' 1852Decimal.modulo = 3 1853y.mod(z) // '-1'</pre> 1854 1855 1856 1857 <h5 id="exp">naturalExponential<code class='inset'>.exp() <i>⇒ Decimal</i></code></h5> 1858 <p> 1859 Returns a new Decimal whose value is the base <code>e</code> (Euler's number, the base of the 1860 natural logarithm) exponential of the value of this Decimal, rounded to 1861 <a href='#precision'><code>precision</code></a> significant digits using rounding mode 1862 <a href='#rounding'><code>rounding</code></a>. 1863 </p> 1864 <p> 1865 The <code><a href='#ln'>naturalLogarithm</a></code> function is the inverse of this function. 1866 </p> 1867 <pre> 1868x = new Decimal(1) 1869x.naturalExponential() // '2.7182818284590452354' 1870y = new Decimal(2) 1871y.exp() // '7.3890560989306502272'</pre> 1872 <p> 1873 The return value will be correctly rounded, i.e. rounded as if the result was first calculated 1874 to an infinite number of correct digits before rounding. (The mathematical result of the 1875 exponential function is non-terminating, unless its argument is <code>0</code>). 1876 </p> 1877 <p>The performance of this method degrades exponentially with increasing digits.</p> 1878 1879 1880 1881 <h5 id="ln">naturalLogarithm<code class='inset'>.ln() <i>⇒ Decimal</i></code></h5> 1882 <p> 1883 Returns a new Decimal whose value is the natural logarithm of the value of this Decimal, 1884 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1885 mode <a href='#rounding'><code>rounding</code></a>. 1886 </p> 1887 <p> 1888 The natural logarithm is the inverse of the <code><a href='#exp'>naturalExponential</a></code> 1889 function. 1890 </p> 1891 <pre> 1892x = new Decimal(10) 1893x.naturalLogarithm() // '2.3026' 1894y = new Decimal('1.23e+30') 1895y.ln() // '69.28'</pre> 1896 <p> 1897 The return value will be correctly rounded, i.e. rounded as if the result was first calculated 1898 to an infinite number of correct digits before rounding. (The mathematical result of the 1899 natural logarithm function is non-terminating, unless its argument is <code>1</code>). 1900 </p> 1901 <p> 1902 Internally, this method is dependent on a constant whose value is the natural logarithm of 1903 <code>10</code>. This <code>LN10</code> variable in the source code currently has a precision 1904 of <code>1025</code> digits, meaning that this method can accurately calculate up to 1905 <code>1000</code> digits. 1906 </p> 1907 <p> 1908 If more than <code>1000</code> digits is required then the precision of <code>LN10</code> 1909 will need to be increased to <code>25</code> digits more than is required - though, as the 1910 time-taken by this method increases exponentially with increasing digits, it is unlikely to be 1911 viable to calculate over <code>1000</code> digits anyway. 1912 </p> 1913 1914 1915 1916 <h5 id="neg">negated<code class='inset'>.neg() <i>⇒ Decimal</i></code></h5> 1917 <p> 1918 Returns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by 1919 <code>-1</code>. 1920 </p> 1921 <p> 1922 The return value is not affected by the value of the 1923 <a href='#precision'><code>precision</code></a> setting. 1924 </p> 1925 <pre> 1926x = new Decimal(1.8) 1927x.negated() // '-1.8' 1928y = new Decimal(-1.3) 1929y.neg() // '1.3'</pre> 1930 1931 1932 1933 <h5 id="add">plus<code class='inset'>.plus(x) <i>⇒ Decimal</i></code></h5> 1934 <p><code>x</code>: <i>number|string|Decimal</i></p> 1935 <p> 1936 Returns a new Decimal whose value is the value of this Decimal plus <code>x</code>, rounded to 1937 <a href='#precision'><code>precision</code></a> significant digits using rounding mode 1938 <a href='#rounding'><code>rounding</code></a>. 1939 </p> 1940 <pre> 19410.1 + 0.2 // 0.30000000000000004 1942x = new Decimal(0.1) 1943y = x.plus(0.2) // '0.3' 1944new Decimal(0.7).plus(x).plus(y) // '1.1'</pre> 1945 1946 1947 1948 <h5 id="sd">precision<code class='inset'>.sd([include_zeros]) <i>⇒ number</i></code></h5> 1949 <p>Returns the number of significant digits of the value of this Decimal.</p> 1950 <p> 1951 If <code>include_zeros</code> is <code>true</code> or <code>1</code> then any trailing zeros 1952 of the integer part of a number are counted as significant digits, otherwise they are not. 1953 </p> 1954 <pre> 1955x = new Decimal(1.234) 1956x.precision() // '4' 1957y = new Decimal(987000) 1958y.sd() // '3' 1959y.sd(true) // '6'</pre> 1960 1961 1962 1963 <h5 id="round">round<code class='inset'>.round() <i>⇒ Decimal</i></code></h5> 1964 <p> 1965 Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using 1966 rounding mode <a href='#rounding'><code>rounding</code></a>. 1967 </p> 1968 <p> 1969 To emulate <code>Math.round</code>, set <a href='#rounding'><code>rounding</code></a> to 1970 <code>7</code>, i.e. <a href='#modes'><code>ROUND_HALF_CEIL</code></a>. 1971 </p> 1972 <pre> 1973Decimal.set({ rounding: 4 }) 1974x = 1234.5 1975x.round() // '1235' 1976 1977Decimal.rounding = Decimal.ROUND_DOWN 1978x.round() // '1234' 1979x // '1234.5'</pre> 1980 1981 1982 1983 <h5 id="sin">sine<code class='inset'>.sin() <i>⇒ Decimal</i></code></h5> 1984 <p> 1985 Returns a new Decimal whose value is the sine of the value in radians of this Decimal, 1986 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 1987 mode <a href='#rounding'><code>rounding</code></a>. 1988 </p> 1989 <p> 1990 Domain: [<code>-Infinity, Infinity</code>]<br /> 1991 Range: [<code>-1, 1</code>] 1992 </p> 1993 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 1994 <pre> 1995x = new Decimal(0.5) 1996x.sine() // '0.47942553860420300027' 1997y = new Decimal(0.75) 1998y.sin() // '0.68163876002333416673'</pre> 1999 2000 2001 2002 <h5 id="sqrt">squareRoot<code class='inset'>.sqrt() <i>⇒ Decimal</i></code></h5> 2003 <p> 2004 Returns a new Decimal whose value is the square root of this Decimal, rounded to 2005 <a href='#precision'><code>precision</code></a> significant digits using rounding mode 2006 <a href='#rounding'><code>rounding</code></a>. 2007 </p> 2008 <p> 2009 The return value will be correctly rounded, i.e. rounded as if the result was first calculated 2010 to an infinite number of correct digits before rounding. 2011 </p> 2012 <p> 2013 This method is much faster than using the <a href='#pow'><code>toPower</code></a> method with 2014 an exponent of <code>0.5</code>. 2015 </p> 2016 <pre> 2017x = new Decimal(16) 2018x.squareRoot() // '4' 2019y = new Decimal(3) 2020y.sqrt() // '1.73205080756887729353' 2021y.sqrt().eq( y.pow(0.5) ) // true</pre> 2022 2023 2024 2025 <h5 id="tan">tangent<code class='inset'>.tan() <i>⇒ Decimal</i></code></h5> 2026 <p> 2027 Returns a new Decimal whose value is the tangent of the value in radians of this Decimal, 2028 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 2029 mode <a href='#rounding'><code>rounding</code></a>. 2030 </p> 2031 <p> 2032 Domain: [<code>-Infinity, Infinity</code>]<br /> 2033 Range: [<code>-Infinity, Infinity</code>] 2034 </p> 2035 <p>See <a href='#Pi'><code>Pi</code></a> for the precision limit of this method.</p> 2036 <pre> 2037x = new Decimal(0.5) 2038x.tangent() // '0.54630248984379051326' 2039y = new Decimal(0.75) 2040y.tan() // '0.93159645994407246117'</pre> 2041 2042 2043 2044 <h5 id="mul">times<code class='inset'>.times(x) <i>⇒ Decimal</i></code></h5> 2045 <p><code>x</code>: <i>number|string|Decimal</i></p> 2046 <p> 2047 Returns a new Decimal whose value is the value of this Decimal times <code>x</code>, 2048 rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding 2049 mode <a href='#rounding'><code>rounding</code></a>. 2050 </p> 2051 <pre> 20520.6 * 3 // 1.7999999999999998 2053x = new Decimal(0.6) 2054y = x.times(3) // '1.8' 2055new Decimal('7e+500').times(y) // '1.26e+501'</pre> 2056 2057 2058 2059 <h5 id="toBinary"> 2060 toBinary<code class='inset'>.toBinary([sd [, rm]]) <i>⇒ string</i></code> 2061 </h5> 2062 <p> 2063 <code>sd</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2064 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2065 </p> 2066 <p> 2067 Returns a string representing the value of this Decimal in binary, rounded to <code>sd</code> 2068 significant digits using rounding mode <code>rm</code>. 2069 </p> 2070 <p> 2071 If <code>sd</code> is defined, the return value will use binary exponential notation. 2072 </p> 2073 <p> 2074 If <code>sd</code> is omitted, the return value will be rounded to 2075 <a href='#precision'><code>precision</code></a> significant digits. 2076 </p> 2077 <p> 2078 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> 2079 will be used. 2080 </p> 2081 <p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p> 2082 <pre> 2083x = new Decimal(256) 2084x.toBinary() // '0b100000000' 2085x.toBinary(1) // '0b1p+8'</pre> 2086 2087 2088 2089 <h5 id="toDP"> 2090 toDecimalPlaces<code class='inset'>.toDP([dp [, rm]]) <i>⇒ Decimal</i></code> 2091 </h5> 2092 <p> 2093 <code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2094 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive. 2095 </p> 2096 <p> 2097 Returns a new Decimal whose value is the value of this Decimal rounded to <code>dp</code> 2098 decimal places using rounding mode <code>rm</code>. 2099 </p> 2100 <p> 2101 If <code>dp</code> is omitted, the return value will have the same value as this Decimal. 2102 </p> 2103 <p> 2104 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> 2105 is used. 2106 </p> 2107 <p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p> 2108 <pre> 2109x = new Decimal(12.34567) 2110x.toDecimalPlaces(0) // '12' 2111x.toDecimalPlaces(1, Decimal.ROUND_UP) // '12.4' 2112 2113y = new Decimal(9876.54321) 2114y.toDP(3) // '9876.543' 2115y.toDP(1, 0) // '9876.6' 2116y.toDP(1, Decimal.ROUND_DOWN) // '9876.5'</pre> 2117 2118 2119 2120 <h5 id="toExponential"> 2121 toExponential<code class='inset'>.toExponential([dp [, rm]]) <i>⇒ string</i></code> 2122 </h5> 2123 <p> 2124 <code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2125 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2126 </p> 2127 <p> 2128 Returns a string representing the value of this Decimal in exponential notation rounded 2129 using rounding mode <code>rm</code> to <code>dp</code> decimal places, i.e with one digit 2130 before the decimal point and <code>dp</code> digits after it. 2131 </p> 2132 <p> 2133 If the value of this Decimal in exponential notation has fewer than <code>dp</code> fraction 2134 digits, the return value will be appended with zeros accordingly. 2135 </p> 2136 <p> 2137 If <code>dp</code> is omitted, the number of digits after the decimal point defaults to the 2138 minimum number of digits necessary to represent the value exactly. 2139 </p> 2140 <p> 2141 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is 2142 used. 2143 </p> 2144 <p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p> 2145 <pre> 2146x = 45.6 2147y = new Decimal(x) 2148x.toExponential() // '4.56e+1' 2149y.toExponential() // '4.56e+1' 2150x.toExponential(0) // '5e+1' 2151y.toExponential(0) // '5e+1' 2152x.toExponential(1) // '4.6e+1' 2153y.toExponential(1) // '4.6e+1' 2154y.toExponential(1, Decimal.ROUND_DOWN) // '4.5e+1' 2155x.toExponential(3) // '4.560e+1' 2156y.toExponential(3) // '4.560e+1'</pre> 2157 2158 2159 2160 <h5 id="toFixed"> 2161 toFixed<code class='inset'>.toFixed([dp [, rm]]) <i>⇒ string</i></code> 2162 </h5> 2163 <p> 2164 <code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2165 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2166 </p> 2167 <p> 2168 Returns a string representing the value of this Decimal in normal (fixed-point) notation 2169 rounded to <code>dp</code> decimal places using rounding mode <code>rm</code>. 2170 </p> 2171 <p> 2172 If the value of this Decimal in normal notation has fewer than <code>dp</code> fraction 2173 digits, the return value will be appended with zeros accordingly. 2174 </p> 2175 <p> 2176 Unlike <code>Number.prototype.toFixed</code>, which returns exponential notation if a number 2177 is greater or equal to <code>10<sup>21</sup></code>, this method will always return normal 2178 notation. 2179 </p> 2180 <p> 2181 If <code>dp</code> is omitted, the return value will be unrounded and in normal notation. This 2182 is unlike <code>Number.prototype.toFixed</code>, which returns the value to zero decimal 2183 places, but is useful when because of the current 2184 <a href="#toExpNeg"><code>toExpNeg</code></a> or 2185 <a href="#toExpPos"><code>toExpNeg</code></a> values, 2186 <code><a href='#toString'>toString</a></code> returns exponential notation. 2187 </p> 2188 <p> 2189 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is 2190 used. 2191 </p> 2192 <p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p> 2193 <pre> 2194x = 3.456 2195y = new Decimal(x) 2196x.toFixed() // '3' 2197y.toFixed() // '3.456' 2198y.toFixed(0) // '3' 2199x.toFixed(2) // '3.46' 2200y.toFixed(2) // '3.46' 2201y.toFixed(2, Decimal.ROUND_DOWN) // '3.45' 2202x.toFixed(5) // '3.45600' 2203y.toFixed(5) // '3.45600'</pre> 2204 2205 2206 2207 <h5 id="toFraction"> 2208 toFraction 2209 <code class='inset'>.toFraction([max_denominator]) <i>⇒ [Decimal, Decimal]</i></code> 2210 </h5> 2211 <p> 2212 <code>max_denominator</code>: <i>number|string|Decimal</i>: <code>1</code> >= integer < 2213 <code>Infinity</code> 2214 </p> 2215 <p> 2216 Returns an array of two Decimals representing the value of this Decimal as a simple fraction 2217 with an integer numerator and an integer denominator. The denominator will be a positive 2218 non-zero value less than or equal to <code>max_denominator</code>. 2219 </p> 2220 <p> 2221 If a maximum denominator is omitted, the denominator will be the lowest value necessary to 2222 represent the number exactly. 2223 </p> 2224 <p>Throws on an invalid <code>max_denominator</code> value.</p> 2225 <pre> 2226x = new Decimal(1.75) 2227x.toFraction() // '7, 4' 2228 2229pi = new Decimal('3.14159265358') 2230pi.toFraction() // '157079632679,50000000000' 2231pi.toFraction(100000) // '312689, 99532' 2232pi.toFraction(10000) // '355, 113' 2233pi.toFraction(100) // '311, 99' 2234pi.toFraction(10) // '22, 7' 2235pi.toFraction(1) // '3, 1'</pre> 2236 2237 2238 2239 <h5 id="toHex"> 2240 toHexadecimal<code class='inset'>.toHex([sd [, rm]]) <i>⇒ string</i></code> 2241 </h5> 2242 <p> 2243 <code>sd</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2244 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2245 </p> 2246 <p> 2247 Returns a string representing the value of this Decimal in hexadecimal, rounded to 2248 <code>sd</code> significant digits using rounding mode <code>rm</code>. 2249 </p> 2250 <p> 2251 If <code>sd</code> is defined, the return value will use binary exponential notation. 2252 </p> 2253 <p> 2254 If <code>sd</code> is omitted, the return value will be rounded to 2255 <a href='#precision'><code>precision</code></a> significant digits. 2256 </p> 2257 <p> 2258 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> 2259 will be used. 2260 </p> 2261 <p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p> 2262 <pre> 2263x = new Decimal(256) 2264x.toHexadecimal() // '0x100' 2265x.toHex(1) // '0x1p+8'</pre> 2266 2267 2268 2269 <h5 id="toJSON">toJSON<code class='inset'>.toJSON() <i>⇒ string</i></code></h5> 2270 <p>As <a href='#valueOf'><code>valueOf</code></a>.</p> 2271 2272 2273 2274 <h5 id="toNearest"> 2275 toNearest<code class='inset'>.toNearest(x [, rm]) <i>⇒ Decimal</i></code> 2276 </h5> 2277 <p> 2278 <code>x</code>: <i>number|string|Decimal</i><br /> 2279 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2280 </p> 2281 <p> 2282 Returns a new Decimal whose value is the nearest multiple of <code>x</code> in the direction 2283 of rounding mode <code>rm</code>, or <a href='#rounding'><code>rounding</code></a> if 2284 <code>rm</code> is omitted, to the value of this Decimal. 2285 </p> 2286 <p> 2287 The return value will always have the same sign as this Decimal, unless either this Decimal 2288 or <code>x</code> is <code>NaN</code>, in which case the return value will be also be 2289 <code>NaN</code>. 2290 </p> 2291 <p> 2292 The return value is not affected by the value of the 2293 <a href='#precision'><code>precision</code></a> setting. 2294 </p> 2295 <pre> 2296x = new Decimal(1.39) 2297x.toNearest(0.25) // '1.5' 2298 2299y = new Decimal(9.499) 2300y.toNearest(0.5, Decimal.ROUND_UP) // '9.5' 2301y.toNearest(0.5, Decimal.ROUND_DOWN) // '9'</pre> 2302 2303 2304 2305 <h5 id="toNumber">toNumber<code class='inset'>.toNumber() <i>⇒ number</i></code></h5> 2306 <p>Returns the value of this Decimal converted to a primitive number.</p> 2307 <p> 2308 Type coercion with, for example, JavaScript's unary plus operator will also work, except that 2309 a Decimal with the value minus zero will convert to positive zero. 2310 </p> 2311 <pre> 2312x = new Decimal(456.789) 2313x.toNumber() // 456.789 2314+x // 456.789 2315 2316y = new Decimal('45987349857634085409857349856430985') 2317y.toNumber() // 4.598734985763409e+34 2318 2319z = new Decimal(-0) 23201 / +z // Infinity 23211 / z.toNumber() // -Infinity</pre> 2322 2323 2324 2325 <h5 id="toOctal"> 2326 toOctal<code class='inset'>.toOctal([sd [, rm]]) <i>⇒ string</i></code> 2327 </h5> 2328 <p> 2329 <code>sd</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br /> 2330 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2331 </p> 2332 <p> 2333 Returns a string representing the value of this Decimal in octal, rounded to <code>sd</code> 2334 significant digits using rounding mode <code>rm</code>. 2335 </p> 2336 <p> 2337 If <code>sd</code> is defined, the return value will use binary exponential notation. 2338 </p> 2339 <p> 2340 If <code>sd</code> is omitted, the return value will be rounded to 2341 <a href='#precision'><code>precision</code></a> significant digits. 2342 </p> 2343 <p> 2344 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> 2345 will be used. 2346 </p> 2347 <p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p> 2348 <pre> 2349x = new Decimal(256) 2350x.toOctal() // '0o400' 2351x.toOctal(1) // '0o1p+8'</pre> 2352 2353 2354 2355 <h5 id="pow">toPower<code class='inset'>.pow(x) <i>⇒ Decimal</i></code></h5> 2356 <p><code>x</code>: <i>number|string|Decimal</i>: integer or non-integer</p> 2357 <p> 2358 Returns a new Decimal whose value is the value of this Decimal raised to the power 2359 <code>x</code>, rounded to <a href='#precision'><code>precision</code></a> significant digits 2360 using rounding mode <a href='#rounding'><code>rounding</code></a>. 2361 </p> 2362 <p> 2363 The performance of this method degrades exponentially with increasing digits. For 2364 non-integer exponents in particular, the performance of this method may not be adequate. 2365 </p> 2366 <pre> 2367Math.pow(0.7, 2) // 0.48999999999999994 2368x = new Decimal(0.7) 2369x.toPower(2) // '0.49' 2370new Decimal(3).pow(-2) // '0.11111111111111111111' 2371 2372new Decimal(1217652.23).pow('98765.489305603941') 2373// '4.8227010515242461181e+601039'</pre> 2374 <p><i>Is the pow function guaranteed to be correctly rounded?</i></p> 2375 <p> 2376 The return value will <i>almost always</i> be correctly rounded, i.e. rounded as if the result 2377 was first calculated to an infinite number of correct digits before rounding. If a result is 2378 incorrectly rounded the maximum error will be <code>1</code> <i>ulp</i> (unit in the last 2379 place). 2380 </p> 2381 <p>For non-integer and larger exponents this method uses the formula</p> 2382 <blockquote><code>x<sup>y</sup> = exp(y*ln(x))</code></blockquote> 2383 <p> 2384 As the mathematical return values of the <a href='#exp'><code>exp</code></a> and 2385 <a href='#ln'><code>ln</code></a> functions are both non-terminating (excluding arguments of 2386 <code>0</code> or <code>1</code>), the values of the Decimals returned by the functions as 2387 implemented by this library will necessarily be rounded approximations, which means that there 2388 can be no guarantee of correct rounding when they are combined in the above formula. 2389 </p> 2390 <p> 2391 The return value may, depending on the rounding mode, be incorrectly rounded only if the first 2392 <code>15</code> rounding digits are <code>15</code> zeros (and there are non-zero digits 2393 following at some point), or <code>15</code> nines, or a <code>5</code> or <code>4</code> 2394 followed by <code>14</code> nines. 2395 </p> 2396 <p> 2397 Therefore, assuming the first <code>15</code> rounding digits are each equally likely to be 2398 any digit, <code>0-9</code>, the probability of an incorrectly rounded result is less than 2399 <code>1</code> in <code>250,000,000,000,000</code>. 2400 </p> 2401 <p> 2402 An example of incorrect rounding: 2403 </p> 2404 <pre> 2405Decimal.set({ precision: 20, rounding: 1 }) 2406new Decimal(28).pow('6.166675020000903537297764507632802193308677149') 2407// 839756321.64088511</pre> 2408 <p>As the exact mathematical result begins</p> 2409 <pre>839756321.6408851099999999999999999999999999998969466049426031167...</pre> 2410 <p> 2411 and the rounding mode is set to <code><a href='#modes'>ROUND_DOWN</a></code>, the correct 2412 return value should be 2413 </p> 2414 <pre>839756321.64088510999</pre> 2415 2416 2417 2418 <h5 id="toPrecision"> 2419 toPrecision<code class='inset'>.toPrecision([sd [, rm]]) <i>⇒ string</i></code> 2420 </h5> 2421 <p> 2422 <code>sd</code>: <i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br /> 2423 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive 2424 </p> 2425 <p> 2426 Returns a string representing the value of this Decimal rounded to <code>sd</code> significant 2427 digits using rounding mode <code>rm</code>. 2428 </p> 2429 <p> 2430 If <code>sd</code> is less than the number of digits necessary to represent the integer part 2431 of the value in normal (fixed-point) notation, then exponential notation is used. 2432 </p> 2433 <p> 2434 If <code>sd</code> is omitted, the return value is the same as 2435 <code><a href='#toString'>toString</a></code>. 2436 </p> 2437 <p> 2438 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is 2439 used. 2440 </p> 2441 <p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p> 2442 <pre> 2443x = 45.6 2444y = new Decimal(x) 2445x.toPrecision() // '45.6' 2446y.toPrecision() // '45.6' 2447x.toPrecision(1) // '5e+1' 2448y.toPrecision(1) // '5e+1' 2449y.toPrecision(2, Decimal.ROUND_UP) // '46' 2450y.toPrecision(2, Decimal.ROUND_DOWN) // '45' 2451x.toPrecision(5) // '45.600' 2452y.toPrecision(5) // '45.600'</pre> 2453 2454 2455 2456 <h5 id="toSD"> 2457 toSignificantDigits<code class='inset'>.toSD([sd [, rm]]) <i>⇒ Decimal</i></code> 2458 </h5> 2459 <p> 2460 <code>sd</code>: <i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive.<br /> 2461 <code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive. 2462 </p> 2463 <p> 2464 Returns a new Decimal whose value is the value of this Decimal rounded to <code>sd</code> 2465 significant digits using rounding mode <code>rm</code>. 2466 </p> 2467 <p> 2468 If <code>sd</code> is omitted, the return value will be rounded to 2469 <a href='#precision'><code>precision</code></a> significant digits. 2470 </p> 2471 <p> 2472 If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> 2473 will be used. 2474 </p> 2475 <p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p> 2476 <pre> 2477Decimal.set({ precision: 5, rounding: 4 }) 2478x = new Decimal(9876.54321) 2479 2480x.toSignificantDigits() // '9876.5' 2481x.toSignificantDigits(6) // '9876.54' 2482x.toSignificantDigits(6, Decimal.ROUND_UP) // '9876.55' 2483x.toSD(2) // '9900' 2484x.toSD(2, 1) // '9800' 2485x // '9876.54321'</pre> 2486 2487 2488 2489 <h5 id="toString">toString<code class='inset'>.toString() <i>⇒ string</i></code></h5> 2490 <p>Returns a string representing the value of this Decimal.</p> 2491 <p> 2492 If this Decimal has a positive exponent that is equal to or greater than 2493 <a href="#toExpPos"><code>toExpPos</code></a>, or a negative exponent equal to or less than 2494 <a href="#toExpPos"><code>toExpNeg</code></a>, then exponential notation will be returned. 2495 </p> 2496 <pre> 2497x = new Decimal(750000) 2498x.toString() // '750000' 2499Decimal.set({ toExpPos: 5 }) 2500x.toString() // '7.5e+5' 2501 2502Decimal.set({ precision: 4 }) 2503y = new Decimal('1.23456789') 2504y.toString() // '1.23456789'</pre> 2505 2506 2507 2508 <h5 id="trunc">truncated<code class='inset'>.trunc() <i>⇒ Decimal</i></code></h5> 2509 <p> 2510 Returns a new Decimal whose value is the value of this Decimal truncated to a whole number. 2511 </p> 2512 <p> 2513 The return value is not affected by the value of the 2514 <a href='#precision'><code>precision</code></a> setting. 2515 </p> 2516 <pre> 2517x = new Decimal(123.456) 2518x.truncated() // '123' 2519y = new Decimal(-12.3) 2520y.trunc() // '-12'</pre> 2521 2522 2523 2524 <h5 id="valueOf">valueOf<code class='inset'>.valueOf() <i>⇒ string</i></code></h5> 2525 <p>As <a href='#toString'><code>toString</code></a>, but zero is signed.</p> 2526 <pre> 2527x = new Decimal(-0) 2528x.valueOf() // '-0'</pre> 2529 2530 2531 2532 2533 2534 2535 <h4 id="instance-properties">Properties</h4> 2536 <p> 2537 The value of a Decimal is stored in a normalised base <code>10000000</code> floating point 2538 format. 2539 </p> 2540 <p> 2541 A Decimal instance is an object with three properties: 2542 </p> 2543 <table> 2544 <tr> 2545 <th>Property</th> 2546 <th>Description</th> 2547 <th>Type</th> 2548 <th>Value</th> 2549 </tr> 2550 <tr> 2551 <td class='centre' id='digits'><b>d</b></td> 2552 <td>digits</td> 2553 <td><i>number</i><code style='color:#000'>[]</code></td> 2554 <td> Array of integers, each <code>0</code> - <code>1e7</code>, or <code>null</code></td> 2555 </tr> 2556 <tr> 2557 <td class='centre' id='exponent'><b>e</b></td> 2558 <td>exponent</td> 2559 <td><i>number</i></td> 2560 <td>Integer, <code>-9e15</code> to <code>9e15</code> inclusive, or <code>NaN</code></td> 2561 </tr> 2562 <tr> 2563 <td class='centre' id='sign'><b>s</b></td> 2564 <td>sign</td> 2565 <td><i>number</i></td> 2566 <td><code>-1</code>, <code>1</code>, or <code>NaN</code></td> 2567 </tr> 2568 </table> 2569 <p>All the properties are best considered to be read-only.</p> 2570 <p> 2571 As with JavaScript numbers, the original exponent and fractional trailing zeros of a value 2572 are not preserved. 2573 </p> 2574 <pre> 2575x = new Decimal(0.123) // '0.123' 2576x.toExponential() // '1.23e-1' 2577x.d // [ 1230000 ] 2578x.e // -1 2579x.s // 1 2580 2581y = new Number(-123.4567000e+2) // '-12345.67' 2582y.toExponential() // '-1.234567e+4' 2583z = new Decimal('-123.4567000e+2') // '-12345.67' 2584z.toExponential() // '-1.234567e+4' 2585z.d // [ 12345, 6700000 ] 2586z.e // 4 2587z.s // -1</pre> 2588 2589 2590 2591 <h4 id="zero-nan-infinity">Zero, NaN and Infinity</h4> 2592 <p> 2593 The table below shows how <code>±0</code>, <code>NaN</code> and 2594 <code>±Infinity</code> are stored. 2595 </p> 2596 <table> 2597 <tr> 2598 <th> </th> 2599 <th>±0</th> 2600 <th>NaN</th> 2601 <th>±Infinity</th> 2602 </tr> 2603 <tr> 2604 <td><b> d </b></td> 2605 <td><code>[0]</code></td> 2606 <td><code>null</code></td> 2607 <td><code>null</code></td> 2608 </tr> 2609 <tr> 2610 <td><b> e </b></td> 2611 <td><code>0</code></td> 2612 <td><code>NaN</code></td> 2613 <td><code>NaN</code></td> 2614 </tr> 2615 <tr> 2616 <td><b> s </b></td> 2617 <td><code>±1</code></td> 2618 <td><code>NaN</code></td> 2619 <td><code>±1</code></td> 2620 </tr> 2621 </table> 2622 <pre> 2623x = new Number(-0) // 0 26241 / x == -Infinity // true 2625 2626y = new Decimal(-0) 2627y.d // '0' ( [0].toString() ) 2628y.e // 0 2629y.s // -1 2630y.toString() // '0' 2631y.valueOf() // '-0'</pre> 2632 2633 2634 2635 <h4 id='Errors'>Errors</h4> 2636 <p> 2637 The errors that are thrown are generic <code>Error</code> objects whose <code>message</code> 2638 property begins with <code>"[DecimalError]"</code>. 2639 </p> 2640 <p>To determine if an exception is a Decimal Error:</p> 2641 <pre> 2642try { 2643 // ... 2644} catch (e) { 2645 if ( e instanceof Error && /DecimalError/.test(e.message) ) { 2646 // ... 2647 } 2648}</pre> 2649 2650 2651 2652 <h4 id='Pi'>Pi</h4> 2653 <p> 2654 The maximum precision of the trigonometric methods is dependent on the internal value of the 2655 constant pi, which is defined as the string <code>PI</code> near the top of the source file. 2656 </p> 2657 <p> 2658 It has a precision of <code>1025</code> digits, meaning that the trigonometric methods 2659 can calculate up to just over <code>1000</code> digits, but the actual figure depends on the 2660 precision of the argument passed to them. To calculate the actual figure use: 2661 </p> 2662 <p><b>maximum_result_precision = 1000 - argument_precision</b></p> 2663 For example, the following both work fine: 2664 <pre> 2665Decimal.set({precision: 991}).tan(123456789) 2666Decimal.set({precision: 9}).tan(991_digit_number)</pre> 2667 <p> 2668 as, for each, the result precision plus the argument precision, i.e. <code>991 + 9</code> and 2669 <code>9 + 991</code>, is less than or equal to <code>1000</code>. 2670 </p> 2671 <p> 2672 If greater precision is required then the value of <code>PI</code> will need to be extended to 2673 about <code>25</code> digits more than the precision required. The time taken by the methods 2674 will then be the limiting factor. 2675 </p> 2676 <p> 2677 The value can also be shortened to reduce the size of the source file if such high precision 2678 is not required. 2679 </p> 2680 <p>To get the value of pi:</p> 2681 <pre> 2682pi = Decimal.acos(-1)</pre> 2683 2684 2685 2686 <h2 id='faq'>FAQ</h2> 2687 <h6>Why are trailing fractional zeros removed from Decimals?</h6> 2688 <p> 2689 Some arbitrary-precision libraries retain trailing fractional zeros as they can indicate the 2690 precision of a value. This can be useful but the results of arithmetic operations can be 2691 misleading. 2692 </p> 2693 <pre> 2694x = new BigDecimal("1.0") 2695y = new BigDecimal("1.1000") 2696z = x.add(y) // 2.1000 2697 2698x = new BigDecimal("1.20") 2699y = new BigDecimal("3.45000") 2700z = x.multiply(y) // 4.1400000</pre> 2701 <p> 2702 To specify the precision of a value is to specify that the value lies 2703 within a certain range. 2704 </p> 2705 <p> 2706 In the first example, <code>x</code> has a value of <code>1.0</code>. The trailing zero shows 2707 the precision of the value, implying that it is in the range <code>0.95</code> to 2708 <code>1.05</code>. Similarly, the precision indicated by the trailing zeros of <code>y</code> 2709 indicates that the value is in the range <code>1.09995</code> to <code>1.10005</code>. 2710 </p> 2711 <p> 2712 If we add the two lowest values in the ranges we have, <code>0.95 + 1.09995 = 2.04995</code>, 2713 and if we add the two highest values we have, <code>1.05 + 1.10005 = 2.15005</code>, so the 2714 range of the result of the addition implied by the precision of its operands is 2715 <code>2.04995</code> to <code>2.15005</code>. 2716 </p> 2717 <p> 2718 The result given by BigDecimal of <code>2.1000</code> however, indicates that the value is in 2719 the range <code>2.09995</code> to <code>2.10005</code> and therefore the precision implied by 2720 its trailing zeros may be misleading. 2721 </p> 2722 <p> 2723 In the second example, the true range is <code>4.122744</code> to <code>4.157256</code> yet 2724 the BigDecimal answer of <code>4.1400000</code> indicates a range of <code>4.13999995</code> 2725 to <code>4.14000005</code>. Again, the precision implied by the trailing zeros may be 2726 misleading. 2727 </p> 2728 <p> 2729 This library, like binary floating point and most calculators, does not retain trailing 2730 fractional zeros. Instead, the <code>toExponential</code>, <code>toFixed</code> and 2731 <code>toPrecision</code> methods enable trailing zeros to be added if and when required.<br /> 2732 </p> 2733 </div> 2734 2735</body> 2736</html> 2737