time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (3706B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 The Stdlib Authors.
      6 
      7 Licensed under the Apache License, Version 2.0 (the "License");
      8 you may not use this file except in compliance with the License.
      9 You may obtain a copy of the License at
     10 
     11    http://www.apache.org/licenses/LICENSE-2.0
     12 
     13 Unless required by applicable law or agreed to in writing, software
     14 distributed under the License is distributed on an "AS IS" BASIS,
     15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16 See the License for the specific language governing permissions and
     17 limitations under the License.
     18 
     19 -->
     20 
     21 # Normalize
     22 
     23 > Return a normal number `y` and exponent `exp` satisfying `x = y * 2^exp`.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var normalizef = require( '@stdlib/number/float32/base/normalize' );
     31 ```
     32 
     33 #### normalizef( \[out,] x )
     34 
     35 Returns a normal number `y` and exponent `exp` satisfying `x = y * 2^exp`.
     36 
     37 ```javascript
     38 var toFloat32 = require( '@stdlib/number/float64/base/to-float32' );
     39 
     40 var out = normalizef( toFloat32( 1.401e-45 ) );
     41 // returns [ 1.1754943508222875e-38, -23 ]
     42 ```
     43 
     44 By default, the function returns `y` and `exp` as a two-element `array`.
     45 
     46 ```javascript
     47 var toFloat32 = require( '@stdlib/number/float64/base/to-float32' );
     48 var pow = require( '@stdlib/math/base/special/pow' );
     49 
     50 var out = normalizef( toFloat32( 1.401e-45 ) );
     51 // returns [ 1.1754943508222875e-38, -23 ]
     52 
     53 var y = out[ 0 ];
     54 var exp = out[ 1 ];
     55 
     56 var bool = ( y*pow(2, exp) === toFloat32(1.401e-45) );
     57 // returns true
     58 ```
     59 
     60 To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
     61 
     62 ```javascript
     63 var toFloat32 = require( '@stdlib/number/float64/base/to-float32' );
     64 var Float32Array = require( '@stdlib/array/float32' );
     65 
     66 var out = new Float32Array( 2 );
     67 
     68 var v = normalizef( out, toFloat32( 1.401e-45 ) );
     69 // returns <Float32Array>[ 1.1754943508222875e-38, -23 ]
     70 
     71 var bool = ( v === out );
     72 // returns true
     73 ```
     74 
     75 The function expects a finite, non-zero [single-precision floating-point number][ieee754] `x`. If `x == 0`,
     76 
     77 ```javascript
     78 var out = normalizef( 0.0 );
     79 // returns [ 0.0, 0 ];
     80 ```
     81 
     82 If `x` is either positive or negative `infinity` or `NaN`,
     83 
     84 ```javascript
     85 var PINF = require( '@stdlib/constants/float32/pinf' );
     86 var NINF = require( '@stdlib/constants/float32/ninf' );
     87 
     88 var out = normalizef( PINF );
     89 // returns [ Infinity, 0 ]
     90 
     91 out = normalizef( NINF );
     92 // returns [ -Infinity, 0 ]
     93 
     94 out = normalizef( NaN );
     95 // returns [ NaN, 0 ]
     96 ```
     97 
     98 </section>
     99 
    100 <!-- /.usage -->
    101 
    102 <section class="notes">
    103 
    104 ## Notes
    105 
    106 -   While the function accepts higher precision [floating-point numbers][ieee754], beware that providing such numbers can be a source of subtle bugs as the relation `x = y * 2^exp` may **not** hold.
    107 
    108 </section>
    109 
    110 <!-- /.notes -->
    111 
    112 <section class="examples">
    113 
    114 ## Examples
    115 
    116 <!-- eslint no-undef: "error" -->
    117 
    118 ```javascript
    119 var randu = require( '@stdlib/random/base/randu' );
    120 var round = require( '@stdlib/math/base/special/round' );
    121 var pow = require( '@stdlib/math/base/special/pow' );
    122 var toFloat32 = require( '@stdlib/number/float64/base/to-float32' );
    123 var normalizef = require( '@stdlib/number/float32/base/normalize' );
    124 
    125 var frac;
    126 var exp;
    127 var x;
    128 var v;
    129 var i;
    130 
    131 // Generate denormalized single-precision floating-point numbers and then normalize them...
    132 for ( i = 0; i < 100; i++ ) {
    133     frac = randu() * 10.0;
    134     exp = 38 + round( randu()*6.0 );
    135     x = frac * pow( 10.0, -exp );
    136     x = toFloat32( x );
    137     v = normalizef( x );
    138     console.log( '%d = %d * 2^%d = %d', x, v[0], v[1], v[0]*pow(2.0, v[1]) );
    139 }
    140 ```
    141 
    142 </section>
    143 
    144 <!-- /.examples -->
    145 
    146 <section class="links">
    147 
    148 [ieee754]: https://en.wikipedia.org/wiki/IEEE_754-1985
    149 
    150 </section>
    151 
    152 <!-- /.links -->