round-tofixed solves common problems when rounding decimal numbers in JavaScript:
- the Math.round() built-in function only rounds to integers
- commonly used rounding methods for decimal numbers produce incorrect results
Test results of rounding 1,040,000 random numbers that end with a '5':
| Method | Errors | Fraction of total | Avg Err Ratio |
|---|---|---|---|
| Number.toFixed | 93,686 | 9.008 % | 0.03391 |
| multiply-then-divide | 7,780 | 0.7481 % | 0.005592 |
| exponent +/- | 549 | 0.6602 % | NaN |
| round-tofixed | 0 | 0 % | 0 |
Node.js:
// using CommonJS
const roundToFixed = require("round-to-fixed");<!-- from an HTML file -->
<script src="round-tofixed.min.js"></script>Round a number to a fixed number of decimal places.
roundToFixed(num [, digits])num
(number) - The number to round off
digits
(positive integer) [optional]- the number of digits after decimal point
Defaults to zero.
(number) - The value of num rounded to digits decimal places. Returns NaN on invalid inputs.
round-tofixed avoids the problems of commonly used rounding methods, all of which produce incorrect results in certain cases.
The most commonly used method for rounding a decimal number is Number.toFixed:
Number.toFixed(digits)However, when a number ends in 5, it sometimes rounds in the wrong direction.
Another popular method is multiply-then-divide:
Math.round( x * (10 ** digits) ) / (10 ** digits);While more accurate than using Number.toFixed(), it still rounds numbers ending in 5 incorrectly.
A more accurate method is exponent add-and-subtract:
Math.round( x + 'e' + digits ) + 'e-' + digits;Exponent add-and-subtract rounds numbers correctly. But it has a fatal flaw—for input values smaller than 1e-6, it returns NaN.
round-tofixed uses the exponent add-and-subtract method, but it avoids the NaN result, rounding correctly for all values.
Because JavaScript numbers have about 16 digits of precision, round-tofixed produces inaccurate results with precision requests above 15.
MIT License
Copyright (c) 2020 Terry Morse
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.