| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201 |
- # big.js
- **A small, fast JavaScript library for arbitrary-precision decimal arithmetic.**
- The little sister to [bignumber.js](https://github.com/MikeMcl/bignumber.js/) and [decimal.js](https://github.com/MikeMcl/decimal.js/). See [here](https://github.com/MikeMcl/big.js/wiki) for some notes on the difference between them.
- ## Features
- - Faster, smaller and easier-to-use than JavaScript versions of Java's BigDecimal
- - Only 5.9 KB minified and 2.7 KB gzipped
- - Simple API
- - Replicates the `toExponential`, `toFixed` and `toPrecision` methods of JavaScript's Number type
- - Includes a `sqrt` method
- - Stores values in an accessible decimal floating point format
- - No dependencies
- - Comprehensive [documentation](http://mikemcl.github.io/big.js/) and test set
- ## Set up
- The library is the single JavaScript file *big.js* (or *big.min.js*, which is *big.js* minified).
- Browser:
- ```html
- <script src='path/to/big.js'></script>
- ```
- [Node.js](http://nodejs.org):
- ```bash
- $ npm install big.js
- ```
- ```javascript
- const Big = require('big.js');
- ```
- ES6 module:
- ```javascript
- import Big from 'big.mjs';
- ```
- ## Use
- *In all examples below, `var`, semicolons and `toString` calls are not shown. If a commented-out value is in quotes it means `toString` has been called on the preceding expression.*
- The library exports a single function, `Big`, the constructor of Big number instances.
- It accepts a value of type number, string or Big number object.
- x = new Big(123.4567)
- y = Big('123456.7e-3') // 'new' is optional
- z = new Big(x)
- x.eq(y) && x.eq(z) && y.eq(z) // true
- A Big number is immutable in the sense that it is not changed by its methods.
- 0.3 - 0.1 // 0.19999999999999998
- x = new Big(0.3)
- x.minus(0.1) // "0.2"
- x // "0.3"
- The methods that return a Big number can be chained.
- x.div(y).plus(z).times(9).minus('1.234567801234567e+8').plus(976.54321).div('2598.11772')
- x.sqrt().div(y).pow(3).gt(y.mod(z)) // true
- Like JavaScript's Number type, there are `toExponential`, `toFixed` and `toPrecision` methods.
- x = new Big(255.5)
- x.toExponential(5) // "2.55500e+2"
- x.toFixed(5) // "255.50000"
- x.toPrecision(5) // "255.50"
- The arithmetic methods always return the exact result except `div`, `sqrt` and `pow`
- (with negative exponent), as these methods involve division.
- The maximum number of decimal places and the rounding mode used to round the results of these methods is determined by the value of the `DP` and `RM` properties of the `Big` number constructor.
- Big.DP = 10
- Big.RM = 1
- x = new Big(2);
- y = new Big(3);
- z = x.div(y) // "0.6666666667"
- z.sqrt() // "0.8164965809"
- z.pow(-3) // "3.3749999995"
- z.times(z) // "0.44444444448888888889"
- z.times(z).round(10) // "0.4444444445"
- Multiple Big number constructors can be created, each with an independent configuration.
- The value of a Big number is stored in a decimal floating point format in terms of a coefficient, exponent and sign.
- x = new Big(-123.456);
- x.c // [1,2,3,4,5,6] coefficient (i.e. significand)
- x.e // 2 exponent
- x.s // -1 sign
- For further information see the [API](http://mikemcl.github.io/big.js/) reference from the *doc* folder.
- ## Test
- The *test* directory contains the test scripts for each Big number method.
- The tests can be run with Node.js or a browser.
- To run all the tests
- $ npm test
- To test a single method
- $ node test/toFixed
- For the browser, see *single-test.html* and *every-test.html* in the *test/browser* directory.
- *big-vs-number.html* is a simple application that enables some of the methods of big.js to be compared with those of JavaScript's Number type.
- ## Performance
- The *perf* directory contains two legacy applications and a *lib* directory containing the BigDecimal libraries used by both.
- *big-vs-bigdecimal.html* tests the performance of big.js against the JavaScript translations of two versions of BigDecimal, its use should be more or less self-explanatory.
- * [GWT: java.math.BigDecimal](https://github.com/iriscouch/bigdecimal.js)
- * [ICU4J: com.ibm.icu.math.BigDecimal](https://github.com/dtrebbien/BigDecimal.js)
- The BigDecimal in the npm registry is the GWT version. It has some bugs, see the Node.js script *perf/lib/bigdecimal_GWT/bugs.js* for examples of flaws in its *remainder*, *divide* and *compareTo* methods.
- *bigtime.js* is a Node.js command-line application which tests the performance of big.js against the GWT version of
- BigDecimal from the npm registry.
- For example, to compare the time taken by the big.js `plus` method and the BigDecimal `add` method
- $ node bigtime plus 10000 40
- This will time 10000 calls to each, using operands of up to 40 random digits and will check that the results match.
- For help
- $ node bigtime -h
- ## Build
- If [uglify-js](https://github.com/mishoo/UglifyJS2) is installed globally
- $ npm install uglify-js -g
- then
- $ npm run build
- will create *big.min.js*.
- ## TypeScript
- The [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped) project has a Typescript type definitions file for big.js.
- $ npm install @types/big.js
- Any questions about the TypeScript type definitions file should be addressed to the DefinitelyTyped project.
- ## Feedback
- Bugs/comments/questions?
- Open an issue, or email <a href="mailto:M8ch88l@gmail.com">Michael</a>
- ## Licence
- [MIT](LICENCE)
- ## Contributors
- This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
- <a href="graphs/contributors"><img src="https://opencollective.com/bigjs/contributors.svg?width=890&button=false" /></a>
- ## Backers
- Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/bigjs#backer)]
- <a href="https://opencollective.com/bigjs#backers" target="_blank"><img src="https://opencollective.com/bigjs/backers.svg?width=890"></a>
- ## Sponsors
- Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/bigjs#sponsor)]
- <a href="https://opencollective.com/bigjs/sponsor/0/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/0/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/1/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/1/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/2/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/2/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/3/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/3/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/4/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/4/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/5/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/5/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/6/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/6/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/7/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/7/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/8/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/8/avatar.svg"></a>
- <a href="https://opencollective.com/bigjs/sponsor/9/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/9/avatar.svg"></a>
|
