truncn.js (5404B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2018 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var isnan = require( './../../../../base/assert/is-nan' ); 24 var isInfinite = require( './../../../../base/assert/is-infinite' ); 25 var pow = require( './../../../../base/special/pow' ); 26 var abs = require( './../../../../base/special/abs' ); 27 var trunc = require( './../../../../base/special/trunc' ); 28 var MAX_SAFE_INTEGER = require( '@stdlib/constants/float64/max-safe-integer' ); 29 var MAX_EXP = require( '@stdlib/constants/float64/max-base10-exponent' ); 30 var MIN_EXP = require( '@stdlib/constants/float64/min-base10-exponent' ); 31 var MIN_EXP_SUBNORMAL = require( '@stdlib/constants/float64/min-base10-exponent-subnormal' ); 32 33 34 // VARIABLES // 35 36 var MAX_INT = MAX_SAFE_INTEGER + 1; 37 var HUGE = 1.0e+308; 38 39 40 // MAIN // 41 42 /** 43 * Rounds a numeric value to the nearest multiple of \\(10^n\\) toward zero. 44 * 45 * ## Method 46 * 47 * 1. If \\(|x| <= 2^{53}\\) and \\(|n| <= 308\\), we can use the formula 48 * 49 * ```tex 50 * \operatorname{truncn}(x,n) = \frac{\operatorname{trunc}(x \cdot 10^{-n})}{10^{-n}} 51 * ``` 52 * 53 * which shifts the decimal to the nearest multiple of \\(10^n\\), performs a standard \\(\mathrm{trunc}\\) operation, and then shifts the decimal to its original position. 54 * 55 * <!-- <note> --> 56 * 57 * If \\(x \cdot 10^{-n}\\) overflows, \\(x\\) lacks a sufficient number of decimal digits to have any effect when rounding. Accordingly, the rounded value is \\(x\\). 58 * 59 * <!-- </note> --> 60 * 61 * <!-- <note> --> 62 * 63 * Note that rescaling \\(x\\) can result in unexpected behavior due to the fact that most decimal fractions cannot be exactly represented as floating-point numbers. And further, rescaling can lead to slightly different fractional values, which, in turn, affects the result of \\(\mathrm{trunc}\\). 64 * 65 * <!-- </note> --> 66 * 67 * 2. If \\(n > 308\\), we recognize that the maximum absolute double-precision floating-point number is \\(\approx 1.8\mbox{e}308\\) and, thus, the result of rounding any possible finite number \\(x\\) to the nearest \\(10^n\\) is \\(0\\). To ensure consistent behavior with \\(\operatorname{trunc}(x)\\), the sign of \\(x\\) is preserved. 68 * 69 * 3. If \\(n < -324\\), \\(n\\) exceeds the maximum number of possible decimal places (such as with subnormal numbers), and, thus, the rounded value is \\(x\\). 70 * 71 * 4. If \\(x > 2^{53}\\), \\(x\\) is **always** an integer (i.e., \\(x\\) has no decimal digits). If \\(n <= 0\\), the rounded value is \\(x\\). 72 * 73 * 5. If \\(n < -308\\), we let \\(m = n + 308\\) and modify the above formula to avoid overflow. 74 * 75 * ```tex 76 * \operatorname{truncn}(x,n) = \frac{\biggl(\frac{\operatorname{trunc}( (x \cdot 10^{308}) 10^{-m})}{10^{308}}\biggr)}{10^{-m}} 77 * ``` 78 * 79 * If overflow occurs, the rounded value is \\(x\\). 80 * 81 * 82 * ## Special Cases 83 * 84 * ```tex 85 * \begin{align*} 86 * \operatorname{truncn}(\mathrm{NaN}, n) &= \mathrm{NaN} \\ 87 * \operatorname{truncn}(x, \mathrm{NaN}) &= \mathrm{NaN} \\ 88 * \operatorname{truncn}(x, \pm\infty) &= \mathrm{NaN} \\ 89 * \operatorname{truncn}(\pm\infty, n) &= \pm\infty \\ 90 * \operatorname{truncn}(\pm 0, n) &= \pm 0 91 * \end{align*} 92 * ``` 93 * 94 * 95 * @param {number} x - input value 96 * @param {integer} n - integer power of `10` 97 * @returns {number} rounded value 98 * 99 * @example 100 * // Round a value to 4 decimal places: 101 * var v = truncn( 3.141592653589793, -4 ); 102 * // returns 3.1415 103 * 104 * @example 105 * // If n = 0, `truncn` behaves like `trunc`: 106 * var v = truncn( 3.141592653589793, 0 ); 107 * // returns 3.0 108 * 109 * @example 110 * // Round a value to the nearest thousand: 111 * var v = truncn( 12368.0, 3 ); 112 * // returns 12000.0 113 */ 114 function truncn( x, n ) { 115 var s; 116 var y; 117 if ( 118 isnan( x ) || 119 isnan( n ) || 120 isInfinite( n ) 121 ) { 122 return NaN; 123 } 124 if ( 125 // Handle infinities... 126 isInfinite( x ) || 127 128 // Handle +-0... 129 x === 0.0 || 130 131 // If `n` exceeds the maximum number of feasible decimal places (such as with subnormal numbers), nothing to truncate... 132 n < MIN_EXP_SUBNORMAL || 133 134 // If `|x|` is large enough, no decimals to truncate... 135 ( abs( x ) > MAX_INT && n <= 0 ) 136 ) { 137 return x; 138 } 139 // The maximum absolute double is ~1.8e308. Accordingly, any possible positive finite `x` rounded to the nearest >=10^309 is zero. 140 if ( n > MAX_EXP ) { 141 return 0.0 * x; // preserve the sign (same behavior as trunc) 142 } 143 // If we overflow, return `x`, as the number of digits to the right of the decimal is too small (i.e., `x` is too large / lacks sufficient fractional precision) for there to be any effect when rounding... 144 if ( n < MIN_EXP ) { 145 s = pow( 10.0, -(n + MAX_EXP) ); 146 y = (x*HUGE) * s; // order of operation matters! 147 if ( isInfinite( y ) ) { 148 return x; 149 } 150 return ( trunc(y)/HUGE ) / s; 151 } 152 s = pow( 10.0, -n ); 153 y = x * s; 154 if ( isInfinite( y ) ) { 155 return x; 156 } 157 return trunc( y ) / s; 158 } 159 160 161 // EXPORTS // 162 163 module.exports = truncn;