Skip to content

Commit 9df924b

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat!: add writable parameter support to ndarray/base/transpose (#10474)
This commit adds support for a writable parameter. Previously, a returned ndarray was always writable; this is now configurable. This commit also fixes a bug related to index offset calculation. BREAKING CHANGE: add writable parameter To migrate and preserve prior behavior, users should always pass `true` for the second parameter. PR-URL: #10474 Closes: stdlib-js/metr-issue-tracker#170 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent e947540 commit 9df924b

21 files changed

+490
-590
lines changed

‎lib/node_modules/@stdlib/ndarray/base/transpose/README.md‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -40,32 +40,29 @@ limitations under the License.
4040
var transpose = require( '@stdlib/ndarray/base/transpose' );
4141
```
4242

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

4545
Transposes a matrix (or a stack of matrices) `x`.
4646

4747
```javascript
48+
var getData = require( '@stdlib/ndarray/data-buffer' );
4849
var array = require( '@stdlib/ndarray/array' );
4950

5051
var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] );
51-
// returns <ndarray>
52+
// returns <ndarray>[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
5253

53-
var sh = x.shape;
54-
// returns [ 2, 3 ]
54+
var y = transpose( x, false );
55+
// returns <ndarray>[ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
5556

56-
var y = transpose( x );
57-
// returns <ndarray>
58-
59-
sh = y.shape;
60-
// returns [ 3, 2 ]
61-
62-
var bool = ( x.data === y.data );
63-
// returns true
64-
65-
bool = ( x.get( 0, 1 ) === y.get( 1, 0 ) );
57+
var bool = ( getData( x ) === getData( y ) );
6658
// returns true
6759
```
6860

61+
The function accepts the following arguments:
62+
63+
- **x**: input ndarray.
64+
- **writable**: boolean indicating whether a returned ndarray should be writable.
65+
6966
</section>
7067

7168
<!-- /.usage -->
@@ -76,8 +73,9 @@ bool = ( x.get( 0, 1 ) === y.get( 1, 0 ) );
7673

7774
## Notes
7875

79-
- The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa. While powerful, this can lead to subtle bugs. In general, one should handle the returned ndarray as **read-only**.
76+
- The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa.
8077
- If provided an ndarray with fewer than two dimensions, the function raises an exception.
78+
- The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
8179

8280
</section>
8381

@@ -133,7 +131,7 @@ var buf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
133131
var x = new ndarray( 'float64', buf, [ 2, 2, 3 ], [ 0, 3, 1 ], 0, 'row-major' );
134132

135133
// Transpose the stack of matrices:
136-
var y = transpose( x );
134+
var y = transpose( x, false );
137135

138136
// Print the stacks:
139137
console.log( '' );

‎lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.js‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,14 @@
2323
var bench = require( '@stdlib/bench' );
2424
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2525
var zeros = require( '@stdlib/ndarray/base/zeros' );
26+
var format = require( '@stdlib/string/format' );
2627
var pkg = require( './../package.json' ).name;
2728
var transpose = require( './../lib' );
2829

2930

3031
// MAIN //
3132

32-
bench( pkg+'::base:dtype=float64', function benchmark( b ) {
33+
bench( format( '%s::base:dtype=float64', pkg ), function benchmark( b ) {
3334
var x;
3435
var y;
3536
var i;
@@ -38,7 +39,7 @@ bench( pkg+'::base:dtype=float64', function benchmark( b ) {
3839

3940
b.tic();
4041
for ( i = 0; i < b.iterations; i++ ) {
41-
y = transpose( x );
42+
y = transpose( x, false );
4243
if ( y.length !== 4 ) {
4344
b.fail( 'should have expected length' );
4445
}
@@ -51,7 +52,7 @@ bench( pkg+'::base:dtype=float64', function benchmark( b ) {
5152
b.end();
5253
});
5354

54-
bench( pkg+'::base:dtype=float32', function benchmark( b ) {
55+
bench( format( '%s::base:dtype=float32', pkg ), function benchmark( b ) {
5556
var x;
5657
var y;
5758
var i;
@@ -60,7 +61,7 @@ bench( pkg+'::base:dtype=float32', function benchmark( b ) {
6061

6162
b.tic();
6263
for ( i = 0; i < b.iterations; i++ ) {
63-
y = transpose( x );
64+
y = transpose( x, false );
6465
if ( y.length !== 4 ) {
6566
b.fail( 'should have expected length' );
6667
}
@@ -73,7 +74,7 @@ bench( pkg+'::base:dtype=float32', function benchmark( b ) {
7374
b.end();
7475
});
7576

76-
bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
77+
bench( format( '%s::base:dtype=complex128', pkg ), function benchmark( b ) {
7778
var x;
7879
var y;
7980
var i;
@@ -82,7 +83,7 @@ bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
8283

8384
b.tic();
8485
for ( i = 0; i < b.iterations; i++ ) {
85-
y = transpose( x );
86+
y = transpose( x, false );
8687
if ( y.length !== 4 ) {
8788
b.fail( 'should have expected length' );
8889
}
@@ -95,7 +96,7 @@ bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
9596
b.end();
9697
});
9798

98-
bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
99+
bench( format( '%s::base:dtype=complex64', pkg ), function benchmark( b ) {
99100
var x;
100101
var y;
101102
var i;
@@ -104,7 +105,7 @@ bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
104105

105106
b.tic();
106107
for ( i = 0; i < b.iterations; i++ ) {
107-
y = transpose( x );
108+
y = transpose( x, false );
108109
if ( y.length !== 4 ) {
109110
b.fail( 'should have expected length' );
110111
}
@@ -117,7 +118,7 @@ bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
117118
b.end();
118119
});
119120

120-
bench( pkg+'::base:dtype=int32', function benchmark( b ) {
121+
bench( format( '%s::base:dtype=int32', pkg ), function benchmark( b ) {
121122
var x;
122123
var y;
123124
var i;
@@ -126,7 +127,7 @@ bench( pkg+'::base:dtype=int32', function benchmark( b ) {
126127

127128
b.tic();
128129
for ( i = 0; i < b.iterations; i++ ) {
129-
y = transpose( x );
130+
y = transpose( x, false );
130131
if ( y.length !== 4 ) {
131132
b.fail( 'should have expected length' );
132133
}
@@ -139,7 +140,7 @@ bench( pkg+'::base:dtype=int32', function benchmark( b ) {
139140
b.end();
140141
});
141142

142-
bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
143+
bench( format( '%s::base:dtype=uint32', pkg ), function benchmark( b ) {
143144
var x;
144145
var y;
145146
var i;
@@ -148,7 +149,7 @@ bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
148149

149150
b.tic();
150151
for ( i = 0; i < b.iterations; i++ ) {
151-
y = transpose( x );
152+
y = transpose( x, false );
152153
if ( y.length !== 4 ) {
153154
b.fail( 'should have expected length' );
154155
}
@@ -161,7 +162,7 @@ bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
161162
b.end();
162163
});
163164

164-
bench( pkg+'::base:dtype=int16', function benchmark( b ) {
165+
bench( format( '%s::base:dtype=int16', pkg ), function benchmark( b ) {
165166
var x;
166167
var y;
167168
var i;
@@ -170,7 +171,7 @@ bench( pkg+'::base:dtype=int16', function benchmark( b ) {
170171

171172
b.tic();
172173
for ( i = 0; i < b.iterations; i++ ) {
173-
y = transpose( x );
174+
y = transpose( x, false );
174175
if ( y.length !== 4 ) {
175176
b.fail( 'should have expected length' );
176177
}
@@ -183,7 +184,7 @@ bench( pkg+'::base:dtype=int16', function benchmark( b ) {
183184
b.end();
184185
});
185186

186-
bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
187+
bench( format( '%s::base:dtype=uint16', pkg ), function benchmark( b ) {
187188
var x;
188189
var y;
189190
var i;
@@ -192,7 +193,7 @@ bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
192193

193194
b.tic();
194195
for ( i = 0; i < b.iterations; i++ ) {
195-
y = transpose( x );
196+
y = transpose( x, false );
196197
if ( y.length !== 4 ) {
197198
b.fail( 'should have expected length' );
198199
}
@@ -205,7 +206,7 @@ bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
205206
b.end();
206207
});
207208

208-
bench( pkg+'::base:dtype=int8', function benchmark( b ) {
209+
bench( format( '%s::base:dtype=int8', pkg ), function benchmark( b ) {
209210
var x;
210211
var y;
211212
var i;
@@ -214,7 +215,7 @@ bench( pkg+'::base:dtype=int8', function benchmark( b ) {
214215

215216
b.tic();
216217
for ( i = 0; i < b.iterations; i++ ) {
217-
y = transpose( x );
218+
y = transpose( x, false );
218219
if ( y.length !== 4 ) {
219220
b.fail( 'should have expected length' );
220221
}
@@ -227,7 +228,7 @@ bench( pkg+'::base:dtype=int8', function benchmark( b ) {
227228
b.end();
228229
});
229230

230-
bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
231+
bench( format( '%s::base:dtype=uint8', pkg ), function benchmark( b ) {
231232
var x;
232233
var y;
233234
var i;
@@ -236,7 +237,7 @@ bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
236237

237238
b.tic();
238239
for ( i = 0; i < b.iterations; i++ ) {
239-
y = transpose( x );
240+
y = transpose( x, false );
240241
if ( y.length !== 4 ) {
241242
b.fail( 'should have expected length' );
242243
}
@@ -249,7 +250,7 @@ bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
249250
b.end();
250251
});
251252

252-
bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
253+
bench( format( '%s::base:dtype=uint8c', pkg ), function benchmark( b ) {
253254
var x;
254255
var y;
255256
var i;
@@ -258,7 +259,7 @@ bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
258259

259260
b.tic();
260261
for ( i = 0; i < b.iterations; i++ ) {
261-
y = transpose( x );
262+
y = transpose( x, false );
262263
if ( y.length !== 4 ) {
263264
b.fail( 'should have expected length' );
264265
}
@@ -271,7 +272,7 @@ bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
271272
b.end();
272273
});
273274

274-
bench( pkg+'::base:dtype=generic', function benchmark( b ) {
275+
bench( format( '%s::base:dtype=generic', pkg ), function benchmark( b ) {
275276
var x;
276277
var y;
277278
var i;
@@ -280,7 +281,7 @@ bench( pkg+'::base:dtype=generic', function benchmark( b ) {
280281

281282
b.tic();
282283
for ( i = 0; i < b.iterations; i++ ) {
283-
y = transpose( x );
284+
y = transpose( x, false );
284285
if ( y.length !== 4 ) {
285286
b.fail( 'should have expected length' );
286287
}

‎lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.complex128.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
2525
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2626
var zeros = require( '@stdlib/ndarray/base/zeros' );
27+
var format = require( '@stdlib/string/format' );
2728
var pkg = require( './../package.json' ).name;
2829
var transpose = require( './../lib' );
2930

@@ -53,7 +54,7 @@ function createBenchmark( len ) {
5354

5455
b.tic();
5556
for ( i = 0; i < b.iterations; i++ ) {
56-
arr = transpose( x );
57+
arr = transpose( x, false );
5758
if ( arr.length !== len ) {
5859
b.fail( 'unexpected length' );
5960
}
@@ -88,7 +89,7 @@ function main() {
8889
for ( i = min; i <= max; i++ ) {
8990
len = pow( 10, i );
9091
f = createBenchmark( len );
91-
bench( pkg+'::base:dtype=complex128,size='+len, f );
92+
bench( format( '%s::base:dtype=complex128,size=%d', pkg, len ), f );
9293
}
9394
}
9495

‎lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.complex64.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
2525
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2626
var zeros = require( '@stdlib/ndarray/base/zeros' );
27+
var format = require( '@stdlib/string/format' );
2728
var pkg = require( './../package.json' ).name;
2829
var transpose = require( './../lib' );
2930

@@ -53,7 +54,7 @@ function createBenchmark( len ) {
5354

5455
b.tic();
5556
for ( i = 0; i < b.iterations; i++ ) {
56-
arr = transpose( x );
57+
arr = transpose( x, false );
5758
if ( arr.length !== len ) {
5859
b.fail( 'unexpected length' );
5960
}
@@ -88,7 +89,7 @@ function main() {
8889
for ( i = min; i <= max; i++ ) {
8990
len = pow( 10, i );
9091
f = createBenchmark( len );
91-
bench( pkg+'::base:dtype=complex64,size='+len, f );
92+
bench( format( '%s::base:dtype=complex64,size=%d', pkg, len ), f );
9293
}
9394
}
9495

‎lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.float32.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
2525
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2626
var zeros = require( '@stdlib/ndarray/base/zeros' );
27+
var format = require( '@stdlib/string/format' );
2728
var pkg = require( './../package.json' ).name;
2829
var transpose = require( './../lib' );
2930

@@ -53,7 +54,7 @@ function createBenchmark( len ) {
5354

5455
b.tic();
5556
for ( i = 0; i < b.iterations; i++ ) {
56-
arr = transpose( x );
57+
arr = transpose( x, false );
5758
if ( arr.length !== len ) {
5859
b.fail( 'unexpected length' );
5960
}
@@ -88,7 +89,7 @@ function main() {
8889
for ( i = min; i <= max; i++ ) {
8990
len = pow( 10, i );
9091
f = createBenchmark( len );
91-
bench( pkg+'::base:dtype=float32,size='+len, f );
92+
bench( format( '%s::base:dtype=float32,size=%d', pkg, len ), f );
9293
}
9394
}
9495

‎lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.float64.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
2525
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2626
var zeros = require( '@stdlib/ndarray/base/zeros' );
27+
var format = require( '@stdlib/string/format' );
2728
var pkg = require( './../package.json' ).name;
2829
var transpose = require( './../lib' );
2930

@@ -53,7 +54,7 @@ function createBenchmark( len ) {
5354

5455
b.tic();
5556
for ( i = 0; i < b.iterations; i++ ) {
56-
arr = transpose( x );
57+
arr = transpose( x, false );
5758
if ( arr.length !== len ) {
5859
b.fail( 'unexpected length' );
5960
}
@@ -88,7 +89,7 @@ function main() {
8889
for ( i = min; i <= max; i++ ) {
8990
len = pow( 10, i );
9091
f = createBenchmark( len );
91-
bench( pkg+'::base:dtype=float64,size='+len, f );
92+
bench( format( '%s::base:dtype=float64,size=%d', pkg, len ), f );
9293
}
9394
}
9495

0 commit comments

Comments
 (0)