Skip to content

Commit 4ebe63d

Browse files
steff456kgryte
steff456
and
kgryte
authored
Refactor normalize API to provide an assign method (stdlib-js#532)
* Refactor normalize API * Add empty line to separate imports from example code * Add empty line to separate returns annotation from rest of example code * Update type * Add empty line * Update description * Update description * Update packages to the new normalize API * Fix signature * Fix method call * Fix import Co-authored-by: Athan <kgryte@gmail.com>
1 parent 6fd2837 commit 4ebe63d

13 files changed

Lines changed: 460 additions & 250 deletions

File tree

‎lib/node_modules/@stdlib/math/base/special/frexp/lib/frexp.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2424
var isInfinite = require( '@stdlib/math/base/assert/is-infinite' );
25-
var normalize = require( '@stdlib/number/float64/base/normalize' );
25+
var normalize = require( '@stdlib/number/float64/base/normalize' ).assign;
2626
var floatExp = require( '@stdlib/number/float64/base/exponent' );
2727
var toWords = require( '@stdlib/number/float64/base/to-words' );
2828
var fromWords = require( '@stdlib/number/float64/base/from-words' );
@@ -90,7 +90,7 @@ function frexp( out, x ) {
9090
return out;
9191
}
9292
// If `x` is subnormal, normalize it...
93-
normalize( X, x );
93+
normalize( x, X, 1, 0 );
9494

9595
// Extract the exponent from `x` and add the normalization exponent:
9696
exp = floatExp( X[0] ) + X[ 1 ] + 1;

‎lib/node_modules/@stdlib/math/base/special/ldexp/lib/main.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ var MIN_SUBNORMAL_EXPONENT = require( '@stdlib/constants/float64/min-base2-expon
3636
var isnan = require( '@stdlib/math/base/assert/is-nan' );
3737
var isInfinite = require( '@stdlib/math/base/assert/is-infinite' );
3838
var copysign = require( '@stdlib/math/base/special/copysign' );
39-
var normalize = require( '@stdlib/number/float64/base/normalize' );
39+
var normalize = require( '@stdlib/number/float64/base/normalize' ).assign;
4040
var floatExp = require( '@stdlib/number/float64/base/exponent' );
4141
var toWords = require( '@stdlib/number/float64/base/to-words' );
4242
var fromWords = require( '@stdlib/number/float64/base/from-words' );
@@ -106,7 +106,7 @@ function ldexp( frac, exp ) {
106106
return frac;
107107
}
108108
// Normalize the input fraction:
109-
normalize( FRAC, frac );
109+
normalize( frac, FRAC, 1, 0 );
110110
frac = FRAC[ 0 ];
111111
exp += FRAC[ 1 ];
112112

‎lib/node_modules/@stdlib/number/float64/base/normalize/README.md‎

Lines changed: 17 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -30,17 +30,10 @@ limitations under the License.
3030
var normalize = require( '@stdlib/number/float64/base/normalize' );
3131
```
3232

33-
#### normalize( \[out,] x )
33+
#### normalize( x )
3434

3535
Returns a normal number `y` and exponent `exp` satisfying `x = y * 2^exp`.
3636

37-
```javascript
38-
var out = normalize( 3.14e-319 );
39-
// returns [ 1.4141234400356668e-303, -52 ]
40-
```
41-
42-
By default, the function returns `y` and `exp` as a two-element `array`.
43-
4437
```javascript
4538
var pow = require( '@stdlib/math/base/special/pow' );
4639

@@ -54,20 +47,6 @@ var bool = ( y*pow(2.0, exp) === 3.14e-319 );
5447
// returns true
5548
```
5649

57-
To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
58-
59-
```javascript
60-
var Float64Array = require( '@stdlib/array/float64' );
61-
62-
var out = new Float64Array( 2 );
63-
64-
var v = normalize( out, 3.14e-319 );
65-
// returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
66-
67-
var bool = ( v === out );
68-
// returns true
69-
```
70-
7150
The function expects a finite, non-zero `numeric` value `x`. If `x == 0`,
7251

7352
```javascript
@@ -91,6 +70,22 @@ out = normalize( NaN );
9170
// returns [ NaN, 0 ]
9271
```
9372

73+
#### normalize.assign( x, out, stride, offset )
74+
75+
Returns a normal number `y` and exponent `exp` satisfying `x = y * 2^exp` and assigns results to a provided output array.
76+
77+
```javascript
78+
var Float64Array = require( '@stdlib/array/float64' );
79+
80+
var out = new Float64Array( 2 );
81+
82+
var v = normalize.assign( 3.14e-319, out, 1, 0);
83+
// returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
84+
85+
var bool = ( v === out );
86+
// returns true
87+
```
88+
9489
</section>
9590

9691
<!-- /.usage -->

‎lib/node_modules/@stdlib/number/float64/base/normalize/benchmark/benchmark.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ bench( pkg, function benchmark( b ) {
5050
b.end();
5151
});
5252

53-
bench( pkg+'::memory_reuse', function benchmark( b ) {
53+
bench( pkg+'::assign', function benchmark( b ) {
5454
var out;
5555
var x;
5656
var y;
@@ -61,7 +61,7 @@ bench( pkg+'::memory_reuse', function benchmark( b ) {
6161
b.tic();
6262
for ( i = 0; i < b.iterations; i++ ) {
6363
x = ( randu()*1.0e7 ) - 5.0e6;
64-
y = normalize( out, x );
64+
y = normalize.assign( x, out, 1, 0 );
6565
if ( typeof y !== 'object' ) {
6666
b.fail( 'should return an array' );
6767
}

‎lib/node_modules/@stdlib/number/float64/base/normalize/docs/repl.txt‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
11

2-
{{alias}}( [out,] x )
2+
{{alias}}( x )
33
Returns a normal number and exponent satisfying `x = y * 2^exp` as an array.
44

55
The first element of the returned array corresponds to `y` and the second to
66
`exp`.
77

88
Parameters
99
----------
10-
out: Array|TypedArray|Object (optional)
11-
Output array.
12-
1310
x: number
1411
Double-precision floating-point number.
1512

1613
Returns
1714
-------
18-
out: Array|TypedArray|Object
15+
out: Array<number>
1916
An array containing `y` and `exp`.
2017

2118
Examples
@@ -37,9 +34,37 @@
3734
> out = {{alias}}( NaN )
3835
[ NaN, 0 ]
3936

40-
// Provide an output array:
41-
> out = new {{alias:@stdlib/array/float64}}( 2 );
42-
> var v = {{alias}}( out, 3.14e-319 )
37+
38+
{{alias}}.assign( x, out, stride, offset )
39+
Returns a normal number and exponent satisfying `x = y * 2^exp` and assigns
40+
results to a provided output array.
41+
42+
The first element of the returned array corresponds to `y` and the second to
43+
`exp`.
44+
45+
Parameters
46+
----------
47+
x: number
48+
Double-precision floating-point number.
49+
50+
out: Array|TypedArray|Object
51+
Output array.
52+
53+
stride: integer
54+
Output array stride.
55+
56+
offset: integer
57+
Output array index offset.
58+
59+
Returns
60+
-------
61+
out: Array|TypedArray|Object
62+
Output array.
63+
64+
Examples
65+
--------
66+
> var out = new {{alias:@stdlib/array/float64}}( 2 )
67+
> var v = {{alias}}.assign( 3.14e-319, out, 1, 0 )
4368
<Float64Array>[ 1.4141234400356668e-303, -52 ]
4469
> bool = ( v === out )
4570
true

‎lib/node_modules/@stdlib/number/float64/base/normalize/docs/types/index.d.ts‎

Lines changed: 68 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -23,77 +23,88 @@
2323
import { ArrayLike } from '@stdlib/types/array';
2424

2525
/**
26-
* Returns a normal number `y` and exponent `exp` satisfying \\(x = y \cdot 2^\mathrm{exp}\\).
27-
*
28-
* @param out - output array
29-
* @param x - input value
30-
* @returns output array
31-
*
32-
* @example
33-
* var Float64Array = require( `@stdlib/array/float64` );
34-
* var pow = require( `@stdlib/math/base/special/pow` );
35-
*
36-
* var out = new Float64Array( 2 );
37-
*
38-
* var v = normalize( out, 3.14e-319 );
39-
* // returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
40-
*
41-
* var bool = ( v === out );
42-
* // returns true
43-
*
44-
* @example
45-
* var out = normalize( [ 0.0, 0 ], 0.0 );
46-
* // returns [ 0.0, 0 ]
47-
*
48-
* @example
49-
* var out = normalize( [ 0.0, 0 ], Infinity );
50-
* // returns [ Infinity, 0 ]
51-
*
52-
* @example
53-
* var out = normalize( [ 0.0, 0 ], -Infinity );
54-
* // returns [ -Infinity, 0 ]
55-
*
56-
* @example
57-
* var out = normalize( [ 0.0, 0 ], NaN );
58-
* // returns [ NaN, 0 ]
59-
*/
60-
declare function normalize( out: ArrayLike<number>, x: number ): ArrayLike<number>; // tslint-disable-line max-line-length
26+
* Interface describing `normalize`.
27+
*/
28+
interface Normalize {
29+
/**
30+
* Returns a normal number `y` and exponent `exp` satisfying \\(x = y \cdot 2^\mathrm{exp}\\).
31+
*
32+
* The first element of the returned array corresponds to `y` and the second to `exp`.
33+
*
34+
* @param x - input value
35+
* @returns output array
36+
*
37+
* @example
38+
* var pow = require( `@stdlib/math/base/special/pow` );
39+
*
40+
* var out = normalize( 3.14e-319 );
41+
* // returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
42+
*
43+
* var y = out[ 0 ];
44+
* var exponent = out[ 1 ];
45+
* var bool = ( y*pow(2.0, exponent) === 3.14e-319 );
46+
* // returns true
47+
*
48+
* @example
49+
* var out = normalize( 0.0 );
50+
* // returns [ 0.0, 0 ]
51+
*
52+
* @example
53+
* var out = normalize( Infinity );
54+
* // returns [ Infinity, 0 ]
55+
*
56+
* @example
57+
* var out = normalize( -Infinity );
58+
* // returns [ -Infinity, 0 ]
59+
*
60+
* @example
61+
* var out = normalize( NaN );
62+
* // returns [ NaN, 0 ]
63+
*/
64+
( x: number ): ArrayLike<number>;
65+
66+
/**
67+
* Returns a normal number and exponent satisfying `x = y * 2^exp` and assigns results to a provided output array.
68+
*
69+
* The first element of the returned array corresponds to `y` and the second to `exp`.
70+
*
71+
* @param x - input value
72+
* @param out - output array
73+
* @param stride - output array stride
74+
* @param offset - output array index offset
75+
* @returns output array
76+
*
77+
* @example
78+
* var out = new Float64Array( 2 );
79+
*
80+
* var v = normalize.assign( 3.14e-319, out, 1, 0 );
81+
* // returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
82+
*
83+
* var bool = ( v === out );
84+
* // returns true
85+
*/
86+
assign( x: number, out: ArrayLike<any>, stride: number, offset: number ): ArrayLike<number>; // tslint-disable-line max-line-length
87+
}
6188

6289
/**
6390
* Returns a normal number `y` and exponent `exp` satisfying \\(x = y \cdot 2^\mathrm{exp}\\).
6491
*
92+
* The first element of the returned array corresponds to `y` and the second to `exp`.
93+
*
6594
* @param x - input value
6695
* @returns output array
6796
*
6897
* @example
6998
* var pow = require( `@stdlib/math/base/special/pow` );
70-
*
7199
* var out = normalize( 3.14e-319 );
72-
* // returns [ 1.4141234400356668e-303, -52 ]
100+
* // returns <Float64Array>[ 1.4141234400356668e-303, -52 ]
73101
*
74102
* var y = out[ 0 ];
75-
* var exp = out[ 1 ];
76-
*
77-
* var bool = ( y*pow(2.0,exp) === 3.14e-319 );
103+
* var exponent = out[ 1 ];
104+
* var bool = ( y*pow(2.0, exponent) === 3.14e-319 );
78105
* // returns true
79-
*
80-
* @example
81-
* var out = normalize( 0.0 );
82-
* // returns [ 0.0, 0 ]
83-
*
84-
* @example
85-
* var out = normalize( Infinity );
86-
* // returns [ Infinity, 0 ]
87-
*
88-
* @example
89-
* var out = normalize( -Infinity );
90-
* // returns [ -Infinity, 0 ]
91-
*
92-
* @example
93-
* var out = normalize( NaN );
94-
* // returns [ NaN, 0 ]
95106
*/
96-
declare function normalize( x: number ): ArrayLike<number>;
107+
declare var normalize: Normalize;
97108

98109

99110
// EXPORTS //

0 commit comments

Comments
 (0)