Skip to content

Commit 369c5e5

Browse files
impawstarlightkgryte
impawstarlight
and
kgryte
authored
feat: add number/uint64/base/bigint2words
PR-URL: #13379 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Signed-off-by: Athan Reines <kgryte@gmail.com>
1 parent 49456e6 commit 369c5e5

13 files changed

Lines changed: 1080 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/number/uint64/base/bigint2words/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 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+
# bigint2words
22+
23+
> Split a bigint into the high and low 32-bit words of a 64-bit unsigned integer.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var bigint2words = require( '@stdlib/number/uint64/base/bigint2words' );
41+
```
42+
43+
#### bigint2words( value )
44+
45+
Splits a bigint into the high and low 32-bit words of a 64-bit unsigned integer.
46+
47+
```javascript
48+
var BigInt = require( '@stdlib/bigint/ctor' );
49+
50+
var w = bigint2words( BigInt( 1234 ) );
51+
// returns [ 0, 1234 ]
52+
```
53+
54+
The function returns an array containing two elements: a higher order word and a lower order word. The lower order word contains the less significant bits, while the higher order word contains the more significant bits.
55+
56+
#### bigint2words.assign( value, out, stride, offset )
57+
58+
Splits a bigint into the high and low 32-bit words of a 64-bit unsigned integer and assigns results to a provided output array.
59+
60+
```javascript
61+
var Uint32Array = require( '@stdlib/array/uint32' );
62+
var BigInt = require( '@stdlib/bigint/ctor' );
63+
64+
var out = new Uint32Array( 2 );
65+
// returns <Uint32Array>[ 0, 0 ]
66+
67+
var w = bigint2words.assign( BigInt( '18446744073709551615' ), out, 1, 0 );
68+
// returns <Uint32Array>[ 4294967295, 4294967295 ]
69+
70+
var bool = ( w === out );
71+
// returns true
72+
```
73+
74+
</section>
75+
76+
<!-- /.usage -->
77+
78+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
79+
80+
<section class="notes">
81+
82+
## Notes
83+
84+
- For accurate results, the input value should be an integer in the range \[`0`, `2^64-1`\].
85+
86+
</section>
87+
88+
<!-- /.notes -->
89+
90+
<!-- Package usage examples. -->
91+
92+
<section class="examples">
93+
94+
## Examples
95+
96+
```javascript
97+
var BigInt = require( '@stdlib/bigint/ctor' );
98+
var bigint2words = require( '@stdlib/number/uint64/base/bigint2words' );
99+
100+
var w = bigint2words( BigInt( 1234 ) );
101+
console.log( w );
102+
// => [ 0, 1234 ]
103+
104+
w = bigint2words( BigInt( 0x100000000 ) );
105+
console.log( w );
106+
// => [ 1, 0 ]
107+
108+
w = bigint2words( BigInt( '18446744073709551615' ) );
109+
console.log( w );
110+
// => [ 4294967295, 4294967295 ]
111+
```
112+
113+
</section>
114+
115+
<!-- /.examples -->
116+
117+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
118+
119+
<section class="related">
120+
121+
</section>
122+
123+
<!-- /.related -->
124+
125+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
126+
127+
<section class="links">
128+
129+
<!-- <related-links> -->
130+
131+
<!-- </related-links> -->
132+
133+
</section>
134+
135+
<!-- /.links -->

‎lib/node_modules/@stdlib/number/uint64/base/bigint2words/benchmark/benchmark.js‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 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 bench = require( '@stdlib/bench' );
24+
var Uint32Array = require( '@stdlib/array/uint32' );
25+
var isArray = require( '@stdlib/assert/is-array' );
26+
var hasBigIntSupport = require( '@stdlib/assert/has-bigint-support' );
27+
var UINT32_MAX = require( '@stdlib/constants/uint32/max' );
28+
var BigInt = require( '@stdlib/bigint/ctor' );
29+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
30+
var format = require( '@stdlib/string/format' );
31+
var pkg = require( './../package.json' ).name;
32+
var bigint2words = require( './../lib' );
33+
34+
35+
// VARIABLES //
36+
37+
var TWO_32 = 0x100000000; // 2^32
38+
var opts = {
39+
'skip': !hasBigIntSupport()
40+
};
41+
var options = {
42+
'dtype': 'uint32'
43+
};
44+
45+
46+
// MAIN //
47+
48+
bench( pkg, opts, function benchmark( b ) {
49+
var values;
50+
var N;
51+
var a;
52+
var i;
53+
var w;
54+
var x;
55+
56+
N = 100;
57+
x = discreteUniform( N, 0, UINT32_MAX, options );
58+
values = [];
59+
for ( i = 0; i < N; i++ ) {
60+
a = ( BigInt( x[ i ] ) * BigInt( TWO_32 ) ) + BigInt( x[ (i+1)%N ] );
61+
values.push( a );
62+
}
63+
64+
b.tic();
65+
for ( i = 0; i < b.iterations; i++ ) {
66+
w = bigint2words( values[ i % N ] );
67+
if ( typeof w !== 'object' ) {
68+
b.fail( 'should return an array' );
69+
}
70+
}
71+
b.toc();
72+
if ( !isArray( w ) ) {
73+
b.fail( 'should return an array' );
74+
}
75+
b.pass( 'benchmark finished' );
76+
b.end();
77+
});
78+
79+
bench( format( '%s:assign', pkg ), opts, function benchmark( b ) {
80+
var values;
81+
var out;
82+
var N;
83+
var a;
84+
var i;
85+
var w;
86+
var x;
87+
88+
N = 100;
89+
x = discreteUniform( N, 0, UINT32_MAX, options );
90+
values = [];
91+
for ( i = 0; i < N; i++ ) {
92+
a = ( BigInt( x[ i ] ) * BigInt( TWO_32 ) ) + BigInt( x[ (i+1)%N ] );
93+
values.push( a );
94+
}
95+
96+
out = new Uint32Array( 2 );
97+
98+
b.tic();
99+
for ( i = 0; i < b.iterations; i++ ) {
100+
w = bigint2words.assign( values[ i % N ], out, 1, 0 );
101+
if ( typeof w !== 'object' ) {
102+
b.fail( 'should return an array' );
103+
}
104+
}
105+
b.toc();
106+
if ( w !== out ) {
107+
b.fail( 'should return the output array' );
108+
}
109+
b.pass( 'benchmark finished' );
110+
b.end();
111+
});

‎lib/node_modules/@stdlib/number/uint64/base/bigint2words/docs/repl.txt‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
2+
{{alias}}( value )
3+
Splits a bigint into the high and low 32-bit words of a 64-bit unsigned
4+
integer.
5+
6+
The function returns an array with two elements: a higher order word and a
7+
lower order word, respectively. The lower order word contains the less
8+
significant bits, while the higher order word contains the more significant
9+
bits.
10+
11+
Parameters
12+
----------
13+
value: bigint
14+
Integer value in the range [0, 2^64-1].
15+
16+
Returns
17+
-------
18+
out: Array<integer>
19+
High and low words as 32-bit unsigned integers.
20+
21+
Examples
22+
--------
23+
> var w = {{alias}}( {{alias:@stdlib/bigint/ctor}}( 1234 ) )
24+
[ 0, 1234 ]
25+
26+
27+
{{alias}}.assign( value, out, stride, offset )
28+
Splits a bigint into the high and low 32-bit words of a 64-bit unsigned
29+
integer and assigns results to a provided output array.
30+
31+
Parameters
32+
----------
33+
value: bigint
34+
Integer value in the range [0, 2^64-1].
35+
36+
out: Array|TypedArray|Object
37+
Output array.
38+
39+
stride: integer
40+
Output array stride.
41+
42+
offset: integer
43+
Output array index offset.
44+
45+
Returns
46+
-------
47+
out: Array|TypedArray|Object
48+
Output array.
49+
50+
Examples
51+
--------
52+
> var out = new {{alias:@stdlib/array/uint32}}( 2 );
53+
> var w = {{alias}}.assign( {{alias:@stdlib/bigint/ctor}}( '18446744073709551615' ), out, 1, 0 )
54+
<Uint32Array>[ 4294967295, 4294967295 ]
55+
> var bool = ( w === out )
56+
true
57+
58+
See Also
59+
--------

0 commit comments

Comments
 (0)