Skip to content

Commit c7665fe

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent da5b927 commit c7665fe

File tree

11 files changed

+142
-263
lines changed

11 files changed

+142
-263
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
### Features
1212

13+
- [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11) - add writable parameter to `ndarray/base/remove-singleton-dimensions` [(#9667)](https://github.com/stdlib-js/stdlib/pull/9667)
1314
- [`e5af570`](https://github.com/stdlib-js/stdlib/commit/e5af57010dbb7c873ea46afe2662c8ceb44ac637) - add `atleastnd` to namespace
1415
- [`53caca8`](https://github.com/stdlib-js/stdlib/commit/53caca808d0b9aad069992056c6fe64b0c780e8f) - add `ndarray/base/atleastnd` [(#10422)](https://github.com/stdlib-js/stdlib/pull/10422)
1516
- [`9221bdb`](https://github.com/stdlib-js/stdlib/commit/9221bdb56bac8544a387c8b8f74ae69ae5ec2961) - add `toTransposed` to namespace
@@ -682,6 +683,11 @@
682683

683684
### BREAKING CHANGES
684685

686+
- [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11): add writable parameter and always return a new view
687+
688+
- To migrate, in order to preserve prior writable behavior, users should set the final parameter equal to a boolean indicating whether the input ndarray is writable. If not, pass `false`; if yes, pass `true`.
689+
To preserve prior behavior in which the input ndarray is returned if it does not have singleton dimensions, use `ndarray/base/maybe-remove-singleton-dimensions`.
690+
685691
- [`cf38d87`](https://github.com/stdlib-js/stdlib/commit/cf38d87a6820408d2ec054cbf0e20561e8352deb): rename `stdlib_ndarray_bytelength` to `stdlib_ndarray_byte_length`
686692

687693
- To migrate, users using the C API should update their call signatures
@@ -760,6 +766,7 @@ A total of 44 issues were closed in this release:
760766

761767
<details>
762768

769+
- [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11) - **feat:** add writable parameter to `ndarray/base/remove-singleton-dimensions` [(#9667)](https://github.com/stdlib-js/stdlib/pull/9667) _(by Muhammad Haris, Athan Reines)_
763770
- [`e9054b2`](https://github.com/stdlib-js/stdlib/commit/e9054b2892ab8d483449efd9b78aaed53c6fcb2b) - **docs:** add note _(by Athan Reines)_
764771
- [`e5af570`](https://github.com/stdlib-js/stdlib/commit/e5af57010dbb7c873ea46afe2662c8ceb44ac637) - **feat:** add `atleastnd` to namespace _(by Athan Reines)_
765772
- [`53caca8`](https://github.com/stdlib-js/stdlib/commit/53caca808d0b9aad069992056c6fe64b0c780e8f) - **feat:** add `ndarray/base/atleastnd` [(#10422)](https://github.com/stdlib-js/stdlib/pull/10422) _(by Muhammad Haris, Athan Reines)_

‎base/remove-singleton-dimensions/README.md‎

Lines changed: 17 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ limitations under the License.
4040
var removeSingletonDimensions = require( '@stdlib/ndarray/base/remove-singleton-dimensions' );
4141
```
4242

43-
#### removeSingletonDimensions( x )
43+
#### removeSingletonDimensions( x, writable )
4444

4545
Returns an ndarray without singleton dimensions (i.e., dimensions whose size is equal to `1`).
4646

@@ -49,16 +49,18 @@ var array = require( '@stdlib/ndarray/array' );
4949

5050
// Create a 1x2x2 ndarray:
5151
var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ] ] );
52-
// returns <ndarray>
52+
// returns <ndarray>[ [ [ 1, 2 ], [ 3, 4 ] ] ]
5353

5454
// Remove singleton dimensions:
55-
var y = removeSingletonDimensions( x );
56-
// returns <ndarray>
57-
58-
var sh = y.shape;
59-
// returns [ 2, 2 ]
55+
var y = removeSingletonDimensions( x, false );
56+
// returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
6057
```
6158

59+
The function accepts the following arguments:
60+
61+
- **x**: input ndarray.
62+
- **writable**: boolean indicating whether a returned ndarray should be writable.
63+
6264
</section>
6365

6466
<!-- /.usage -->
@@ -69,8 +71,8 @@ var sh = y.shape;
6971

7072
## Notes
7173

72-
- If a provided ndarray does not have any singleton dimensions, the function returns the provided ndarray unchanged.
73-
- If a provided ndarray does have singleton dimensions, the function returns a new ndarray view.
74+
- The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
75+
- The function **always** returns a new ndarray instance even if the input ndarray does not contain any singleton dimensions.
7476

7577
</section>
7678

@@ -85,33 +87,15 @@ var sh = y.shape;
8587
<!-- eslint no-undef: "error" -->
8688

8789
```javascript
88-
var array = require( '@stdlib/ndarray/array' );
89-
var numel = require( '@stdlib/ndarray/base/numel' );
90-
var ind2sub = require( '@stdlib/ndarray/ind2sub' );
90+
var uniform = require( '@stdlib/random/uniform' );
91+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
9192
var removeSingletonDimensions = require( '@stdlib/ndarray/base/remove-singleton-dimensions' );
9293

93-
// Create a 5-dimensional array:
94-
var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
95-
'ndmin': 5
96-
});
97-
// returns <ndarray>
98-
99-
// Remove singleton dimensions:
100-
var y = removeSingletonDimensions( x );
101-
// returns <ndarray>
102-
103-
// Retrieve the shape:
104-
var sh = y.shape;
105-
// returns [ 2, 2 ]
106-
107-
// Retrieve the number of elements:
108-
var N = numel( sh );
94+
var x = uniform( [ 1, 1, 3, 3, 3 ], -10.0, 10.0 );
95+
console.log( ndarray2array( x ) );
10996

110-
// Loop through the array elements...
111-
var i;
112-
for ( i = 0; i < N; i++ ) {
113-
console.log( 'Y[%s] = %d', ind2sub( sh, i ).join( ', ' ), y.iget( i ) );
114-
}
97+
var y = removeSingletonDimensions( x, false );
98+
console.log( ndarray2array( y ) );
11599
```
116100

117101
</section>

‎base/remove-singleton-dimensions/benchmark/benchmark.js‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,14 @@ var Float64Array = require( '@stdlib/array/float64' );
2525
var ndarrayBase = require( './../../../base/ctor' );
2626
var ndarray = require( './../../../ctor' );
2727
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
28+
var format = require( '@stdlib/string/format' );
2829
var pkg = require( './../package.json' ).name;
2930
var removeSingletonDimensions = require( './../lib' );
3031

3132

3233
// MAIN //
3334

34-
bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
35+
bench( format( '%s::base_ndarray,2d', pkg ), function benchmark( b ) {
3536
var strides;
3637
var values;
3738
var buffer;
@@ -59,7 +60,7 @@ bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
5960

6061
b.tic();
6162
for ( i = 0; i < b.iterations; i++ ) {
62-
out = removeSingletonDimensions( values[ i%values.length ] );
63+
out = removeSingletonDimensions( values[ i%values.length ], false );
6364
if ( typeof out !== 'object' ) {
6465
b.fail( 'should return an object' );
6566
}
@@ -72,7 +73,7 @@ bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
7273
b.end();
7374
});
7475

75-
bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
76+
bench( format( '%s::base_ndarray,2d,no_singleton_dimensions', pkg ), function benchmark( b ) {
7677
var strides;
7778
var values;
7879
var buffer;
@@ -100,7 +101,7 @@ bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b )
100101

101102
b.tic();
102103
for ( i = 0; i < b.iterations; i++ ) {
103-
out = removeSingletonDimensions( values[ i%values.length ] );
104+
out = removeSingletonDimensions( values[ i%values.length ], false );
104105
if ( typeof out !== 'object' ) {
105106
b.fail( 'should return an object' );
106107
}
@@ -113,7 +114,7 @@ bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b )
113114
b.end();
114115
});
115116

116-
bench( pkg+'::ndarray,2d', function benchmark( b ) {
117+
bench( format( '%s::ndarray,2d', pkg ), function benchmark( b ) {
117118
var strides;
118119
var values;
119120
var buffer;
@@ -141,7 +142,7 @@ bench( pkg+'::ndarray,2d', function benchmark( b ) {
141142

142143
b.tic();
143144
for ( i = 0; i < b.iterations; i++ ) {
144-
out = removeSingletonDimensions( values[ i%values.length ] );
145+
out = removeSingletonDimensions( values[ i%values.length ], false );
145146
if ( typeof out !== 'object' ) {
146147
b.fail( 'should return an object' );
147148
}
@@ -154,7 +155,7 @@ bench( pkg+'::ndarray,2d', function benchmark( b ) {
154155
b.end();
155156
});
156157

157-
bench( pkg+'::ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
158+
bench( format( '%s::ndarray,2d,no_singleton_dimensions', pkg ), function benchmark( b ) {
158159
var strides;
159160
var values;
160161
var buffer;
@@ -182,7 +183,7 @@ bench( pkg+'::ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
182183

183184
b.tic();
184185
for ( i = 0; i < b.iterations; i++ ) {
185-
out = removeSingletonDimensions( values[ i%values.length ] );
186+
out = removeSingletonDimensions( values[ i%values.length ], false );
186187
if ( typeof out !== 'object' ) {
187188
b.fail( 'should return an object' );
188189
}

‎base/remove-singleton-dimensions/benchmark/benchmark.ndims.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
var bench = require( '@stdlib/bench' );
2424
var array = require( './../../../array' );
2525
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
26+
var format = require( '@stdlib/string/format' );
2627
var pkg = require( './../package.json' ).name;
2728
var removeSingletonDimensions = require( './../lib' );
2829

@@ -54,7 +55,7 @@ function createBenchmark( ndims ) {
5455

5556
b.tic();
5657
for ( i = 0; i < b.iterations; i++ ) {
57-
out = removeSingletonDimensions( x );
58+
out = removeSingletonDimensions( x, false );
5859
if ( typeof out !== 'object' ) {
5960
b.fail( 'should return an object' );
6061
}
@@ -87,7 +88,7 @@ function main() {
8788

8889
for ( i = min; i <= max; i++ ) {
8990
f = createBenchmark( i );
90-
bench( pkg+'::ndarray,2d:singleton_dimensions='+i, f );
91+
bench( format( '%s::ndarray,2d:singleton_dimensions=%d', pkg, i ), f );
9192
}
9293
}
9394

‎base/remove-singleton-dimensions/docs/repl.txt‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11

2-
{{alias}}( x )
3-
Returns an array without singleton dimensions.
2+
{{alias}}( x, writable )
3+
Returns an ndarray without singleton dimensions.
44

5-
If a provided ndarray does not have any singleton dimensions, the function
6-
returns the provided ndarray unchanged.
7-
8-
If a provided ndarray does have singleton dimensions, the function returns a
9-
new ndarray view.
5+
The function always returns a new ndarray instance even if the input ndarray
6+
does not contain any singleton dimensions.
107

118
Parameters
129
----------
1310
x: ndarray
1411
Input array.
1512

13+
writable: boolean
14+
Boolean indicating whether a returned array should be writable.
15+
1616
Returns
1717
-------
1818
out: ndarray
@@ -21,21 +21,9 @@
2121
Examples
2222
--------
2323
> var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ], { 'ndmin': 5 } )
24-
<ndarray>
25-
> var sh = x.shape
26-
[ 1, 1, 1, 2, 2 ]
27-
> var y = {{alias}}( x )
28-
<ndarray>
29-
> sh = y.shape
30-
[ 2, 2 ]
31-
> var v = y.get( 0, 0 )
32-
1
33-
> v = y.get( 0, 1 )
34-
2
35-
> v = y.get( 1, 0 )
36-
3
37-
> v = y.get( 1, 1 )
38-
4
24+
<ndarray>[ [ [ [ [1, 2 ], [ 3, 4 ] ] ] ] ]
25+
> var y = {{alias}}( x, false )
26+
<ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
3927

4028
See Also
4129
--------

‎base/remove-singleton-dimensions/docs/types/index.d.ts‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@
2323
import { ndarray } from '@stdlib/types/ndarray';
2424

2525
/**
26-
* Returns an array without singleton dimensions.
26+
* Returns an ndarray without singleton dimensions.
2727
*
2828
* ## Notes
2929
*
30-
* - If a provided ndarray does not have any singleton dimensions, the function returns the provided ndarray unchanged.
31-
* - If a provided ndarray does have singleton dimensions, the function returns a new ndarray view.
30+
* - The function always returns a new ndarray instance even if the input ndarray does not contain any singleton dimensions.
3231
*
3332
* @param x - input array
33+
* @param writable - boolean indicating whether a returned array should be writable
3434
* @returns squeezed array
3535
*
3636
* @example
@@ -39,30 +39,12 @@ import { ndarray } from '@stdlib/types/ndarray';
3939
* var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
4040
* 'ndmin': 5
4141
* });
42-
* // returns <ndarray>
42+
* // returns <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
4343
*
44-
* var shx = x.shape;
45-
* // returns [ 1, 1, 1, 2, 2 ]
46-
*
47-
* var y = removeSingletonDimensions( x );
48-
* // returns <ndarray>
49-
*
50-
* var shy = y.shape;
51-
* // returns [ 2, 2 ]
52-
*
53-
* var v = y.get( 0, 0 );
54-
* // returns 1
55-
*
56-
* v = y.get( 0, 1 );
57-
* // returns 2
58-
*
59-
* v = y.get( 1, 0 );
60-
* // returns 3
61-
*
62-
* v = y.get( 1, 1 );
63-
* // returns 4
44+
* var y = removeSingletonDimensions( x, false );
45+
* // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
6446
*/
65-
declare function removeSingletonDimensions( x: ndarray ): ndarray;
47+
declare function removeSingletonDimensions( x: ndarray, writable: boolean ): ndarray;
6648

6749

6850
// EXPORTS //

‎base/remove-singleton-dimensions/docs/types/test.ts‎

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,25 +26,38 @@ import removeSingletonDimensions = require( './index' );
2626
{
2727
const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
2828

29-
removeSingletonDimensions( x ); // $ExpectType ndarray
29+
removeSingletonDimensions( x, false ); // $ExpectType ndarray
3030
}
3131

3232
// The compiler throws an error if the function is not provided a first argument which is an ndarray...
3333
{
34-
removeSingletonDimensions( '5' ); // $ExpectError
35-
removeSingletonDimensions( 5 ); // $ExpectError
36-
removeSingletonDimensions( true ); // $ExpectError
37-
removeSingletonDimensions( false ); // $ExpectError
38-
removeSingletonDimensions( null ); // $ExpectError
39-
removeSingletonDimensions( {} ); // $ExpectError
40-
removeSingletonDimensions( [ '5' ] ); // $ExpectError
41-
removeSingletonDimensions( ( x: number ): number => x ); // $ExpectError
34+
removeSingletonDimensions( '5', false ); // $ExpectError
35+
removeSingletonDimensions( 5, false ); // $ExpectError
36+
removeSingletonDimensions( true, false ); // $ExpectError
37+
removeSingletonDimensions( false, false ); // $ExpectError
38+
removeSingletonDimensions( null, false ); // $ExpectError
39+
removeSingletonDimensions( {}, false ); // $ExpectError
40+
removeSingletonDimensions( [ '5' ], false ); // $ExpectError
41+
removeSingletonDimensions( ( x: number ): number => x, false ); // $ExpectError
42+
}
43+
44+
// The compiler throws an error if the function is not provided a second argument which is a boolean...
45+
{
46+
const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
47+
48+
removeSingletonDimensions( x, '5' ); // $ExpectError
49+
removeSingletonDimensions( x, 5 ); // $ExpectError
50+
removeSingletonDimensions( x, null ); // $ExpectError
51+
removeSingletonDimensions( x, {} ); // $ExpectError
52+
removeSingletonDimensions( x, [ '5' ] ); // $ExpectError
53+
removeSingletonDimensions( x, ( x: number ): number => x ); // $ExpectError
4254
}
4355

4456
// The compiler throws an error if the function is provided an unsupported number of arguments...
4557
{
4658
const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
4759

4860
removeSingletonDimensions(); // $ExpectError
49-
removeSingletonDimensions( x, [ 1, 2, 3 ], [ 2, 3 ] ); // $ExpectError
61+
removeSingletonDimensions( x ); // $ExpectError
62+
removeSingletonDimensions( x, false, {} ); // $ExpectError
5063
}

0 commit comments

Comments
 (0)