Skip to content

Commit be023a5

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/base/reinterpret-boolean
PR-URL: #11707 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Closes: stdlib-js/metr-issue-tracker#271
1 parent 7c287ff commit be023a5

10 files changed

Lines changed: 754 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-boolean/README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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+
# reinterpretBoolean
22+
23+
> Reinterpret a boolean [ndarray][@stdlib/ndarray/base/ctor] as an unsigned 8-bit integer [ndarray][@stdlib/ndarray/base/ctor].
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var reinterpretBoolean = require( '@stdlib/ndarray/base/reinterpret-boolean' );
37+
```
38+
39+
#### reinterpretBoolean( x )
40+
41+
Reinterprets a boolean [ndarray][@stdlib/ndarray/base/ctor] as an unsigned 8-bit integer [ndarray][@stdlib/ndarray/base/ctor].
42+
43+
```javascript
44+
var falses = require( '@stdlib/ndarray/base/falses' );
45+
46+
var x = falses( 'bool', [ 2, 2 ], 'row-major' );
47+
// returns <ndarray>[ [ false, false ], [ false, false ] ]
48+
49+
var out = reinterpretBoolean( x );
50+
// returns <ndarray>[ [ 0, 0 ], [ 0, 0 ] ]
51+
```
52+
53+
</section>
54+
55+
<!-- /.usage -->
56+
57+
<section class="notes">
58+
59+
## Notes
60+
61+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a view on the input [ndarray][@stdlib/ndarray/base/ctor] data buffer.
62+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a "base" [ndarray][@stdlib/ndarray/base/ctor], and, thus, the returned [ndarray][@stdlib/ndarray/base/ctor] does not perform bounds checking or afford any of the guarantees of the non-base [ndarray][@stdlib/ndarray/ctor] constructor. The primary intent of this function is to reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead.
63+
64+
</section>
65+
66+
<!-- /.notes -->
67+
68+
<section class="examples">
69+
70+
## Examples
71+
72+
<!-- eslint no-undef: "error" -->
73+
74+
```javascript
75+
var bernoulli = require( '@stdlib/random/array/bernoulli' );
76+
var BooleanArray = require( '@stdlib/array/bool' );
77+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
78+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
79+
var reinterpretBoolean = require( '@stdlib/ndarray/base/reinterpret-boolean' );
80+
81+
// Create a boolean ndarray:
82+
var buf = new BooleanArray( bernoulli( 4, 0.5 ) );
83+
var x = ndarray( 'bool', buf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
84+
85+
// Reinterpret as an unsigned 8-bit integer ndarray:
86+
var out = reinterpretBoolean( x );
87+
console.log( ndarray2array( out ) );
88+
```
89+
90+
</section>
91+
92+
<!-- /.examples -->
93+
94+
<section class="references">
95+
96+
</section>
97+
98+
<!-- /.references -->
99+
100+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
101+
102+
<section class="related">
103+
104+
</section>
105+
106+
<!-- /.related -->
107+
108+
<section class="links">
109+
110+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
111+
112+
[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/ctor
113+
114+
</section>
115+
116+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-boolean/benchmark/benchmark.js‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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 BooleanArray = require( '@stdlib/array/bool' );
25+
var ndarrayBase = require( '@stdlib/ndarray/base/ctor' );
26+
var ndarray = require( '@stdlib/ndarray/ctor' );
27+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
28+
var format = require( '@stdlib/string/format' );
29+
var pkg = require( './../package.json' ).name;
30+
var reinterpretBoolean = require( './../lib' );
31+
32+
33+
// MAIN //
34+
35+
bench( format( '%s::base_ndarray,2d', pkg ), function benchmark( b ) {
36+
var strides;
37+
var values;
38+
var buffer;
39+
var offset;
40+
var dtype;
41+
var shape;
42+
var order;
43+
var out;
44+
var i;
45+
46+
dtype = 'bool';
47+
buffer = new BooleanArray( 4 );
48+
shape = [ 2, 2 ];
49+
strides = [ 2, 1 ];
50+
offset = 0;
51+
order = 'row-major';
52+
53+
values = [
54+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
55+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
56+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
57+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
58+
ndarrayBase( dtype, buffer, shape, strides, offset, order )
59+
];
60+
61+
b.tic();
62+
for ( i = 0; i < b.iterations; i++ ) {
63+
out = reinterpretBoolean( values[ i%values.length ] );
64+
if ( typeof out !== 'object' ) {
65+
b.fail( 'should return an object' );
66+
}
67+
}
68+
b.toc();
69+
if ( !isndarrayLike( out ) ) {
70+
b.fail( 'should return an ndarray' );
71+
}
72+
b.pass( 'benchmark finished' );
73+
b.end();
74+
});
75+
76+
bench( format( '%s::ndarray,2d', pkg ), function benchmark( b ) {
77+
var strides;
78+
var values;
79+
var buffer;
80+
var offset;
81+
var dtype;
82+
var shape;
83+
var order;
84+
var out;
85+
var i;
86+
87+
dtype = 'bool';
88+
buffer = new BooleanArray( 4 );
89+
shape = [ 2, 2 ];
90+
strides = [ 2, 1 ];
91+
offset = 0;
92+
order = 'row-major';
93+
94+
values = [
95+
ndarray( dtype, buffer, shape, strides, offset, order ),
96+
ndarray( dtype, buffer, shape, strides, offset, order ),
97+
ndarray( dtype, buffer, shape, strides, offset, order ),
98+
ndarray( dtype, buffer, shape, strides, offset, order ),
99+
ndarray( dtype, buffer, shape, strides, offset, order )
100+
];
101+
102+
b.tic();
103+
for ( i = 0; i < b.iterations; i++ ) {
104+
out = reinterpretBoolean( values[ i%values.length ] );
105+
if ( typeof out !== 'object' ) {
106+
b.fail( 'should return an object' );
107+
}
108+
}
109+
b.toc();
110+
if ( !isndarrayLike( out ) ) {
111+
b.fail( 'should return an ndarray' );
112+
}
113+
b.pass( 'benchmark finished' );
114+
b.end();
115+
});

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-boolean/docs/repl.txt‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
{{alias}}( x )
3+
Reinterprets a boolean ndarray as an unsigned 8-bit integer ndarray.
4+
5+
The returned ndarray is a view on the input ndarray data buffer.
6+
7+
The returned ndarray is a "base" ndarray, and, thus, the returned ndarray
8+
does not perform bounds checking or afford any of the guarantees of the
9+
non-base ndarray constructor. The primary intent of this function is to
10+
reinterpret an ndarray-like object within internal implementations and to
11+
do so with minimal overhead.
12+
13+
Parameters
14+
----------
15+
x: ndarray
16+
Input ndarray.
17+
18+
Returns
19+
-------
20+
out: ndarray
21+
Unsigned 8-bit integer ndarray view.
22+
23+
Examples
24+
--------
25+
> var x = {{alias:@stdlib/ndarray/base/zeros}}( 'bool', [ 2, 2 ], 'row-major' );
26+
> var out = {{alias}}( x )
27+
<ndarray>[ [ 0, 0 ], [ 0, 0 ] ]
28+
29+
See Also
30+
--------
31+

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-boolean/docs/types/index.d.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
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+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { boolndarray, uint8ndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Reinterprets a boolean ndarray as an unsigned 8-bit integer ndarray.
27+
*
28+
* ## Notes
29+
*
30+
* - The returned ndarray is a view on the input ndarray data buffer.
31+
* - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray does not perform bounds checking or afford any of the guarantees of the non-base ndarray constructor. The primary intent of this function is to reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead.
32+
*
33+
* @param x - input ndarray
34+
* @returns unsigned 8-bit integer ndarray view
35+
*
36+
* @example
37+
* var zeros = require( '@stdlib/ndarray/base/zeros' );
38+
*
39+
* var x = zeros( 'bool', [ 2, 2 ], 'row-major' );
40+
* // returns <ndarray>[ [ false, false ], [ false, false ] ]
41+
*
42+
* var out = reinterpretBoolean( x );
43+
* // returns <ndarray>[ [ 0, 0 ], [ 0, 0 ] ]
44+
*/
45+
declare function reinterpretBoolean( x: boolndarray ): uint8ndarray;
46+
47+
48+
// EXPORTS //
49+
50+
export = reinterpretBoolean;

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-boolean/docs/types/test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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+
/* eslint-disable space-in-parens */
20+
21+
import zeros = require( '@stdlib/ndarray/base/zeros' );
22+
import reinterpretBoolean = require( './index' );
23+
24+
25+
// TESTS //
26+
27+
// The function returns a uint8ndarray...
28+
{
29+
const x = zeros( 'bool', [ 2, 2 ], 'row-major' );
30+
31+
reinterpretBoolean( x ); // $ExpectType uint8ndarray
32+
}
33+
34+
// The compiler throws an error if the function is not provided a first argument which is a boolndarray...
35+
{
36+
reinterpretBoolean( '5' ); // $ExpectError
37+
reinterpretBoolean( 5 ); // $ExpectError
38+
reinterpretBoolean( true ); // $ExpectError
39+
reinterpretBoolean( false ); // $ExpectError
40+
reinterpretBoolean( null ); // $ExpectError
41+
reinterpretBoolean( {} ); // $ExpectError
42+
reinterpretBoolean( [ '5' ] ); // $ExpectError
43+
reinterpretBoolean( ( x: number ): number => x ); // $ExpectError
44+
reinterpretBoolean( zeros( 'float64', [ 2, 2 ], 'row-major' ) ); // $ExpectError
45+
reinterpretBoolean( zeros( 'float32', [ 2, 2 ], 'row-major' ) ); // $ExpectError
46+
reinterpretBoolean( zeros( 'int32', [ 2, 2 ], 'row-major' ) ); // $ExpectError
47+
reinterpretBoolean( zeros( 'uint8', [ 2, 2 ], 'row-major' ) ); // $ExpectError
48+
reinterpretBoolean( zeros( 'complex64', [ 2, 2 ], 'row-major' ) ); // $ExpectError
49+
reinterpretBoolean( zeros( 'complex128', [ 2, 2 ], 'row-major' ) ); // $ExpectError
50+
}
51+
52+
// The compiler throws an error if the function is provided an unsupported number of arguments...
53+
{
54+
const x = zeros( 'bool', [ 2, 2 ], 'row-major' );
55+
56+
reinterpretBoolean(); // $ExpectError
57+
reinterpretBoolean( x, {} ); // $ExpectError
58+
}

0 commit comments

Comments
 (0)