/
API.html
2249 lines (2007 loc) · 83.1 KB
/
API.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="Author" content="M Mclaughlin">
<title>bignumber.js API</title>
<style>
html{font-size:100%}
body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;
line-height:1.65em;min-height:100%;margin:0}
body,i{color:#000}
.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:200px;overflow-y:auto;
padding:15px 0 30px 15px}
div.container{width:600px;margin:50px 0 50px 240px}
p{margin:0 0 1em;width:600px}
pre,ul{margin:1em 0}
h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}
h1,h2{padding:.75em 0}
h1{font:400 3em Verdana,sans-serif;color:#000;margin-bottom:1em}
h2{font-size:2.25em;color:#ff2a00}
h3{font-size:1.75em;color:#4dc71f}
h4{font-size:1.75em;color:#ff2a00;padding-bottom:.75em}
h5{font-size:1.2em;margin-bottom:.4em}
h6{font-size:1.1em;margin-bottom:0.8em;padding:0.5em 0}
dd{padding-top:.35em}
dt{padding-top:.5em}
b{font-weight:700}
dt b{font-size:1.3em}
a,a:visited{color:#ff2a00;text-decoration:none}
a:active,a:hover{outline:0;text-decoration:underline}
.nav a,.nav b,.nav a:visited{display:block;color:#ff2a00;font-weight:700; margin-top:15px}
.nav b{color:#4dc71f;margin-top:20px;cursor:default;width:auto}
ul{list-style-type:none;padding:0 0 0 20px}
.nav ul{line-height:14px;padding-left:0;margin:5px 0 0}
.nav ul a,.nav ul a:visited,span{display:inline;color:#000;font-family:Verdana,Geneva,sans-serif;
font-size:11px;font-weight:400;margin:0}
.inset,ul.inset{margin-left:20px}
.inset{font-size:.9em}
.nav li{width:auto;margin:0 0 3px}
.alias{font-style:italic;margin-left:20px}
table{border-collapse:collapse;border-spacing:0;border:2px solid #a7dbd8;margin:1.75em 0;padding:0}
td,th{text-align:left;margin:0;padding:2px 5px;border:1px dotted #a7dbd8}
th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#ff2a00}
code,pre{font-family:Consolas, monaco, monospace;font-weight:400}
pre{background:#f5f5f5;white-space:pre-wrap;word-wrap:break-word;border-left:5px solid #abef98;
padding:1px 0 1px 15px;margin:1.2em 0}
code,.nav-title{color:#ff2a00}
.end{margin-bottom:25px}
.centre{text-align:center}
.error-table{font-size:13px;width:100%}
#faq{margin:3em 0 0}
li span{float:right;margin-right:10px;color:#c0c0c0}
#js{font:inherit;color:#4dc71f}
</style>
</head>
<body>
<div class="nav">
<b>v9.0.2</b>
<a class='nav-title' href="#">API</a>
<b> CONSTRUCTOR </b>
<ul>
<li><a href="#bignumber">BigNumber</a></li>
</ul>
<a href="#methods">Methods</a>
<ul>
<li><a href="#clone">clone</a></li>
<li><a href="#config" >config</a><span>set</span></li>
<li>
<ul class="inset">
<li><a href="#decimal-places">DECIMAL_PLACES</a></li>
<li><a href="#rounding-mode" >ROUNDING_MODE</a></li>
<li><a href="#exponential-at">EXPONENTIAL_AT</a></li>
<li><a href="#range" >RANGE</a></li>
<li><a href="#crypto" >CRYPTO</a></li>
<li><a href="#modulo-mode" >MODULO_MODE</a></li>
<li><a href="#pow-precision" >POW_PRECISION</a></li>
<li><a href="#format" >FORMAT</a></li>
<li><a href="#alphabet" >ALPHABET</a></li>
</ul>
</li>
<li><a href="#isBigNumber">isBigNumber</a></li>
<li><a href="#max" >maximum</a><span>max</span></li>
<li><a href="#min" >minimum</a><span>min</span></li>
<li><a href="#random" >random</a></li>
<li><a href="#sum" >sum</a></li>
</ul>
<a href="#constructor-properties">Properties</a>
<ul>
<li><a href="#round-up" >ROUND_UP</a></li>
<li><a href="#round-down" >ROUND_DOWN</a></li>
<li><a href="#round-ceil" >ROUND_CEIL</a></li>
<li><a href="#round-floor" >ROUND_FLOOR</a></li>
<li><a href="#round-half-up" >ROUND_HALF_UP</a></li>
<li><a href="#round-half-down" >ROUND_HALF_DOWN</a></li>
<li><a href="#round-half-even" >ROUND_HALF_EVEN</a></li>
<li><a href="#round-half-ceil" >ROUND_HALF_CEIL</a></li>
<li><a href="#round-half-floor">ROUND_HALF_FLOOR</a></li>
<li><a href="#debug" >DEBUG</a></li>
</ul>
<b> INSTANCE </b>
<a href="#prototype-methods">Methods</a>
<ul>
<li><a href="#abs" >absoluteValue </a><span>abs</span> </li>
<li><a href="#cmp" >comparedTo </a> </li>
<li><a href="#dp" >decimalPlaces </a><span>dp</span> </li>
<li><a href="#div" >dividedBy </a><span>div</span> </li>
<li><a href="#divInt" >dividedToIntegerBy </a><span>idiv</span> </li>
<li><a href="#pow" >exponentiatedBy </a><span>pow</span> </li>
<li><a href="#int" >integerValue </a> </li>
<li><a href="#eq" >isEqualTo </a><span>eq</span> </li>
<li><a href="#isF" >isFinite </a> </li>
<li><a href="#gt" >isGreaterThan </a><span>gt</span> </li>
<li><a href="#gte" >isGreaterThanOrEqualTo</a><span>gte</span> </li>
<li><a href="#isInt" >isInteger </a> </li>
<li><a href="#lt" >isLessThan </a><span>lt</span> </li>
<li><a href="#lte" >isLessThanOrEqualTo </a><span>lte</span> </li>
<li><a href="#isNaN" >isNaN </a> </li>
<li><a href="#isNeg" >isNegative </a> </li>
<li><a href="#isPos" >isPositive </a> </li>
<li><a href="#isZ" >isZero </a> </li>
<li><a href="#minus" >minus </a> </li>
<li><a href="#mod" >modulo </a><span>mod</span> </li>
<li><a href="#times" >multipliedBy </a><span>times</span></li>
<li><a href="#neg" >negated </a> </li>
<li><a href="#plus" >plus </a> </li>
<li><a href="#sd" >precision </a><span>sd</span> </li>
<li><a href="#shift" >shiftedBy </a> </li>
<li><a href="#sqrt" >squareRoot </a><span>sqrt</span> </li>
<li><a href="#toE" >toExponential </a> </li>
<li><a href="#toFix" >toFixed </a> </li>
<li><a href="#toFor" >toFormat </a> </li>
<li><a href="#toFr" >toFraction </a> </li>
<li><a href="#toJSON" >toJSON </a> </li>
<li><a href="#toN" >toNumber </a> </li>
<li><a href="#toP" >toPrecision </a> </li>
<li><a href="#toS" >toString </a> </li>
<li><a href="#valueOf">valueOf </a> </li>
</ul>
<a href="#instance-properties">Properties</a>
<ul>
<li><a href="#coefficient">c: coefficient</a></li>
<li><a href="#exponent" >e: exponent</a></li>
<li><a href="#sign" >s: sign</a></li>
</ul>
<a href="#zero-nan-infinity">Zero, NaN & Infinity</a>
<a href="#Errors">Errors</a>
<a href="#type-coercion">Type coercion</a>
<a class='end' href="#faq">FAQ</a>
</div>
<div class="container">
<h1>bignumber<span id='js'>.js</span></h1>
<p>A JavaScript library for arbitrary-precision arithmetic.</p>
<p><a href="https://github.com/MikeMcl/bignumber.js">Hosted on GitHub</a>. </p>
<h2>API</h2>
<p>
See the <a href='https://github.com/MikeMcl/bignumber.js'>README</a> on GitHub for a
quick-start introduction.
</p>
<p>
In all examples below, <code>var</code> and semicolons are not shown, and if a commented-out
value is in quotes it means <code>toString</code> has been called on the preceding expression.
</p>
<h3>CONSTRUCTOR</h3>
<h5 id="bignumber">
BigNumber<code class='inset'>BigNumber(n [, base]) <i>⇒ BigNumber</i></code>
</h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<code>base</code>: <i>number</i>: integer, <code>2</code> to <code>36</code> inclusive. (See
<a href='#alphabet'><code>ALPHABET</code></a> to extend this range).
</p>
<p>
Returns a new instance of a BigNumber object with value <code>n</code>, where <code>n</code>
is a numeric value in the specified <code>base</code>, or base <code>10</code> if
<code>base</code> is omitted or is <code>null</code> or <code>undefined</code>.
</p>
<p>
Note that the BigNnumber constructor accepts an <code>n</code> of type <em>number</em> purely
as a convenience so that string quotes don't have to be typed when entering literal values,
and that it is the <code>toString</code> value of <code>n</code> that is used rather than its
underlying binary floating point value converted to decimal.
</p>
<pre>
x = new BigNumber(123.4567) // '123.4567'
// 'new' is optional
y = BigNumber(x) // '123.4567'</pre>
<p>
If <code>n</code> is a base <code>10</code> value it can be in normal or exponential notation.
Values in other bases must be in normal notation. Values in any base can have fraction digits,
i.e. digits after the decimal point.
</p>
<pre>
new BigNumber(43210) // '43210'
new BigNumber('4.321e+4') // '43210'
new BigNumber('-735.0918e-430') // '-7.350918e-428'
new BigNumber('123412421.234324', 5) // '607236.557696'</pre>
<p>
Signed <code>0</code>, signed <code>Infinity</code> and <code>NaN</code> are supported.
</p>
<pre>
new BigNumber('-Infinity') // '-Infinity'
new BigNumber(NaN) // 'NaN'
new BigNumber(-0) // '0'
new BigNumber('.5') // '0.5'
new BigNumber('+2') // '2'</pre>
<p>
String values in hexadecimal literal form, e.g. <code>'0xff'</code> or <code>'0xFF'</code>
(but not <code>'0xfF'</code>), are valid, as are string values with the octal and binary
prefixs <code>'0o'</code> and <code>'0b'</code>. String values in octal literal form without
the prefix will be interpreted as decimals, e.g. <code>'011'</code> is interpreted as 11, not 9.
</p>
<pre>
new BigNumber(-10110100.1, 2) // '-180.5'
new BigNumber('-0b10110100.1') // '-180.5'
new BigNumber('ff.8', 16) // '255.5'
new BigNumber('0xff.8') // '255.5'</pre>
<p>
If a base is specified, <code>n</code> is rounded according to the current
<a href='#decimal-places'><code>DECIMAL_PLACES</code></a> and
<a href='#rounding-mode'><code>ROUNDING_MODE</code></a> settings. <em>This includes base
<code>10</code> so don't include a <code>base</code> parameter for decimal values unless
this behaviour is wanted.</em>
</p>
<pre>BigNumber.config({ DECIMAL_PLACES: 5 })
new BigNumber(1.23456789) // '1.23456789'
new BigNumber(1.23456789, 10) // '1.23457'</pre>
<p>An error is thrown if <code>base</code> is invalid. See <a href='#Errors'>Errors</a>.</p>
<p>
There is no limit to the number of digits of a value of type <em>string</em> (other than
that of JavaScript's maximum array size). See <a href='#range'><code>RANGE</code></a> to set
the maximum and minimum possible exponent value of a BigNumber.
</p>
<pre>
new BigNumber('5032485723458348569331745.33434346346912144534543')
new BigNumber('4.321e10000000')</pre>
<p>BigNumber <code>NaN</code> is returned if <code>n</code> is invalid
(unless <code>BigNumber.DEBUG</code> is <code>true</code>, see below).</p>
<pre>
new BigNumber('.1*') // 'NaN'
new BigNumber('blurgh') // 'NaN'
new BigNumber(9, 2) // 'NaN'</pre>
<p>
To aid in debugging, if <code>BigNumber.DEBUG</code> is <code>true</code> then an error will
be thrown on an invalid <code>n</code>. An error will also be thrown if <code>n</code> is of
type <em>number</em> and has more than <code>15</code> significant digits, as calling
<code><a href='#toS'>toString</a></code> or <code><a href='#valueOf'>valueOf</a></code> on
these numbers may not result in the intended value.
</p>
<pre>
console.log(823456789123456.3) // 823456789123456.2
new BigNumber(823456789123456.3) // '823456789123456.2'
BigNumber.DEBUG = true
// '[BigNumber Error] Number primitive has more than 15 significant digits'
new BigNumber(823456789123456.3)
// '[BigNumber Error] Not a base 2 number'
new BigNumber(9, 2)</pre>
<p>
A BigNumber can also be created from an object literal.
Use <code><a href='#isBigNumber'>isBigNumber</a></code> to check that it is well-formed.
</p>
<pre>new BigNumber({ s: 1, e: 2, c: [ 777, 12300000000000 ], _isBigNumber: true }) // '777.123'</pre>
<h4 id="methods">Methods</h4>
<p>The static methods of a BigNumber constructor.</p>
<h5 id="clone">clone
<code class='inset'>.clone([object]) <i>⇒ BigNumber constructor</i></code>
</h5>
<p><code>object</code>: <i>object</i></p>
<p>
Returns a new independent BigNumber constructor with configuration as described by
<code>object</code> (see <a href='#config'><code>config</code></a>), or with the default
configuration if <code>object</code> is <code>null</code> or <code>undefined</code>.
</p>
<p>
Throws if <code>object</code> is not an object. See <a href='#Errors'>Errors</a>.
</p>
<pre>BigNumber.config({ DECIMAL_PLACES: 5 })
BN = BigNumber.clone({ DECIMAL_PLACES: 9 })
x = new BigNumber(1)
y = new BN(1)
x.div(3) // 0.33333
y.div(3) // 0.333333333
// BN = BigNumber.clone({ DECIMAL_PLACES: 9 }) is equivalent to:
BN = BigNumber.clone()
BN.config({ DECIMAL_PLACES: 9 })</pre>
<h5 id="config">config<code class='inset'>set([object]) <i>⇒ object</i></code></h5>
<p>
<code>object</code>: <i>object</i>: an object that contains some or all of the following
properties.
</p>
<p>Configures the settings for this particular BigNumber constructor.</p>
<dl class='inset'>
<dt id="decimal-places"><code><b>DECIMAL_PLACES</b></code></dt>
<dd>
<i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br />
Default value: <code>20</code>
</dd>
<dd>
The <em>maximum</em> number of decimal places of the results of operations involving
division, i.e. division, square root and base conversion operations, and power operations
with negative exponents.<br />
</dd>
<dd>
<pre>BigNumber.config({ DECIMAL_PLACES: 5 })
BigNumber.set({ DECIMAL_PLACES: 5 }) // equivalent</pre>
</dd>
<dt id="rounding-mode"><code><b>ROUNDING_MODE</b></code></dt>
<dd>
<i>number</i>: integer, <code>0</code> to <code>8</code> inclusive<br />
Default value: <code>4</code> <a href="#round-half-up">(<code>ROUND_HALF_UP</code>)</a>
</dd>
<dd>
The rounding mode used in the above operations and the default rounding mode of
<a href='#dp'><code>decimalPlaces</code></a>,
<a href='#sd'><code>precision</code></a>,
<a href='#toE'><code>toExponential</code></a>,
<a href='#toFix'><code>toFixed</code></a>,
<a href='#toFor'><code>toFormat</code></a> and
<a href='#toP'><code>toPrecision</code></a>.
</dd>
<dd>The modes are available as enumerated properties of the BigNumber constructor.</dd>
<dd>
<pre>BigNumber.config({ ROUNDING_MODE: 0 })
BigNumber.set({ ROUNDING_MODE: BigNumber.ROUND_UP }) // equivalent</pre>
</dd>
<dt id="exponential-at"><code><b>EXPONENTIAL_AT</b></code></dt>
<dd>
<i>number</i>: integer, magnitude <code>0</code> to <code>1e+9</code> inclusive, or
<br />
<i>number</i>[]: [ integer <code>-1e+9</code> to <code>0</code> inclusive, integer
<code>0</code> to <code>1e+9</code> inclusive ]<br />
Default value: <code>[-7, 20]</code>
</dd>
<dd>
The exponent value(s) at which <code>toString</code> returns exponential notation.
</dd>
<dd>
If a single number is assigned, the value is the exponent magnitude.<br />
If an array of two numbers is assigned then the first number is the negative exponent
value at and beneath which exponential notation is used, and the second number is the
positive exponent value at and above which the same.
</dd>
<dd>
For example, to emulate JavaScript numbers in terms of the exponent values at which they
begin to use exponential notation, use <code>[-7, 20]</code>.
</dd>
<dd>
<pre>BigNumber.config({ EXPONENTIAL_AT: 2 })
new BigNumber(12.3) // '12.3' e is only 1
new BigNumber(123) // '1.23e+2'
new BigNumber(0.123) // '0.123' e is only -1
new BigNumber(0.0123) // '1.23e-2'
BigNumber.config({ EXPONENTIAL_AT: [-7, 20] })
new BigNumber(123456789) // '123456789' e is only 8
new BigNumber(0.000000123) // '1.23e-7'
// Almost never return exponential notation:
BigNumber.config({ EXPONENTIAL_AT: 1e+9 })
// Always return exponential notation:
BigNumber.config({ EXPONENTIAL_AT: 0 })</pre>
</dd>
<dd>
Regardless of the value of <code>EXPONENTIAL_AT</code>, the <code>toFixed</code> method
will always return a value in normal notation and the <code>toExponential</code> method
will always return a value in exponential form.
</dd>
<dd>
Calling <code>toString</code> with a base argument, e.g. <code>toString(10)</code>, will
also always return normal notation.
</dd>
<dt id="range"><code><b>RANGE</b></code></dt>
<dd>
<i>number</i>: integer, magnitude <code>1</code> to <code>1e+9</code> inclusive, or
<br />
<i>number</i>[]: [ integer <code>-1e+9</code> to <code>-1</code> inclusive, integer
<code>1</code> to <code>1e+9</code> inclusive ]<br />
Default value: <code>[-1e+9, 1e+9]</code>
</dd>
<dd>
The exponent value(s) beyond which overflow to <code>Infinity</code> and underflow to
zero occurs.
</dd>
<dd>
If a single number is assigned, it is the maximum exponent magnitude: values wth a
positive exponent of greater magnitude become <code>Infinity</code> and those with a
negative exponent of greater magnitude become zero.
<dd>
If an array of two numbers is assigned then the first number is the negative exponent
limit and the second number is the positive exponent limit.
</dd>
<dd>
For example, to emulate JavaScript numbers in terms of the exponent values at which they
become zero and <code>Infinity</code>, use <code>[-324, 308]</code>.
</dd>
<dd>
<pre>BigNumber.config({ RANGE: 500 })
BigNumber.config().RANGE // [ -500, 500 ]
new BigNumber('9.999e499') // '9.999e+499'
new BigNumber('1e500') // 'Infinity'
new BigNumber('1e-499') // '1e-499'
new BigNumber('1e-500') // '0'
BigNumber.config({ RANGE: [-3, 4] })
new BigNumber(99999) // '99999' e is only 4
new BigNumber(100000) // 'Infinity' e is 5
new BigNumber(0.001) // '0.01' e is only -3
new BigNumber(0.0001) // '0' e is -4</pre>
</dd>
<dd>
The largest possible magnitude of a finite BigNumber is
<code>9.999...e+1000000000</code>.<br />
The smallest possible magnitude of a non-zero BigNumber is <code>1e-1000000000</code>.
</dd>
<dt id="crypto"><code><b>CRYPTO</b></code></dt>
<dd>
<i>boolean</i>: <code>true</code> or <code>false</code>.<br />
Default value: <code>false</code>
</dd>
<dd>
The value that determines whether cryptographically-secure pseudo-random number
generation is used.
</dd>
<dd>
If <code>CRYPTO</code> is set to <code>true</code> then the
<a href='#random'><code>random</code></a> method will generate random digits using
<code>crypto.getRandomValues</code> in browsers that support it, or
<code>crypto.randomBytes</code> if using Node.js.
</dd>
<dd>
If neither function is supported by the host environment then attempting to set
<code>CRYPTO</code> to <code>true</code> will fail and an exception will be thrown.
</dd>
<dd>
If <code>CRYPTO</code> is <code>false</code> then the source of randomness used will be
<code>Math.random</code> (which is assumed to generate at least <code>30</code> bits of
randomness).
</dd>
<dd>See <a href='#random'><code>random</code></a>.</dd>
<dd>
<pre>
// Node.js
const crypto = require('crypto'); // CommonJS
import * as crypto from 'crypto'; // ES module
global.crypto = crypto;
BigNumber.config({ CRYPTO: true })
BigNumber.config().CRYPTO // true
BigNumber.random() // 0.54340758610486147524</pre>
</dd>
<dt id="modulo-mode"><code><b>MODULO_MODE</b></code></dt>
<dd>
<i>number</i>: integer, <code>0</code> to <code>9</code> inclusive<br />
Default value: <code>1</code> (<a href="#round-down"><code>ROUND_DOWN</code></a>)
</dd>
<dd>The modulo mode used when calculating the modulus: <code>a mod n</code>.</dd>
<dd>
The quotient, <code>q = a / n</code>, is calculated according to the
<a href='#rounding-mode'><code>ROUNDING_MODE</code></a> that corresponds to the chosen
<code>MODULO_MODE</code>.
</dd>
<dd>The remainder, <code>r</code>, is calculated as: <code>r = a - n * q</code>.</dd>
<dd>
The modes that are most commonly used for the modulus/remainder operation are shown in
the following table. Although the other rounding modes can be used, they may not give
useful results.
</dd>
<dd>
<table>
<tr><th>Property</th><th>Value</th><th>Description</th></tr>
<tr>
<td><b>ROUND_UP</b></td><td class='centre'>0</td>
<td>
The remainder is positive if the dividend is negative, otherwise it is negative.
</td>
</tr>
<tr>
<td><b>ROUND_DOWN</b></td><td class='centre'>1</td>
<td>
The remainder has the same sign as the dividend.<br />
This uses 'truncating division' and matches the behaviour of JavaScript's
remainder operator <code>%</code>.
</td>
</tr>
<tr>
<td><b>ROUND_FLOOR</b></td><td class='centre'>3</td>
<td>
The remainder has the same sign as the divisor.<br />
This matches Python's <code>%</code> operator.
</td>
</tr>
<tr>
<td><b>ROUND_HALF_EVEN</b></td><td class='centre'>6</td>
<td>The <i>IEEE 754</i> remainder function.</td>
</tr>
<tr>
<td><b>EUCLID</b></td><td class='centre'>9</td>
<td>
The remainder is always positive. Euclidian division: <br />
<code>q = sign(n) * floor(a / abs(n))</code>
</td>
</tr>
</table>
</dd>
<dd>
The rounding/modulo modes are available as enumerated properties of the BigNumber
constructor.
</dd>
<dd>See <a href='#mod'><code>modulo</code></a>.</dd>
<dd>
<pre>BigNumber.config({ MODULO_MODE: BigNumber.EUCLID })
BigNumber.config({ MODULO_MODE: 9 }) // equivalent</pre>
</dd>
<dt id="pow-precision"><code><b>POW_PRECISION</b></code></dt>
<dd>
<i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive.<br />
Default value: <code>0</code>
</dd>
<dd>
The <i>maximum</i> precision, i.e. number of significant digits, of the result of the power
operation (unless a modulus is specified).
</dd>
<dd>If set to <code>0</code>, the number of significant digits will not be limited.</dd>
<dd>See <a href='#pow'><code>exponentiatedBy</code></a>.</dd>
<dd><pre>BigNumber.config({ POW_PRECISION: 100 })</pre></dd>
<dt id="format"><code><b>FORMAT</b></code></dt>
<dd><i>object</i></dd>
<dd>
The <code>FORMAT</code> object configures the format of the string returned by the
<a href='#toFor'><code>toFormat</code></a> method.
</dd>
<dd>
The example below shows the properties of the <code>FORMAT</code> object that are
recognised, and their default values.
</dd>
<dd>
Unlike the other configuration properties, the values of the properties of the
<code>FORMAT</code> object will not be checked for validity. The existing
<code>FORMAT</code> object will simply be replaced by the object that is passed in.
The object can include any number of the properties shown below.
</dd>
<dd>See <a href='#toFor'><code>toFormat</code></a> for examples of usage.</dd>
<dd>
<pre>
BigNumber.config({
FORMAT: {
// string to prepend
prefix: '',
// decimal separator
decimalSeparator: '.',
// grouping separator of the integer part
groupSeparator: ',',
// primary grouping size of the integer part
groupSize: 3,
// secondary grouping size of the integer part
secondaryGroupSize: 0,
// grouping separator of the fraction part
fractionGroupSeparator: ' ',
// grouping size of the fraction part
fractionGroupSize: 0,
// string to append
suffix: ''
}
});</pre>
</dd>
<dt id="alphabet"><code><b>ALPHABET</b></code></dt>
<dd>
<i>string</i><br />
Default value: <code>'0123456789abcdefghijklmnopqrstuvwxyz'</code>
</dd>
<dd>
The alphabet used for base conversion. The length of the alphabet corresponds to the
maximum value of the base argument that can be passed to the
<a href='#bignumber'><code>BigNumber</code></a> constructor or
<a href='#toS'><code>toString</code></a>.
</dd>
<dd>
There is no maximum length for the alphabet, but it must be at least 2 characters long, and
it must not contain whitespace or a repeated character, or the sign indicators
<code>'+'</code> and <code>'-'</code>, or the decimal separator <code>'.'</code>.
</dd>
<dd>
<pre>// duodecimal (base 12)
BigNumber.config({ ALPHABET: '0123456789TE' })
x = new BigNumber('T', 12)
x.toString() // '10'
x.toString(12) // 'T'</pre>
</dd>
</dl>
<br /><br />
<p>Returns an object with the above properties and their current values.</p>
<p>
Throws if <code>object</code> is not an object, or if an invalid value is assigned to
one or more of the above properties. See <a href='#Errors'>Errors</a>.
</p>
<pre>
BigNumber.config({
DECIMAL_PLACES: 40,
ROUNDING_MODE: BigNumber.ROUND_HALF_CEIL,
EXPONENTIAL_AT: [-10, 20],
RANGE: [-500, 500],
CRYPTO: true,
MODULO_MODE: BigNumber.ROUND_FLOOR,
POW_PRECISION: 80,
FORMAT: {
groupSize: 3,
groupSeparator: ' ',
decimalSeparator: ','
},
ALPHABET: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ$_'
});
obj = BigNumber.config();
obj.DECIMAL_PLACES // 40
obj.RANGE // [-500, 500]</pre>
<h5 id="isBigNumber">
isBigNumber<code class='inset'>.isBigNumber(value) <i>⇒ boolean</i></code>
</h5>
<p><code>value</code>: <i>any</i><br /></p>
<p>
Returns <code>true</code> if <code>value</code> is a BigNumber instance, otherwise returns
<code>false</code>.
</p>
<pre>x = 42
y = new BigNumber(x)
BigNumber.isBigNumber(x) // false
y instanceof BigNumber // true
BigNumber.isBigNumber(y) // true
BN = BigNumber.clone();
z = new BN(x)
z instanceof BigNumber // false
BigNumber.isBigNumber(z) // true</pre>
<p>
If <code>value</code> is a BigNumber instance and <code>BigNumber.DEBUG</code> is <code>true</code>,
then this method will also check if <code>value</code> is well-formed, and throw if it is not.
See <a href='#Errors'>Errors</a>.
</p>
<p>
The check can be useful if creating a BigNumber from an object literal.
See <a href='#bignumber'>BigNumber</a>.
</p>
<pre>
x = new BigNumber(10)
// Change x.c to an illegitimate value.
x.c = NaN
BigNumber.DEBUG = false
// No error.
BigNumber.isBigNumber(x) // true
BigNumber.DEBUG = true
// Error.
BigNumber.isBigNumber(x) // '[BigNumber Error] Invalid BigNumber'</pre>
<h5 id="max">maximum<code class='inset'>.max(n...) <i>⇒ BigNumber</i></code></h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<i>See <code><a href="#bignumber">BigNumber</a></code> for further parameter details.</i>
</p>
<p>
Returns a BigNumber whose value is the maximum of the arguments.
</p>
<p>The return value is always exact and unrounded.</p>
<pre>x = new BigNumber('3257869345.0378653')
BigNumber.maximum(4e9, x, '123456789.9') // '4000000000'
arr = [12, '13', new BigNumber(14)]
BigNumber.max.apply(null, arr) // '14'</pre>
<h5 id="min">minimum<code class='inset'>.min(n...) <i>⇒ BigNumber</i></code></h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<i>See <code><a href="#bignumber">BigNumber</a></code> for further parameter details.</i>
</p>
<p>
Returns a BigNumber whose value is the minimum of the arguments.
</p>
<p>The return value is always exact and unrounded.</p>
<pre>x = new BigNumber('3257869345.0378653')
BigNumber.minimum(4e9, x, '123456789.9') // '123456789.9'
arr = [2, new BigNumber(-14), '-15.9999', -12]
BigNumber.min.apply(null, arr) // '-15.9999'</pre>
<h5 id="random">
random<code class='inset'>.random([dp]) <i>⇒ BigNumber</i></code>
</h5>
<p><code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive</p>
<p>
Returns a new BigNumber with a pseudo-random value equal to or greater than <code>0</code> and
less than <code>1</code>.
</p>
<p>
The return value will have <code>dp</code> decimal places (or less if trailing zeros are
produced).<br />
If <code>dp</code> is omitted then the number of decimal places will default to the current
<a href='#decimal-places'><code>DECIMAL_PLACES</code></a> setting.
</p>
<p>
Depending on the value of this BigNumber constructor's
<a href='#crypto'><code>CRYPTO</code></a> setting and the support for the
<code>crypto</code> object in the host environment, the random digits of the return value are
generated by either <code>Math.random</code> (fastest), <code>crypto.getRandomValues</code>
(Web Cryptography API in recent browsers) or <code>crypto.randomBytes</code> (Node.js).
</p>
<p>
To be able to set <a href='#crypto'><code>CRYPTO</code></a> to <code>true</code> when using
Node.js, the <code>crypto</code> object must be available globally:
</p>
<pre>// Node.js
const crypto = require('crypto'); // CommonJS
import * as crypto from 'crypto'; // ES module
global.crypto = crypto;</pre>
<p>
If <a href='#crypto'><code>CRYPTO</code></a> is <code>true</code>, i.e. one of the
<code>crypto</code> methods is to be used, the value of a returned BigNumber should be
cryptographically-secure and statistically indistinguishable from a random value.
</p>
<p>
Throws if <code>dp</code> is invalid. See <a href='#Errors'>Errors</a>.
</p>
<pre>BigNumber.config({ DECIMAL_PLACES: 10 })
BigNumber.random() // '0.4117936847'
BigNumber.random(20) // '0.78193327636914089009'</pre>
<h5 id="sum">sum<code class='inset'>.sum(n...) <i>⇒ BigNumber</i></code></h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<i>See <code><a href="#bignumber">BigNumber</a></code> for further parameter details.</i>
</p>
<p>Returns a BigNumber whose value is the sum of the arguments.</p>
<p>The return value is always exact and unrounded.</p>
<pre>x = new BigNumber('3257869345.0378653')
BigNumber.sum(4e9, x, '123456789.9') // '7381326134.9378653'
arr = [2, new BigNumber(14), '15.9999', 12]
BigNumber.sum.apply(null, arr) // '43.9999'</pre>
<h4 id="constructor-properties">Properties</h4>
<p>
The library's enumerated rounding modes are stored as properties of the constructor.<br />
(They are not referenced internally by the library itself.)
</p>
<p>
Rounding modes <code>0</code> to <code>6</code> (inclusive) are the same as those of Java's
BigDecimal class.
</p>
<table>
<tr>
<th>Property</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td id="round-up"><b>ROUND_UP</b></td>
<td class='centre'>0</td>
<td>Rounds away from zero</td>
</tr>
<tr>
<td id="round-down"><b>ROUND_DOWN</b></td>
<td class='centre'>1</td>
<td>Rounds towards zero</td>
</tr>
<tr>
<td id="round-ceil"><b>ROUND_CEIL</b></td>
<td class='centre'>2</td>
<td>Rounds towards <code>Infinity</code></td>
</tr>
<tr>
<td id="round-floor"><b>ROUND_FLOOR</b></td>
<td class='centre'>3</td>
<td>Rounds towards <code>-Infinity</code></td>
</tr>
<tr>
<td id="round-half-up"><b>ROUND_HALF_UP</b></td>
<td class='centre'>4</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds away from zero
</td>
</tr>
<tr>
<td id="round-half-down"><b>ROUND_HALF_DOWN</b></td>
<td class='centre'>5</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards zero
</td>
</tr>
<tr>
<td id="round-half-even"><b>ROUND_HALF_EVEN</b></td>
<td class='centre'>6</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards even neighbour
</td>
</tr>
<tr>
<td id="round-half-ceil"><b>ROUND_HALF_CEIL</b></td>
<td class='centre'>7</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards <code>Infinity</code>
</td>
</tr>
<tr>
<td id="round-half-floor"><b>ROUND_HALF_FLOOR</b></td>
<td class='centre'>8</td>
<td>
Rounds towards nearest neighbour.<br />
If equidistant, rounds towards <code>-Infinity</code>
</td>
</tr>
</table>
<pre>
BigNumber.config({ ROUNDING_MODE: BigNumber.ROUND_CEIL })
BigNumber.config({ ROUNDING_MODE: 2 }) // equivalent</pre>
<h5 id="debug">DEBUG</h5>
<p><i>undefined|false|true</i></p>
<p>
If <code>BigNumber.DEBUG</code> is set <code>true</code> then an error will be thrown
if this <a href='#bignumber'>BigNumber</a> constructor receives an invalid value, such as
a value of type <em>number</em> with more than <code>15</code> significant digits.
See <a href='#bignumber'>BigNumber</a>.
</p>
<p>
An error will also be thrown if the <code><a href='#isBigNumber'>isBigNumber</a></code>
method receives a BigNumber that is not well-formed.
See <code><a href='#isBigNumber'>isBigNumber</a></code>.
</p>
<pre>BigNumber.DEBUG = true</pre>
<h3>INSTANCE</h3>
<h4 id="prototype-methods">Methods</h4>
<p>The methods inherited by a BigNumber instance from its constructor's prototype object.</p>
<p>A BigNumber is immutable in the sense that it is not changed by its methods. </p>
<p>
The treatment of ±<code>0</code>, ±<code>Infinity</code> and <code>NaN</code> is
consistent with how JavaScript treats these values.
</p>
<p>Many method names have a shorter alias.</p>
<h5 id="abs">absoluteValue<code class='inset'>.abs() <i>⇒ BigNumber</i></code></h5>
<p>
Returns a BigNumber whose value is the absolute value, i.e. the magnitude, of the value of
this BigNumber.
</p>
<p>The return value is always exact and unrounded.</p>
<pre>
x = new BigNumber(-0.8)
y = x.absoluteValue() // '0.8'
z = y.abs() // '0.8'</pre>
<h5 id="cmp">
comparedTo<code class='inset'>.comparedTo(n [, base]) <i>⇒ number</i></code>
</h5>
<p>
<code>n</code>: <i>number|string|BigNumber</i><br />
<code>base</code>: <i>number</i><br />
<i>See <a href="#bignumber">BigNumber</a> for further parameter details.</i>
</p>
<table>
<tr><th>Returns</th><th> </th></tr>
<tr>
<td class='centre'><code>1</code></td>
<td>If the value of this BigNumber is greater than the value of <code>n</code></td>
</tr>
<tr>
<td class='centre'><code>-1</code></td>
<td>If the value of this BigNumber is less than the value of <code>n</code></td>
</tr>
<tr>
<td class='centre'><code>0</code></td>
<td>If this BigNumber and <code>n</code> have the same value</td>
</tr>
<tr>
<td class='centre'><code>null</code></td>
<td>If the value of either this BigNumber or <code>n</code> is <code>NaN</code></td>
</tr>
</table>
<pre>
x = new BigNumber(Infinity)
y = new BigNumber(5)
x.comparedTo(y) // 1
x.comparedTo(x.minus(1)) // 0
y.comparedTo(NaN) // null
y.comparedTo('110', 2) // -1</pre>
<h5 id="dp">
decimalPlaces<code class='inset'>.dp([dp [, rm]]) <i>⇒ BigNumber|number</i></code>
</h5>
<p>
<code>dp</code>: <i>number</i>: integer, <code>0</code> to <code>1e+9</code> inclusive<br />
<code>rm</code>: <i>number</i>: integer, <code>0</code> to <code>8</code> inclusive
</p>
<p>
If <code>dp</code> is a number, returns a BigNumber whose value is the value of this BigNumber
rounded by rounding mode <code>rm</code> to a maximum of <code>dp</code> decimal places.
</p>
<p>
If <code>dp</code> is omitted, or is <code>null</code> or <code>undefined</code>, the return
value is the number of decimal places of the value of this BigNumber, or <code>null</code> if
the value of this BigNumber is ±<code>Infinity</code> or <code>NaN</code>.
</p>
<p>
If <code>rm</code> is omitted, or is <code>null</code> or <code>undefined</code>,
<a href='#rounding-mode'><code>ROUNDING_MODE</code></a> is used.
</p>