Context Navigation

source: node_modules/decimal.js-light/doc/API.html

Last change on this file was a762898, checked in by istevanoska <ilinastevanoska@…>, 5 months ago
Added visualizations
Property mode set to `100644`
File size: 49.4 KB

Rev	Line
[a762898]	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-light API</title>
	8	<style>
	9	html{font-size:100%}
	10	body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;
	11	line-height:1.65em;min-height:100%;margin:0}
	12	body,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}
	15	div.container{width:600px;margin:50px 0 50px 240px}
	16	p{margin:0 0 1em;width:600px}
	17	pre,ul{margin:1em 0}
	18	h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}
	19	h1,h2{padding:.75em 0}
	20	h1{font:400 3em Consolas, monaco, monospace;color:#000;margin-bottom:1em}
	21	h2{font-size:2.25em;color:#f00}
	22	h3{font-size:1.75em;color:#69d2e7}
	23	h4{font-size:1.75em;color:#f00;padding-bottom:.75em}
	24	h5{font-size:1.2em;margin-bottom:.4em}
	25	h6{font-size:1.1em;margin-bottom:0.8em;padding:0.5em 0}
	26	dd dt{font-size:1.2em}
	27	dt{padding-top:.5em}
	28	dd{padding-top:.35em}
	29	b{font-weight:700}
	30	a,a:visited{color:#f00;text-decoration:none}
	31	a: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}
	34	ul{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}
	41	table{border-collapse:collapse;border-spacing:0;border:2px solid #a7dbd8;margin:1.75em 0;padding:0}
	42	td,th{text-align:left;margin:0;padding:2px 5px;border:1px dotted #a7dbd8}
	43	th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#f00}
	44	code,pre{font-family:Consolas, monaco, monospace;font-weight:400}
	45	pre{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}
	47	code,.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}
	53	li 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">Decimal</a></li></ul>
	65
	66	<a href="#methods">Methods</a>
	67	<ul>
	68	<li><a href="#Dclone" >clone</a></li>
	69	<li><a href="#Dconfig">config</a></li>
	70	</ul>
	71
	72	<a href="#constructor-properties">Properties</a>
	73	<ul>
	74	<li><a href="#precision">precision</a></li>
	75	<li><a href="#rounding" >rounding</a></li>
	76	<li><a href="#toExpNeg" >toExpNeg</a></li>
	77	<li><a href="#toExpPos" >toExpPos</a></li>
	78	<li><a href="#ln10" >LN10</a></li>
	79	<li class='spacer'> </li>
	80	<li><a href="#modes">ROUND_UP</a></li>
	81	<li><a href="#modes">ROUND_DOWN</a></li>
	82	<li><a href="#modes">ROUND_CEIL</a></li>
	83	<li><a href="#modes">ROUND_FLOOR</a></li>
	84	<li><a href="#modes">ROUND_HALF_UP</a></li>
	85	<li><a href="#modes">ROUND_HALF_DOWN</a></li>
	86	<li><a href="#modes">ROUND_HALF_EVEN</a></li>
	87	<li><a href="#modes">ROUND_HALF_CEIL</a></li>
	88	<li><a href="#modes">ROUND_HALF_FLOOR</a></li>
	89	<li><a href="#modes">EUCLID</a></li>
	90	</ul>
	91
	92	<b> INSTANCE </b>
	93
	94	<a href="#prototype-methods">Methods</a>
	95	<ul>
	96	<li><a href="#abs" >absoluteValue </a><span>abs</span> </li>
	97	<li><a href="#cmp" >comparedTo </a><span>cmp</span> </li>
	98	<li><a href="#dp" >decimalPlaces </a><span>dp</span> </li>
	99	<li><a href="#div" >dividedBy </a><span>div</span> </li>
	100	<li><a href="#idiv" >dividedToIntegerBy </a><span>idiv</span> </li>
	101	<li><a href="#eq" >equals </a><span>eq</span> </li>
	102	<li><a href="#exp" >exponent </a> </li>
	103	<li><a href="#gt" >greaterThan </a><span>gt</span> </li>
	104	<li><a href="#gte" >greaterThanOrEqualTo </a><span>gte</span> </li>
	105	<li><a href="#isint" >isInteger </a><span>isint</span></li>
	106	<li><a href="#isneg" >isNegative </a><span>isneg</span></li>
	107	<li><a href="#ispos" >isPositive </a><span>ispos</span></li>
	108	<li><a href="#isZero" >isZero </a> </li>
	109	<li><a href="#lt" >lessThan </a><span>lt</span> </li>
	110	<li><a href="#lte" >lessThanOrEqualTo </a><span>lte</span> </li>
	111	<li><a href="#log" >logarithm </a><span>log</span> </li>
	112	<li><a href="#sub" >minus </a><span>sub</span> </li>
	113	<li><a href="#mod" >modulo </a><span>mod</span> </li>
	114	<li><a href="#exp" >naturalExponential </a><span>exp</span> </li>
	115	<li><a href="#ln" >naturalLogarithm </a><span>ln</span> </li>
	116	<li><a href="#neg" >negated </a><span>neg</span> </li>
	117	<li><a href="#add" >plus </a><span>add</span> </li>
	118	<li><a href="#sd" >precision </a><span>sd</span> </li>
	119	<li><a href="#sqrt" >squareRoot </a><span>sqrt</span> </li>
	120	<li><a href="#mul" >times </a><span>mul</span> </li>
	121	<li><a href="#todp" >toDecimalPlaces </a><span>todp</span> </li>
	122	<li><a href="#toExponential">toExponential </a> </li>
	123	<li><a href="#toFixed" >toFixed </a> </li>
	124	<li><a href="#toInteger" >toInteger </a><span>toint</span></li>
	125	<li><a href="#toJSON" >toJSON </a> </li>
	126	<li><a href="#toNumber" >toNumber </a> </li>
	127	<li><a href="#pow" >toPower </a><span>pow</span> </li>
	128	<li><a href="#toPrecision" >toPrecision </a> </li>
	129	<li><a href="#tosd" >toSignificantDigits </a><span>tosd</span> </li>
	130	<li><a href="#toString" >toString </a> </li>
	131	<li><a href="#valueOf" >valueOf </a><span>val</span> </li>
	132	</ul>
	133
	134	<a href="#instance-properties">Properties</a>
	135	<ul>
	136	<li><a href="#digits" >d</a><span>digits</span></li>
	137	<li><a href="#exponent">e</a><span>exponent</span></li>
	138	<li><a href="#sign" >s</a><span>sign</span></li>
	139	</ul>
	140
	141	<a href="#Errors">Errors</a>
	142	<a class='end' href="#faq">FAQ</a>
	143
	144	</div>
	145
	146	<div class="container">
	147
	148	<h1>decimal<span id='js'>.js</span>-light</h1>
	149
	150	<p>
	151	The light version of <a href='https://github.com/MikeMcl/decimal.js/'>decimal.js</a>, an
	152	arbitrary-precision Decimal type for JavaScript.
	153	</p>
	154	<p><a href='https://github.com/MikeMcl/decimal.js-light'>Hosted on GitHub</a>.</p>
	155
	156	<h2>API</h2>
	157
	158	<p>
	159	See the <a href='https://github.com/MikeMcl/decimal.js'>README</a> on GitHub for a quick-start
	160	introduction.
	161	</p>
	162	<p>
	163	In all examples below, <code>var</code> and semicolons are not shown, and if a commented-out
	164	value is in quotes it means <code>toString</code> has been called on the preceding expression.
	165	</p><br />
	166	<p>
	167	When the library is loaded, it defines a single function object,
	168	<a href='#decimal'><code>Decimal</code></a>, the constructor of Decimal instances.
	169	</p>
	170	<p>
	171	<i>
	172	If necessary, multiple Decimal constructors can be created, each with their own independent
	173	configuration, e.g. precision and range, which applies to all Decimal instances created from
	174	it.
	175	</i>
	176	</p>
	177	<p>
	178	<i>
	179	A new Decimal constructor is created by calling the <code><a href='#Dclone'>clone</a></code>
	180	method of an already existing Decimal constructor.
	181	</i>
	182	</p>
	183
	184
	185
	186	<h3 class='end'>CONSTRUCTOR</h3>
	187
	188	<h5 id="decimal">
	189	Decimal<code class='inset'>Decimal(value) <i>⇒ Decimal</i></code>
	190	</h5>
	191	<dl>
	192	<dt><code>value</code>: <i>number\|string\|Decimal</i></dt>
	193	<dd>
	194	Integer or float.
	195	</dd>
	196	<dd>
	197	The number of digits is not limited, except by JavaScript's maximum array size and, in
	198	practice, the processing time required.
	199	</dd>
	200	<dd>
	201	The maximum permissible exponent magnitude is approximately <code>9007199254740991</code>.
	202	</dd>
	203	<dd>
	204	String values may be in exponential (floating-point), as well as normal (fixed-point)
	205	notation.
	206	</dd>
	207	<dd>
	208	In exponential notation, <code>e</code> or <code>E</code> defines a power-of-ten exponent.
	209	</dd>
	210	</dl>
	211	<p>Returns a new Decimal object instance.</p>
	212	<p>Throws on an invalid <code>value</code>.</p>
	213	<pre>
	214	x = new Decimal(9) // '9'
	215	y = new Decimal(x) // '9'
	216
	217	new Decimal('5032485723458348569331745.33434346346912144534543')
	218	new Decimal('4.321e+4') // '43210'
	219	new Decimal('-735.0918e-430') // '-7.350918e-428'
	220	new Decimal('5.6700000') // '5.67'
	221	new Decimal('.5') // '0.5'
	222
	223	new Decimal(0.046875) // '0.046875'
	224	new Decimal('0.046875000000') // '0.046875'
	225
	226	new Decimal(4.6875e-2) // '0.046875'
	227	new Decimal('468.75e-4') // '0.046875'</pre>
	228
	229
	230
	231	<h4 id="methods">Methods</h4>
	232	<p>The methods of a Decimal constructor.</p>
	233
	234
	235
	236	<h5 id="Dclone">
	237	clone
	238	<code class='inset'>.clone([object]) <i>⇒ Decimal constructor</i></code>
	239	</h5>
	240	<p><code>object</code>: <i>object</i></p>
	241	<p>
	242	Returns a new independent Decimal constructor with configuration settings as described by
	243	<code>object</code> (see <a href='#Dconfig'><code>config</code></a>), or with the same
	244	settings as <code>this</code> Decimal constructor if <code>object</code> is omitted.
	245	</p>
	246	<pre>Decimal.config({ precision: 5 })
	247	D9 = Decimal.clone({ precision: 9 })
	248
	249	a = new Decimal(1)
	250	b = new D9(1)
	251
	252	a.div(3) // 0.33333
	253	b.div(3) // 0.333333333
	254
	255	// D9 = Decimal.clone({ precision: 9 }) is equivalent to:
	256	D9 = Decimal.clone()
	257	D9.config({ precision: 9 })</pre>
	258	<p>
	259	It is not inefficient in terms of memory usage to use multiple Decimal constructors as
	260	functions are shared between them.
	261	</p>
	262
	263
	264
	265	<h5 id="Dconfig">
	266	config<code class='inset'>.set(object) <i>⇒ Decimal constructor</i></code>
	267	</h5>
	268	<p><code>object</code>: <i>object</i></p>
	269	<p>
	270	Configures the 'global' settings for <code>this</code> particular Decimal constructor, i.e.
	271	the settings which apply to operations performed on the Decimal instances created by it.
	272	</p>
	273	<p>Returns <code>this</code> Decimal constructor.</p>
	274	<p>
	275	The configuration object, <code>object</code>, can contain some or all of the properties
	276	described in detail at <a href="#constructor-properties">Properties</a> and shown in the
	277	example below.
	278	</p>
	279	<p>
	280	The values of the configuration object properties are checked for validity and then stored as
	281	equivalently-named properties of <code>this</code> Decimal constructor.
	282	</p>
	283	<p>Throws on an invalid <code>object</code> or configuration property value.</p>
	284	<pre>
	285	// Defaults
	286	Decimal.config({
	287	precision: 20,
	288	rounding: 4,
	289	toExpNeg: -7,
	290	toExpPos: 21,
	291	LN10: new Decimal('2.30258509299404568401799145468436...')
	292	})
	293
	294	Decimal.set({ rounding: Decimal.ROUND_CEIL })
	295	</pre>
	296	<p>
	297	The properties of a Decimal constructor can also be set by direct assignment, but that will
	298	by-pass the validity checking that this method performs - which is not a problem if the user
	299	knows that the checks are unnecessary.
	300	</p>
	301
	302
	303
	304	<h4 id="constructor-properties">Properties</h4>
	305	<p>The properties of a Decimal constructor.</p>
	306
	307
	308
	309	<h6 id='configProps'>Configuration properties</h6>
	310	<p>
	311	The values of the configuration properties <a href='#precision'><code>precision</code></a>,
	312	<a href='#rounding'><code>rounding</code></a>, <a href='#toExpNeg'><code>toExpNeg</code></a>
	313	and <a href='#toExpPos'><code>toExpPos</code></a> are set using the
	314	<a href='#Dconfig'><code>config</code></a> method.
	315	</p>
	316	<p>
	317	As simple object properties they can be set directly without using
	318	<a href='#Dconfig'><code>config</code></a>, and it is fine to do so, but the values assigned
	319	will not then be checked for validity. For example:
	320	</p>
	321	<pre>Decimal.config({ precision: 0 })
	322	// '[DecimalError] Invalid argument: precision: 0'
	323
	324	Decimal.precision = 0
	325	// No error is thrown and the results of calculations are unreliable</pre>
	326
	327
	328
	329	<h5 id="precision">precision</h5>
	330	<p>
	331	<i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br />
	332	Default value: <code>20</code>
	333	</p>
	334	<p>The <i>maximum</i> number of significant digits of the result of an operation.</p>
	335	<p>
	336	All functions which return a Decimal will return the value to <code>precision</code>
	337	significant digits except <a href='#decimal'><code>Decimal</code></a>,
	338	<a href='#abs'><code>absoluteValue</code></a>,
	339	<a href='#neg'><code>negated</code></a>, <a href='#round'><code>toInteger</code></a>, and
	340	<a href='#todp'><code>toDecimalPlaces</code></a>.
	341	</p>
	342	<pre>Decimal.config({ precision: 5 })
	343	Decimal.precision // 5</pre>
	344
	345
	346
	347	<h5 id="rounding">rounding</h5>
	348	<p>
	349	<i>number</i>: integer, <code>0</code> to <code>8</code> inclusive<br />
	350	Default value: <code>4</code> <a href="#modes">(<code>ROUND_HALF_UP</code>)</a>
	351	</p>
	352	<p>
	353	The default rounding mode used by <a href='#round'><code>toInteger</code></a>,
	354	<a href='#todp'><code>toDecimalPlaces</code></a>,
	355	<a href='#toExponential'><code>toExponential</code></a>,
	356	<a href='#toFixed'><code>toFixed</code></a>,
	357	<a href='#toPrecision'><code>toPrecision</code></a> and
	358	<a href='#tosd'><code>toSignificantDigits</code></a>.
	359	</p>
	360	<p>
	361	The <a href='#modes'>rounding modes</a> are available as enumerated properties of the
	362	constructor.
	363	</p>
	364	<pre>Decimal.config({ rounding: Decimal.ROUND_UP })
	365	Decimal.config({ rounding: 0 }) // equivalent
	366	Decimal.rounding // 0</pre>
	367
	368
	369
	370	<h5 id="toExpNeg">toExpNeg</h5>
	371	<p>
	372	<i>number</i>: integer, <code>-9e15</code> to <code>0</code> inclusive<br />
	373	Default value: <code>-7</code>
	374	</p>
	375	<p>
	376	The negative exponent value at and below which <a href='#toString'><code>toString</code></a>
	377	returns exponential notation.
	378	</p>
	379	<pre>Decimal.config({ toExpNeg: -7 })
	380	Decimal.toExpNeg // -7
	381	new Decimal(0.00000123) // '0.00000123' e is -6
	382	new Decimal(0.000000123) // '1.23e-7'
	383
	384	// Always return exponential notation:
	385	Decimal.config({ toExpNeg: 0 })</pre>
	386	<p>
	387	JavaScript numbers use exponential notation for negative exponents of <code>-7</code> and
	388	below.
	389	</p>
	390	<p>
	391	Regardless of the value of <code>toExpNeg</code>, the
	392	<a href='#toFixed'><code>toFixed</code></a> method will always return a value in normal
	393	notation and the <a href='#toExponential'><code>toExponential</code></a> method will always
	394	return a value in exponential form.
	395	</p>
	396
	397
	398
	399	<h5 id="toExpPos">toExpPos</h5>
	400	<p>
	401	<i>number</i>: integer, <code>0</code> to <code>9e15</code> inclusive<br />
	402	Default value: <code>20</code>
	403	</p>
	404	<p>
	405	The positive exponent value at and above which <a href='#toString'><code>toString</code></a>
	406	returns exponential notation.
	407	</p>
	408	<pre>Decimal.config({ toExpPos: 2 })
	409	Decimal.toExpPos // 2
	410	new Decimal(12.3) // '12.3' e is 1
	411	new Decimal(123) // '1.23e+2'
	412
	413	// Always return exponential notation:
	414	Decimal.config({ toExpPos: 0 })</pre>
	415	<p>
	416	JavaScript numbers use exponential notation for positive exponents of <code>20</code> and
	417	above.
	418	</p>
	419	<p>
	420	Regardless of the value of <code>toExpPos</code>, the
	421	<a href='#toFixed'><code>toFixed</code></a> method will always return a value in normal
	422	notation and the <a href='#toExponential'><code>toExponential</code></a> method will always
	423	return a value in exponential form.
	424	</p>
	425
	426
	427
	428	<h5 id="ln10">LN10</h5>
	429	<p>
	430	<i>string\|Decimal</i>: the natural logarithm of <code>10</code><br />
	431	The default value has <code>115</code> digits
	432	</p>
	433	<p>
	434	The maximum precision of the <a href='#exp'><code>naturalExponential</code></a>,
	435	<a href='#ln'><code>naturalLogarithm</code></a>, <a href='#log'><code>logarithm</code></a>,
	436	and <a href='#pow'><code>toPower</code></a> methods is determined by the precision of the
	437	value of <code>LN10</code>.
	438	</p>
	439	<p>
	440	The default value of <code>LN10</code> enables a maximum precision of about <code>100</code>
	441	digits. To increase this, assign a new value to <code>LN10</code> using a string or Decimal
	442	value with about 15 digits more than the maximum precision required.
	443	</p>
	444	<p>
	445	An error will be thrown if the <code>LN10</code> value does not have sufficient precision to
	446	enable an operation to be performed.
	447	</p>
	448	<pre>
	449	Decimal.config({ LN10: '2.3025850929940456840179914546843642076011014886287729760333279009' })
	450
	451	Decimal.LN10.toFixed(5) // ''2.30259'</pre>
	452
	453
	454
	455	<h6 id="modes">Rounding modes</h6>
	456	<p>
	457	The library's enumerated rounding modes are stored as properties of the Decimal constructor.
	458	<br />They are not referenced internally by the library itself.
	459	</p>
	460	<p>Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.</p>
	461	<table>
	462	<tr><th>Property</th><th>Value</th><th>Description</th></tr>
	463	<tr><td><b>ROUND_UP</b></td><td class='centre'>0</td><td>Rounds away from zero</td></tr>
	464	<tr><td><b>ROUND_DOWN</b></td><td class='centre'>1</td><td>Rounds towards zero</td></tr>
	465	<tr><td><b>ROUND_CEIL</b></td><td class='centre'>2</td><td>Rounds towards Infinity</td></tr>
	466	<tr><td><b>ROUND_FLOOR</b></td><td class='centre'>3</td><td>Rounds towards -Infinity</td></tr>
	467	<tr>
	468	<td><b>ROUND_HALF_UP</b></td><td class='centre'>4</td>
	469	<td>Rounds towards nearest neighbour.<br />If equidistant, rounds away from zero</td>
	470	</tr>
	471	<tr>
	472	<td><b>ROUND_HALF_DOWN</b></td><td class='centre'>5</td>
	473	<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards zero</td>
	474	</tr>
	475	<tr>
	476	<td><b>ROUND_HALF_EVEN</b></td><td class='centre'>6</td>
	477	<td>
	478	Rounds towards nearest neighbour.<br />If equidistant, rounds towards even neighbour
	479	</td>
	480	</tr>
	481	<tr>
	482	<td><b>ROUND_HALF_CEIL</b></td><td class='centre'>7</td>
	483	<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards Infinity</td>
	484	</tr>
	485	<tr>
	486	<td><b>ROUND_HALF_FLOOR</b></td><td class='centre'>8</td>
	487	<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards -Infinity</td>
	488	</tr>
	489	</table>
	490	<pre>Decimal.config({ rounding: Decimal.ROUND_CEIL })
	491	Decimal.config({ rounding: 2 }) // equivalent
	492	Decimal.rounding // 2</pre>
	493
	494
	495
	496
	497	<h3>INSTANCE</h3>
	498
	499	<h4 id="prototype-methods">Methods</h4>
	500	<p>The methods inherited by a Decimal instance from its constructor's prototype object.</p>
	501	<p>A Decimal instance is immutable in the sense that it is not changed by its methods.</p>
	502	<p>Methods that return a Decimal can be chained:</p>
	503	<pre>x = new Decimal(2).times('999.999999999999999').dividedBy(4).toFixed(2)</pre>
	504	<p>Methods do not round their arguments before execution.</p>
	505	<p>
	506	Many method names have a shorter alias. (Internally, the library always uses the shorter
	507	method names.)
	508	</p>
	509
	510
	511
	512	<h5 id="abs">absoluteValue<code class='inset'>.abs() <i>⇒ Decimal</i></code></h5>
	513	<p>
	514	Returns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of
	515	this Decimal.
	516	</p>
	517	<p>
	518	The return value is not affected by the value of the
	519	<a href='#precision'><code>precision</code></a> setting.
	520	</p>
	521	<pre>
	522	x = new Decimal(-0.8)
	523	y = x.absoluteValue() // '0.8'
	524	z = y.abs() // '0.8'</pre>
	525
	526
	527
	528	<h5 id="cmp">comparedTo<code class='inset'>.cmp(x) <i>⇒ number</i></code></h5>
	529	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	530	<table>
	531	<tr><th>Returns</th><th> </th></tr>
	532	<tr>
	533	<td class='centre'><code>1</code></td>
	534	<td>if the value of this Decimal is greater than the value of <code>x</code></td>
	535	</tr>
	536	<tr>
	537	<td class='centre'><code>-1</code></td>
	538	<td>if the value of this Decimal is less than the value of <code>x</code></td>
	539	</tr>
	540	<tr>
	541	<td class='centre'><code>0</code></td>
	542	<td>if this Decimal and <code>x</code> have the same value</td>
	543	</tr>
	544	</table>
	545	<pre>
	546	x = new Decimal(4)
	547	y = new Decimal(5)
	548	x.comparedTo(y) // -1
	549	x.comparedTo(x.plus(1)) // 0</pre>
	550
	551
	552
	553	<h5 id="dp">decimalPlaces<code class='inset'>.dp() <i>⇒ number</i></code></h5>
	554	<p>
	555	Returns the number of decimal places, i.e. the number of digits after the decimal point, of
	556	the value of this Decimal.
	557	</p>
	558	<pre>
	559	x = new Decimal(1.234)
	560	x.decimalPlaces() // '3'
	561	y = new Decimal(987.654321)
	562	y.dp() // '6'</pre>
	563
	564
	565
	566	<h5 id="div">dividedBy<code class='inset'>.div(x) <i>⇒ Decimal</i></code></h5>
	567	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	568	<p>
	569	Returns a new Decimal whose value is the value of this Decimal divided by <code>x</code>,
	570	truncated to <a href='#precision'><code>precision</code></a> significant digits.
	571	</p>
	572	<pre>
	573	x = new Decimal(355)
	574	y = new Decimal(113)
	575	x.dividedBy(y) // '3.14159292035398230088'
	576	x.div(5) // '71'</pre>
	577
	578
	579
	580	<h5 id="idiv">
	581	dividedToIntegerBy<code class='inset'>.idiv(x) <i>⇒ Decimal</i></code>
	582	</h5>
	583	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	584	<p>
	585	Return a new Decimal whose value is the integer part of dividing this Decimal by
	586	<code>x</code>, truncated to <code><a href='#precision'>precision</a></code> significant
	587	digits.
	588	</p>
	589	<pre>
	590	x = new Decimal(5)
	591	y = new Decimal(3)
	592	x.dividedToIntegerBy(y) // '1'
	593	x.idiv(0.7) // '7'</pre>
	594
	595
	596
	597	<h5 id="eq">equals<code class='inset'>.eq(x) <i>⇒ boolean</i></code></h5>
	598	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	599	<p>
	600	Returns <code>true</code> if the value of this Decimal equals the value of <code>x</code>,
	601	otherwise returns <code>false</code>.
	602	</p>
	603	<p>Note: This method uses the <code>cmp</code> method internally.</p>
	604	<pre>
	605	0 === 1e-324 // true
	606	x = new Decimal(0)
	607	x.equals('1e-324') // false</pre>
	608
	609
	610
	611	<h5 id="exp">exponent<code class='inset'>.exponent() <i>⇒ number</i></code></h5>
	612	<p>Returns the exponent value of this Decimal.</p>
	613	<pre>
	614	x = new Decimal(1234.567)
	615	x.exponent() // 3</pre>
	616
	617
	618
	619	<h5 id="gt">greaterThan<code class='inset'>.gt(x) <i>⇒ boolean</i></code></h5>
	620	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	621	<p>
	622	Returns <code>true</code> if the value of this Decimal is greater than the value of
	623	<code>x</code>, otherwise returns <code>false</code>.
	624	</p>
	625	<p>Note: This method uses the <code>cmp</code> method internally.</p>
	626	<pre>
	627	0.1 > (0.3 - 0.2) // true
	628	x = new Decimal(0.1)
	629	x.greaterThan(Decimal(0.3).minus(0.2)) // false
	630	new Decimal(0).gt(x) // false</pre>
	631
	632
	633
	634	<h5 id="gte">
	635	greaterThanOrEqualTo<code class='inset'>.gte(x) <i>⇒ boolean</i></code>
	636	</h5>
	637	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	638	<p>
	639	Returns <code>true</code> if the value of this Decimal is greater than or equal to the value
	640	of <code>x</code>, otherwise returns <code>false</code>.
	641	</p>
	642	<p>Note: This method uses the <code>cmp</code> method internally.</p>
	643	<pre>
	644	(0.3 - 0.2) >= 0.1 // false
	645	x = new Decimal(0.3).minus(0.2)
	646	x.greaterThanOrEqualTo(0.1) // true
	647	new Decimal(1).gte(x) // true</pre>
	648
	649
	650
	651	<h5 id="isint">isInteger<code class='inset'>.isint() <i>⇒ boolean</i></code></h5>
	652	<p>
	653	Returns <code>true</code> if the value of this Decimal is a whole number, otherwise returns
	654	<code>false</code>.
	655	</p>
	656	<pre>
	657	x = new Decimal(1)
	658	x.isInteger() // true
	659	y = new Decimal(123.456)
	660	y.isint() // false</pre>
	661
	662
	663
	664	<h5 id="isneg">isNegative<code class='inset'>.isneg() <i>⇒ boolean</i></code></h5>
	665	<p>
	666	Returns <code>true</code> if the value of this Decimal is negative, otherwise returns
	667	<code>false</code>.
	668	</p>
	669	<pre>
	670	x = new Decimal(0)
	671	x.isNegative() // false
	672	y = new Decimal(2)
	673	y.isneg // false</pre>
	674	<p>Note: <code>n < 0</code> can be used if <code>n <= -Number.MIN_VALUE</code>.</p>
	675
	676
	677
	678	<h5 id="ispos">isPositive<code class='inset'>.ispos() <i>⇒ boolean</i></code></h5>
	679	<p>
	680	Returns <code>true</code> if the value of this Decimal is positive, otherwise returns
	681	<code>false</code>.
	682	</p>
	683	<pre>
	684	x = new Decimal(0)
	685	x.isPositive() // false
	686	y = new Decimal(-2)
	687	y.ispos // false</pre>
	688	<p>Note: <code>n < 0</code> can be used if <code>n <= -Number.MIN_VALUE</code>.</p>
	689
	690
	691
	692	<h5 id="isZero">isZero<code class='inset'>.isZero() <i>⇒ boolean</i></code></h5>
	693	<p>
	694	Returns <code>true</code> if the value of this Decimal is zero or minus zero, otherwise
	695	returns <code>false</code>.
	696	</p>
	697	<pre>
	698	x = new Decimal(0)
	699	x.isZero() // true</pre>
	700	<p>Note: <code>n == 0</code> can be used if <code>n >= Number.MIN_VALUE</code>.</p>
	701
	702
	703
	704	<h5 id="lt">lessThan<code class='inset'>.lt(x) <i>⇒ boolean</i></code></h5>
	705	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	706	<p>
	707	Returns <code>true</code> if the value of this Decimal is less than the value of
	708	<code>x</code>, otherwise returns <code>false</code>.
	709	</p>
	710	<p>Note: This method uses the <code>cmp</code> method internally.</p>
	711	<pre>
	712	(0.3 - 0.2) < 0.1 // true
	713	x = new Decimal(0.3).minus(0.2)
	714	x.lessThan(0.1) // false
	715	new Decimal(0).lt(x) // true</pre>
	716
	717
	718
	719	<h5 id="lte">lessThanOrEqualTo<code class='inset'>.lte(x) <i>⇒ boolean</i></code></h5>
	720	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	721	<p>
	722	Returns <code>true</code> if the value of this Decimal is less than or equal to the value of
	723	<code>x</code>, otherwise returns <code>false</code>.
	724	</p>
	725	<p>Note: This method uses the <code>cmp</code> method internally.</p>
	726	<pre>
	727	0.1 <= (0.3 - 0.2) // false
	728	x = new Decimal(0.1)
	729	x.lessThanOrEqualTo(Decimal(0.3).minus(0.2)) // true
	730	new Decimal(-1).lte(x) // true</pre>
	731
	732
	733
	734	<h5 id="log">logarithm<code class='inset'>.log(x) <i>⇒ Decimal</i></code></h5>
	735	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	736	<p>
	737	Returns a new Decimal whose value is the base <code>x</code> logarithm of the value of this
	738	Decimal, truncated to <a href='#precision'><code>precision</code></a> significant digits.
	739	</p>
	740	<p>
	741	If <code>x</code> is omitted, the base 10 logarithm of the value of this Decimal will be
	742	returned.
	743	</p>
	744	<pre>
	745	x = new Decimal(1000)
	746	x.logarithm() // '3'
	747	y = new Decimal(256)
	748	y.log(2) // '8'</pre>
	749	<p>The maximum error will be <code>1</code> <i>ulp</i> (unit in the last place).</p>
	750	<p>Logarithms to base <code>2</code> or <code>10</code> will always be correct.</p>
	751	<p>The performance of this method degrades exponentially with increasing digits.</p>
	752
	753
	754
	755	<h5 id="sub">minus<code class='inset'>.minus(x) <i>⇒ Decimal</i></code></h5>
	756	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	757	<p>
	758	Returns a new Decimal whose value is the value of this Decimal minus <code>x</code>, truncated
	759	to <a href='#precision'><code>precision</code></a> significant digits.
	760	</p>
	761	<pre>
	762	0.3 - 0.1 // 0.19999999999999998
	763	x = new Decimal(0.3)
	764	x.minus(0.1) // '0.2'</pre>
	765
	766
	767
	768	<h5 id="mod">modulo<code class='inset'>.mod(x) <i>⇒ Decimal</i></code></h5>
	769	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	770	<p>
	771	Returns a new Decimal whose value is the value of this Decimal modulo <code>x</code>,
	772	truncated to <a href='#precision'><code>precision</code></a> significant digits.
	773	</p>
	774	<pre>
	775	1 % 0.9 // 0.09999999999999998
	776	x = new Decimal(1)
	777	y = x.modulo(0.9) // '0.1'</pre>
	778
	779
	780
	781	<h5 id="exp">naturalExponential<code class='inset'>.exp() <i>⇒ Decimal</i></code></h5>
	782	<p>
	783	Returns a new Decimal whose value is the base <code>e</code> (Euler's number, the base of the
	784	natural logarithm) exponential of the value of this Decimal, truncated to
	785	<a href='#precision'><code>precision</code></a> significant digits.
	786	</p>
	787	<p>
	788	The <code><a href='#ln'>naturalLogarithm</a></code> function is the inverse of this function.
	789	</p>
	790	<pre>
	791	x = new Decimal(1)
	792	x.naturalExponential() // '2.7182818284590452354'
	793	y = new Decimal(2)
	794	y.exp() // '7.3890560989306502272'</pre>
	795	<p>The maximum error will be <code>1</code> <i>ulp</i> (unit in the last place).</p>
	796	<p>The performance of this method degrades exponentially with increasing digits.</p>
	797
	798
	799
	800	<h5 id="ln">naturalLogarithm<code class='inset'>.ln() <i>⇒ Decimal</i></code></h5>
	801	<p>
	802	Returns a new Decimal whose value is the natural logarithm of the value of this Decimal,
	803	truncated to <a href='#precision'><code>precision</code></a> significant digits.
	804	</p>
	805	<p>
	806	The natural logarithm is the inverse of the <code><a href='#exp'>naturalExponential</a></code>
	807	function.
	808	</p>
	809	<pre>
	810	x = new Decimal(10)
	811	x.naturalLogarithm() // '2.3026'
	812	y = new Decimal('1.23e+30')
	813	y.ln() // '69.28'</pre>
	814	<p>
	815	The mathematical result of the natural logarithm function is non-terminating, unless its
	816	argument is <code>1</code>.
	817	</p>
	818	<p>
	819	The time-taken by this method increases exponentially with increasing digits.
	820	</p>
	821	<p>
	822	See <a href='#ln10'>LN10</a> to configure the maximum precision available.
	823	</p>
	824
	825
	826
	827	<h5 id="neg">negated<code class='inset'>.neg() <i>⇒ Decimal</i></code></h5>
	828	<p>
	829	Returns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by
	830	<code>-1</code>.
	831	</p>
	832	<p>
	833	The return value is not affected by the value of the
	834	<a href='#precision'><code>precision</code></a> setting.
	835	</p>
	836	<pre>
	837	x = new Decimal(1.8)
	838	x.negated() // '-1.8'
	839	y = new Decimal(-1.3)
	840	y.neg() // '1.3'</pre>
	841
	842
	843
	844	<h5 id="add">plus<code class='inset'>.plus(x) <i>⇒ Decimal</i></code></h5>
	845	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	846	<p>
	847	Returns a new Decimal whose value is the value of this Decimal plus <code>x</code>, truncated
	848	to <a href='#precision'><code>precision</code></a> significant digits.
	849	</p>
	850	<pre>
	851	0.1 + 0.2 // 0.30000000000000004
	852	x = new Decimal(0.1)
	853	y = x.plus(0.2) // '0.3'
	854	new Decimal(0.7).plus(x).plus(y) // '1.1'</pre>
	855
	856
	857
	858	<h5 id="sd">precision<code class='inset'>.sd([include_zeros]) <i>⇒ number</i></code></h5>
	859	<p>Returns the number of significant digits of the value of this Decimal.</p>
	860	<p>
	861	If <code>include_zeros</code> is <code>true</code> or <code>1</code> then any trailing zeros
	862	of the integer part of a number are counted as significant digits, otherwise they are not.
	863	</p>
	864	<pre>
	865	x = new Decimal(1.234)
	866	x.precision() // '4'
	867	y = new Decimal(987000)
	868	y.sd() // '3'
	869	y.sd(true) // '6'</pre>
	870
	871
	872
	873	<h5 id="sqrt">squareRoot<code class='inset'>.sqrt() <i>⇒ Decimal</i></code></h5>
	874	<p>
	875	Returns a new Decimal whose value is the square root of this Decimal, truncated to
	876	<a href='#precision'><code>precision</code></a> significant digits.
	877	</p>
	878	<p>
	879	This method is much faster than using the <a href='#pow'><code>toPower</code></a> method with
	880	an exponent of <code>0.5</code>.
	881	</p>
	882	<pre>
	883	x = new Decimal(16)
	884	x.squareRoot() // '4'
	885	y = new Decimal(3)
	886	y.sqrt() // '1.73205080756887729353'
	887	y.sqrt().eq( y.pow(0.5) ) // true</pre>
	888
	889
	890
	891	<h5 id="mul">times<code class='inset'>.times(x) <i>⇒ Decimal</i></code></h5>
	892	<p><code>x</code>: <i>number\|string\|Decimal</i></p>
	893	<p>
	894	Returns a new Decimal whose value is the value of this Decimal times <code>x</code>,
	895	truncated to <a href='#precision'><code>precision</code></a> significant digits.
	896	</p>
	897	<pre>
	898	0.6 * 3 // 1.7999999999999998
	899	x = new Decimal(0.6)
	900	y = x.times(3) // '1.8'
	901	new Decimal('7e+500').times(y) // '1.26e+501'</pre>
	902
	903
	904
	905	<h5 id="todp">
	906	toDecimalPlaces<code class='inset'>.todp([dp [, rm]]) <i>⇒ Decimal</i></code>
	907	</h5>
	908	<p>
	909	<code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br />
	910	<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive.
	911	</p>
	912	<p>
	913	Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of
	914	<code>dp</code> decimal places using rounding mode <code>rm</code>.
	915	</p>
	916	<p>
	917	If <code>dp</code> is omitted, the return value will have the same value as this Decimal.
	918	</p>
	919	<p>
	920	If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a>
	921	is used.
	922	</p>
	923	<p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p>
	924	<pre>
	925	x = new Decimal(12.24567)
	926	x.toDecimalPlaces(0) // '12'
	927	x.toDecimalPlaces(1, 0) // '12.3'
	928
	929	y = new Decimal(9876.54321)
	930	y.todp(3) // '9876.543'
	931	y.todp(1, 0) // '9876.6'
	932	y.todp(1, Decimal.ROUND_DOWN) // '9876.5'</pre>
	933
	934
	935
	936	<h5 id="toExponential">
	937	toExponential<code class='inset'>.toExponential([dp [, rm]]) <i>⇒ string</i></code>
	938	</h5>
	939	<p>
	940	<code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br />
	941	<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive
	942	</p>
	943	<p>
	944	Returns a string representing the value of this Decimal in exponential notation rounded
	945	using rounding mode <code>rm</code> to <code>dp</code> decimal places, i.e with one digit
	946	before the decimal point and <code>dp</code> digits after it.
	947	</p>
	948	<p>
	949	If the value of this Decimal in exponential notation has fewer than <code>dp</code> fraction
	950	digits, the return value will be appended with zeros accordingly.
	951	</p>
	952	<p>
	953	If <code>dp</code> is omitted, the number of digits after the decimal point defaults to the
	954	minimum number of digits necessary to represent the value exactly.
	955	</p>
	956	<p>
	957	If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is
	958	used.
	959	</p>
	960	<p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p>
	961	<pre>
	962	x = 45.6
	963	b = new Decimal(x)
	964	x.toExponential() // '4.56e+1'
	965	y.toExponential() // '4.56e+1'
	966	x.toExponential(0) // '5e+1'
	967	y.toExponential(0) // '5e+1'
	968	x.toExponential(1) // '4.6e+1'
	969	y.toExponential(1) // '4.6e+1'
	970	y.toExponential(1, 1) // '4.5e+1' (ROUND_DOWN)
	971	x.toExponential(3) // '4.560e+1'
	972	y.toExponential(3) // '4.560e+1'</pre>
	973
	974
	975
	976	<h5 id="toFixed">
	977	toFixed<code class='inset'>.toFixed([dp [, rm]]) <i>⇒ string</i></code>
	978	</h5>
	979	<p>
	980	<code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br />
	981	<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive
	982	</p>
	983	<p>
	984	Returns a string representing the value of this Decimal in normal (fixed-point) notation
	985	rounded to <code>dp</code> decimal places using rounding mode <code>rm</code>.
	986	</p>
	987	<p>
	988	If the value of this Decimal in normal notation has fewer than <code>dp</code> fraction
	989	digits, the return value will be appended with zeros accordingly.
	990	</p>
	991	<p>
	992	Unlike <code>Number.prototype.toFixed</code>, which returns exponential notation if a number
	993	is greater or equal to <code>10<sup>21</sup></code>, this method will always return normal
	994	notation.
	995	</p>
	996	<p>
	997	If <code>dp</code> is omitted, the return value will be unrounded and in normal notation. This
	998	is unlike <code>Number.prototype.toFixed</code>, which returns the value to zero decimal
	999	places, but is useful when because of the current
	1000	<a href="#toExpNeg"><code>toExpNeg</code></a> or
	1001	<a href="#toExpPos"><code>toExpNeg</code></a> values,
	1002	<code><a href='#toString'>toString</a></code> returns exponential notation.
	1003	</p>
	1004	<p>
	1005	If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is
	1006	used.
	1007	</p>
	1008	<p>Throws on an invalid <code>dp</code> or <code>rm</code> value.</p>
	1009	<pre>
	1010	x = 3.456
	1011	b = new Decimal(x)
	1012	x.toFixed() // '3'
	1013	y.toFixed() // '3.456'
	1014	y.toFixed(0) // '3'
	1015	x.toFixed(2) // '3.46'
	1016	y.toFixed(2) // '3.46'
	1017	y.toFixed(2, 1) // '3.45' (ROUND_DOWN)
	1018	x.toFixed(5) // '3.45600'
	1019	y.toFixed(5) // '3.45600'</pre>
	1020
	1021
	1022
	1023	<h5 id="toInteger">toInteger<code class='inset'>.toint() <i>⇒ Decimal</i></code></h5>
	1024	<p>
	1025	Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using
	1026	rounding mode <a href='#rounding'><code>rounding</code></a>.
	1027	</p>
	1028	<p>
	1029	To emulate <code>Math.round</code>, set <a href='#rounding'><code>rounding</code></a> to
	1030	<code>7</code>, i.e. <a href='#modes'><code>ROUND_HALF_CEIL</code></a>.
	1031	</p>
	1032	<pre>
	1033	Decimal.config({ rounding: 4 })
	1034	x = 1234.5
	1035	x.toInteger() // '1235'
	1036
	1037	Decimal.rounding = Decimal.ROUND_DOWN
	1038	x.toint() // '1234'
	1039	x // '1234.5'</pre>
	1040
	1041
	1042
	1043	<h5 id="toJSON">toJSON<code class='inset'>.toJSON() <i>⇒ string</i></code></h5>
	1044	<p>As <a href='#toString'><code>toString</code></a>.</p>
	1045
	1046
	1047
	1048	<h5 id="toNumber">toNumber<code class='inset'>.toNumber() <i>⇒ number</i></code></h5>
	1049	<p>Returns the value of this Decimal converted to a primitive number.</p>
	1050	<p>
	1051	Type coercion with, for example, JavaScript's unary plus operator will also work, except that
	1052	a Decimal with the value minus zero will convert to positive zero.
	1053	</p>
	1054	<pre>
	1055	x = new Decimal(456.789)
	1056	x.toNumber() // 456.789
	1057	+x // 456.789
	1058
	1059	y = new Decimal('45987349857634085409857349856430985')
	1060	y.toNumber() // 4.598734985763409e+34</pre>
	1061
	1062
	1063
	1064	<h5 id="pow">toPower<code class='inset'>.pow(x) <i>⇒ Decimal</i></code></h5>
	1065	<p><code>x</code>: <i>number\|string\|Decimal</i>: integer or non-integer</p>
	1066	<p>
	1067	Returns a new Decimal whose value is the value of this Decimal raised to the power
	1068	<code>x</code>, truncated to <a href='#precision'><code>precision</code></a> significant
	1069	digits.
	1070	</p>
	1071	<p>
	1072	The performance of this method degrades exponentially with increasing digits.<br />
	1073	For non-integer exponents in particular, the performance of this method may not be adequate.
	1074	</p>
	1075	<p>The maximum error will be <code>1</code> <i>ulp</i> (unit in the last place). </p>
	1076	<pre>
	1077	Math.pow(0.7, 2) // 0.48999999999999994
	1078	x = new Decimal(0.7)
	1079	x.toPower(2) // '0.49'
	1080	new Decimal(3).pow(-2) // '0.11111111111111111111'
	1081
	1082	new Decimal(1217652.23).pow('98765.489305603941')
	1083	// '4.8227010515242461181e+601039'</pre>
	1084
	1085
	1086
	1087
	1088	<h5 id="toPrecision">
	1089	toPrecision<code class='inset'>.toPrecision([sd [, rm]]) <i>⇒ string</i></code>
	1090	</h5>
	1091	<p>
	1092	<code>sd</code>: <i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br />
	1093	<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive
	1094	</p>
	1095	<p>
	1096	Returns a string representing the value of this Decimal rounded to <code>sd</code> significant
	1097	digits using rounding mode <code>rm</code>.
	1098	</p>
	1099	<p>
	1100	If <code>sd</code> is less than the number of digits necessary to represent the integer part
	1101	of the value in normal (fixed-point) notation, then exponential notation is used.
	1102	</p>
	1103	<p>
	1104	If <code>sd</code> is omitted, the return value is the same as
	1105	<code><a href='#toString'>toString</a></code>.
	1106	</p>
	1107	<p>
	1108	If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a> is
	1109	used.
	1110	</p>
	1111	<p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p>
	1112	<pre>
	1113	x = 45.6
	1114	b = new Decimal(x)
	1115	x.toPrecision() // '45.6'
	1116	y.toPrecision() // '45.6'
	1117	x.toPrecision(1) // '5e+1'
	1118	y.toPrecision(1) // '5e+1'
	1119	y.toPrecision(2, 0) // '4.6e+1' (ROUND_UP)
	1120	y.toPrecision(2, 1) // '4.5e+1' (ROUND_DOWN)
	1121	x.toPrecision(5) // '45.600'
	1122	y.toPrecision(5) // '45.600'</pre>
	1123
	1124
	1125
	1126	<h5 id="tosd">
	1127	toSignificantDigits<code class='inset'>.tosd([sd [, rm]]) <i>⇒ Decimal</i></code>
	1128	</h5>
	1129	<p>
	1130	<code>sd</code>: <i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive.<br />
	1131	<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive.
	1132	</p>
	1133	<p>
	1134	Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of
	1135	<code>sd</code> significant digits using rounding mode <code>rm</code>.
	1136	</p>
	1137	<p>
	1138	If <code>sd</code> is omitted, the return value will be rounded to
	1139	<a href='#precision'><code>precision</code></a> significant digits.
	1140	</p>
	1141	<p>
	1142	If <code>rm</code> is omitted, rounding mode <a href='#rounding'><code>rounding</code></a>
	1143	will be used.
	1144	</p>
	1145	<p>Throws on an invalid <code>sd</code> or <code>rm</code> value.</p>
	1146	<pre>
	1147	Decimal.config({ precision: 5, rounding: 4 })
	1148	x = new Decimal(9876.54321)
	1149
	1150	x.toSignificantDigits() // '9876.5'
	1151	x.toSignificantDigits(6) // '9876.54'
	1152	x.toSignificantDigits(6, Decimal.ROUND_UP) // '9876.55'
	1153	x.tosd(2) // '9900'
	1154	x.tosd(2, 1) // '9800'
	1155	x // '9876.54321'</pre>
	1156
	1157
	1158
	1159	<h5 id="toString">toString<code class='inset'>.toString() <i>⇒ string</i></code></h5>
	1160	<p>Returns a string representing the value of this Decimal.</p>
	1161	<p>
	1162	If this Decimal has a positive exponent that is equal to or greater than
	1163	<a href="#toExpPos"><code>toExpPos</code></a>, or a negative exponent equal to or less than
	1164	<a href="#toExpPos"><code>toExpNeg</code></a>, then exponential notation will be returned.
	1165	</p>
	1166	<pre>
	1167	x = new Decimal(750000)
	1168	x.toString() // '750000'
	1169	Decimal.config({ toExpPos: 5 })
	1170	x.toString() // '7.5e+5'
	1171
	1172	Decimal.config({ precision: 4 });
	1173	y = new Decimal('1.23456789')
	1174	y.toString() // '1.23456789'</pre>
	1175
	1176
	1177
	1178	<h5 id="valueOf">valueOf<code class='inset'>.val() <i>⇒ string</i></code></h5>
	1179	<p>As <a href='#toString'><code>toString</code></a>.</p>
	1180
	1181
	1182
	1183
	1184
	1185	<h4 id="instance-properties">Properties</h4>
	1186	<p>
	1187	The value of a Decimal is stored in a normalised base <code>10000000</code> floating point
	1188	format.
	1189	</p>
	1190	<p>
	1191	A Decimal instance is an object with three properties:
	1192	</p>
	1193	<table>
	1194	<tr>
	1195	<th>Property</th>
	1196	<th>Description</th>
	1197	<th>Type</th>
	1198	<th>Value</th>
	1199	</tr>
	1200	<tr>
	1201	<td class='centre' id='digits'><b>d</b></td>
	1202	<td>digits</td>
	1203	<td><i>number</i><code style='color:#000'>[]</code></td>
	1204	<td> Array of integers, each <code>0</code> - <code>1e7</code></td>
	1205	</tr>
	1206	<tr>
	1207	<td class='centre' id='exponent'><b>e</b></td>
	1208	<td>exponent*</td>
	1209	<td><i>number</i></td>
	1210	<td>Integer, <code>-1286742750677284</code> to <code>1286742750677284</code> inclusive</td>
	1211	</tr>
	1212	<tr>
	1213	<td class='centre' id='sign'><b>s</b></td>
	1214	<td>sign</td>
	1215	<td><i>number</i></td>
	1216	<td><code>-1</code>, <code>0</code>, or <code>1</code></td>
	1217	</tr>
	1218	</table>
	1219	<p>
	1220	*This is the exponent in base <code>10000000</code>. To get the base 10 exponent, use the
	1221	<a href='#exp'><code>exponent</code></a> method.
	1222	</p>
	1223	<p>The properties are best considered to be read-only.</p>
	1224	<p>
	1225	As with JavaScript numbers, the original exponent and fractional trailing zeros of a number
	1226	are not preserved.
	1227	</p>
	1228	<pre>
	1229	x = new Decimal(0.123) // '0.123'
	1230	x.toExponential() // '1.23e-1'
	1231	x.d // [ 1230000 ]
	1232	x.e // -1
	1233	x.s // 1
	1234
	1235	y = new Number(-123.4567000e+2) // '-12345.67'
	1236	y.toExponential() // '-1.234567e+4'
	1237	z = new Decimal('-123.4567000e+2') // '-12345.67'
	1238	z.toExponential() // '-1.234567e+4'
	1239	z.d // [ 12345, 6700000 ]
	1240	z.e // 4
	1241	z.s // -1</pre>
	1242
	1243
	1244
	1245	<h4 id='Errors'>Errors</h4>
	1246	<p>
	1247	The errors that are thrown are generic <code>Error</code> objects whose <code>message</code>
	1248	property begins with <code>"[DecimalError]"</code>.
	1249	</p>
	1250	<p>To determine if an exception is a Decimal Error:</p>
	1251	<pre>
	1252	try {
	1253	// ...
	1254	} catch (e) {
	1255	if ( e instanceof Error && /DecimalError/.test(e.message) ) {
	1256	// ...
	1257	}
	1258	}</pre>
	1259
	1260
	1261
	1262	<h2 id='faq'>FAQ</h2>
	1263	<h6>Why are trailing fractional zeros removed from Decimals?</h6>
	1264	<p>
	1265	Some arbitrary-precision libraries retain trailing fractional zeros as they can indicate the
	1266	precision of a value. This can be useful but the results of arithmetic operations can be
	1267	misleading.
	1268	</p>
	1269	<pre>
	1270	x = new BigDecimal("1.0")
	1271	y = new BigDecimal("1.1000")
	1272	z = x.add(y) // 2.1000
	1273
	1274	x = new BigDecimal("1.20")
	1275	y = new BigDecimal("3.45000")
	1276	z = x.multiply(y) // 4.1400000</pre>
	1277	<p>
	1278	To specify the precision of a value is to specify that the value lies
	1279	within a certain range.
	1280	</p>
	1281	<p>
	1282	In the first example, <code>x</code> has a value of <code>1.0</code>. The trailing zero shows
	1283	the precision of the value, implying that it is in the range <code>0.95</code> to
	1284	<code>1.05</code>. Similarly, the precision indicated by the trailing zeros of <code>y</code>
	1285	indicates that the value is in the range <code>1.09995</code> to <code>1.10005</code>.
	1286	</p>
	1287	<p>
	1288	If we add the two lowest values in the ranges we have, <code>0.95 + 1.09995 = 2.04995</code>,
	1289	and if we add the two highest values we have, <code>1.05 + 1.10005 = 2.15005</code>, so the
	1290	range of the result of the addition implied by the precision of its operands is
	1291	<code>2.04995</code> to <code>2.15005</code>.
	1292	</p>
	1293	<p>
	1294	The result given by BigDecimal of <code>2.1000</code> however, indicates that the value is in
	1295	the range <code>2.09995</code> to <code>2.10005</code> and therefore the precision implied by
	1296	its trailing zeros may be misleading.
	1297	</p>
	1298	<p>
	1299	In the second example, the true range is <code>4.122744</code> to <code>4.157256</code> yet
	1300	the BigDecimal answer of <code>4.1400000</code> indicates a range of <code>4.13999995</code>
	1301	to <code>4.14000005</code>. Again, the precision implied by the trailing zeros may be
	1302	misleading.
	1303	</p>
	1304	<p>
	1305	This library, like binary floating point and most calculators, does not retain trailing
	1306	fractional zeros. Instead, the <code>toExponential</code>, <code>toFixed</code> and
	1307	<code>toPrecision</code> methods enable trailing zeros to be added if and when required.<br />
	1308	</p>
	1309	</div>
	1310
	1311	</body>
	1312	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: