Skip to content
/ ndarray Public

Commit e2c9645

Browse files
stdlib-botstdlib-bot
committedMay 16, 2025·
Auto-generated commit
1 parent 67d19bc commit e2c9645

File tree

13 files changed

+1837
-492
lines changed

13 files changed

+1837
-492
lines changed
 

‎CHANGELOG.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@
44
55
<section class="release" id="unreleased">
66

7-
## Unreleased (2025-05-15)
7+
## Unreleased (2025-05-16)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`848f226`](https://github.com/stdlib-js/stdlib/commit/848f226d45aad2d627453c8306ae192c75338ac3) - add `factory` method
1314
- [`916b907`](https://github.com/stdlib-js/stdlib/commit/916b9073d6cf82262233e835f9bbbaca26d685f0) - add `ndarray/vector/ctor`
1415
- [`9b0d852`](https://github.com/stdlib-js/stdlib/commit/9b0d8520418c2788d20d446b6a39471b6393a787) - add `loopOrder` to namespace
1516
- [`bdc9110`](https://github.com/stdlib-js/stdlib/commit/bdc91105259200e3ebb60aea16e918718301ce4b) - add `ndarray/base/loop-interchange-order`
@@ -389,6 +390,7 @@ A total of 15 issues were closed in this release:
389390

390391
<details>
391392

393+
- [`848f226`](https://github.com/stdlib-js/stdlib/commit/848f226d45aad2d627453c8306ae192c75338ac3) - **feat:** add `factory` method _(by Athan Reines)_
392394
- [`d30fed0`](https://github.com/stdlib-js/stdlib/commit/d30fed0b3516e362f957aa15d1521b3b3fe6cefd) - **docs:** update examples _(by Athan Reines)_
393395
- [`916b907`](https://github.com/stdlib-js/stdlib/commit/916b9073d6cf82262233e835f9bbbaca26d685f0) - **feat:** add `ndarray/vector/ctor` _(by Athan Reines)_
394396
- [`9b8f3a8`](https://github.com/stdlib-js/stdlib/commit/9b8f3a8e51b449803b683c7bf394d498de479a5f) - **docs:** update namespace table of contents [(#6996)](https://github.com/stdlib-js/stdlib/pull/6996) _(by stdlib-bot)_

‎vector/ctor/README.md

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,41 @@ var dt6 = getDType( arr6 );
186186
// returns 'int16'
187187
```
188188

189+
#### vector.factory( dtype\[, options] )
190+
191+
Returns a function for creating a one-dimensional [ndarray][@stdlib/ndarray/ctor].
192+
193+
```javascript
194+
var getDType = require( '@stdlib/ndarray/dtype' );
195+
var numel = require( '@stdlib/ndarray/numel' );
196+
197+
var Float32Vector = vector.factory( 'float32' );
198+
199+
var arr = new Float32Vector( [ 1, 2, 3 ] );
200+
// returns <ndarray>
201+
202+
var dt = getDType( arr );
203+
// returns 'float32'
204+
205+
var len = numel( arr );
206+
// returns 3
207+
```
208+
209+
The function supports the following parameters:
210+
211+
- **dtype**: [data type][@stdlib/ndarray/dtypes].
212+
- **options**: function options (_optional_).
213+
214+
The function accepts the following options:
215+
216+
- **order**: specifies whether the default memory layout for a returned [ndarray][@stdlib/ndarray/ctor] should be `'row-major'` (C-style) or `'column-major'` (Fortran-style). Default: `'row-major'`.
217+
- **mode**: specifies the default behavior when handling indices which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). Default: `'throw'`.
218+
- **readonly**: boolean indicating whether to return a **read-only** [ndarray][@stdlib/ndarray/ctor] by default. Default: `false`.
219+
220+
The function returned by the `factory` method supports the same arguments and options as `vector` above, except for the `dtype` argument, as the returned function always returns a one-dimensional [ndarray][@stdlib/ndarray/ctor] having the same [data type][@stdlib/ndarray/dtypes].
221+
222+
When providing options to the returned function, the provided option values override the defaults established during function creation.
223+
189224
</section>
190225

191226
<!-- /.usage -->
@@ -211,7 +246,7 @@ var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
211246
var cartesianProduct = require( '@stdlib/array/cartesian-product' );
212247
var unzip = require( '@stdlib/utils/unzip' );
213248
var dtypes = require( '@stdlib/ndarray/dtypes' );
214-
var getShape = require( '@stdlib/ndarray/shape' );
249+
var sum = require( '@stdlib/blas/ext/sum' );
215250
var logEachMap = require( '@stdlib/console/log-each-map' );
216251
var vector = require( '@stdlib/ndarray/vector/ctor' );
217252

@@ -220,23 +255,23 @@ var lens = discreteUniform( 10, 5, 15, {
220255
'dtype': 'int32'
221256
});
222257

223-
// Resolve a list of supported ndarray date types:
224-
var dts = dtypes();
258+
// Resolve a list of supported ndarray real-valued data types:
259+
var dts = dtypes( 'real_and_generic' );
225260

226261
// Create length-dtype pairs:
227262
var pairs = cartesianProduct( lens, dts );
228263

229264
// Split the pairs into individual arguments:
230265
var args = unzip( pairs );
231266

232-
// Define a callback to create a vector and return the vector shape:
267+
// Define a callback to create a random vector and return the sum of all vector elements:
233268
function clbk( len, dtype ) {
234-
var x = vector( len, dtype );
235-
return getShape( x );
269+
var x = vector( discreteUniform( len, 0, 100 ), dtype );
270+
return sum( x ).get();
236271
}
237272

238273
// Apply the callback and print the results:
239-
logEachMap( 'len: %2d. dtype: %10s. shape: [%d].', args[ 0 ], args[ 1 ], clbk );
274+
logEachMap( 'len: %2d. dtype: %7s. sum: %d.', args[ 0 ], args[ 1 ], clbk );
240275
```
241276

242277
</section>

‎vector/ctor/benchmark/benchmark.factory.js

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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 isFunction = require( '@stdlib/assert/is-function' );
25+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
26+
var dtypes = require( './../../../dtypes' );
27+
var pkg = require( './../package.json' ).name;
28+
var factory = require( './../lib' ).factory;
29+
30+
31+
// MAIN //
32+
33+
bench( pkg+':factory', function benchmark( b ) {
34+
var values;
35+
var v;
36+
var i;
37+
38+
values = dtypes();
39+
40+
b.tic();
41+
for ( i = 0; i < b.iterations; i++ ) {
42+
v = factory( values[ i%values.length ] );
43+
if ( typeof v !== 'function' ) {
44+
b.fail( 'should return a function' );
45+
}
46+
}
47+
b.toc();
48+
if ( !isFunction( v ) ) {
49+
b.fail( 'should return a function' );
50+
}
51+
b.pass( 'benchmark finished' );
52+
b.end();
53+
});
54+
55+
bench( pkg+':factory:dtype=float64', function benchmark( b ) {
56+
var vector;
57+
var arr;
58+
var i;
59+
60+
vector = factory( 'float64' );
61+
62+
b.tic();
63+
for ( i = 0; i < b.iterations; i++ ) {
64+
arr = vector( 0 );
65+
if ( arr.length !== 0 ) {
66+
b.fail( 'should have length 0' );
67+
}
68+
}
69+
b.toc();
70+
if ( !isndarrayLike( arr ) ) {
71+
b.fail( 'should return an ndarray' );
72+
}
73+
b.pass( 'benchmark finished' );
74+
b.end();
75+
});
76+
77+
bench( pkg+':factory:dtype=float32', function benchmark( b ) {
78+
var vector;
79+
var arr;
80+
var i;
81+
82+
vector = factory( 'float32' );
83+
84+
b.tic();
85+
for ( i = 0; i < b.iterations; i++ ) {
86+
arr = vector( 0 );
87+
if ( arr.length !== 0 ) {
88+
b.fail( 'should have length 0' );
89+
}
90+
}
91+
b.toc();
92+
if ( !isndarrayLike( arr ) ) {
93+
b.fail( 'should return an ndarray' );
94+
}
95+
b.pass( 'benchmark finished' );
96+
b.end();
97+
});
98+
99+
bench( pkg+':factory:dtype=complex128', function benchmark( b ) {
100+
var vector;
101+
var arr;
102+
var i;
103+
104+
vector = factory( 'complex128' );
105+
106+
b.tic();
107+
for ( i = 0; i < b.iterations; i++ ) {
108+
arr = vector( 0 );
109+
if ( arr.length !== 0 ) {
110+
b.fail( 'should have length 0' );
111+
}
112+
}
113+
b.toc();
114+
if ( !isndarrayLike( arr ) ) {
115+
b.fail( 'should return an ndarray' );
116+
}
117+
b.pass( 'benchmark finished' );
118+
b.end();
119+
});
120+
121+
bench( pkg+':factory:dtype=complex64', function benchmark( b ) {
122+
var vector;
123+
var arr;
124+
var i;
125+
126+
vector = factory( 'complex64' );
127+
128+
b.tic();
129+
for ( i = 0; i < b.iterations; i++ ) {
130+
arr = vector( 0 );
131+
if ( arr.length !== 0 ) {
132+
b.fail( 'should have length 0' );
133+
}
134+
}
135+
b.toc();
136+
if ( !isndarrayLike( arr ) ) {
137+
b.fail( 'should return an ndarray' );
138+
}
139+
b.pass( 'benchmark finished' );
140+
b.end();
141+
});
142+
143+
bench( pkg+':factory:dtype=int32', function benchmark( b ) {
144+
var vector;
145+
var arr;
146+
var i;
147+
148+
vector = factory( 'int32' );
149+
150+
b.tic();
151+
for ( i = 0; i < b.iterations; i++ ) {
152+
arr = vector( 0 );
153+
if ( arr.length !== 0 ) {
154+
b.fail( 'should have length 0' );
155+
}
156+
}
157+
b.toc();
158+
if ( !isndarrayLike( arr ) ) {
159+
b.fail( 'should return an ndarray' );
160+
}
161+
b.pass( 'benchmark finished' );
162+
b.end();
163+
});
164+
165+
bench( pkg+':factory:dtype=uint32', function benchmark( b ) {
166+
var vector;
167+
var arr;
168+
var i;
169+
170+
vector = factory( 'uint32' );
171+
172+
b.tic();
173+
for ( i = 0; i < b.iterations; i++ ) {
174+
arr = vector( 0 );
175+
if ( arr.length !== 0 ) {
176+
b.fail( 'should have length 0' );
177+
}
178+
}
179+
b.toc();
180+
if ( !isndarrayLike( arr ) ) {
181+
b.fail( 'should return an ndarray' );
182+
}
183+
b.pass( 'benchmark finished' );
184+
b.end();
185+
});
186+
187+
bench( pkg+':factory:dtype=int16', function benchmark( b ) {
188+
var vector;
189+
var arr;
190+
var i;
191+
192+
vector = factory( 'int16' );
193+
194+
b.tic();
195+
for ( i = 0; i < b.iterations; i++ ) {
196+
arr = vector( 0 );
197+
if ( arr.length !== 0 ) {
198+
b.fail( 'should have length 0' );
199+
}
200+
}
201+
b.toc();
202+
if ( !isndarrayLike( arr ) ) {
203+
b.fail( 'should return an ndarray' );
204+
}
205+
b.pass( 'benchmark finished' );
206+
b.end();
207+
});
208+
209+
bench( pkg+':factory:dtype=uint16', function benchmark( b ) {
210+
var vector;
211+
var arr;
212+
var i;
213+
214+
vector = factory( 'uint16' );
215+
216+
b.tic();
217+
for ( i = 0; i < b.iterations; i++ ) {
218+
arr = vector( 0 );
219+
if ( arr.length !== 0 ) {
220+
b.fail( 'should have length 0' );
221+
}
222+
}
223+
b.toc();
224+
if ( !isndarrayLike( arr ) ) {
225+
b.fail( 'should return an ndarray' );
226+
}
227+
b.pass( 'benchmark finished' );
228+
b.end();
229+
});
230+
231+
bench( pkg+':factory:dtype=int8', function benchmark( b ) {
232+
var vector;
233+
var arr;
234+
var i;
235+
236+
vector = factory( 'int8' );
237+
238+
b.tic();
239+
for ( i = 0; i < b.iterations; i++ ) {
240+
arr = vector( 0 );
241+
if ( arr.length !== 0 ) {
242+
b.fail( 'should have length 0' );
243+
}
244+
}
245+
b.toc();
246+
if ( !isndarrayLike( arr ) ) {
247+
b.fail( 'should return an ndarray' );
248+
}
249+
b.pass( 'benchmark finished' );
250+
b.end();
251+
});
252+
253+
bench( pkg+':factory:dtype=uint8', function benchmark( b ) {
254+
var vector;
255+
var arr;
256+
var i;
257+
258+
vector = factory( 'uint8' );
259+
260+
b.tic();
261+
for ( i = 0; i < b.iterations; i++ ) {
262+
arr = vector( 0 );
263+
if ( arr.length !== 0 ) {
264+
b.fail( 'should have length 0' );
265+
}
266+
}
267+
b.toc();
268+
if ( !isndarrayLike( arr ) ) {
269+
b.fail( 'should return an ndarray' );
270+
}
271+
b.pass( 'benchmark finished' );
272+
b.end();
273+
});
274+
275+
bench( pkg+':factory:dtype=uint8c', function benchmark( b ) {
276+
var vector;
277+
var arr;
278+
var i;
279+
280+
vector = factory( 'uint8c' );
281+
282+
b.tic();
283+
for ( i = 0; i < b.iterations; i++ ) {
284+
arr = vector( 0 );
285+
if ( arr.length !== 0 ) {
286+
b.fail( 'should have length 0' );
287+
}
288+
}
289+
b.toc();
290+
if ( !isndarrayLike( arr ) ) {
291+
b.fail( 'should return an ndarray' );
292+
}
293+
b.pass( 'benchmark finished' );
294+
b.end();
295+
});
296+
297+
bench( pkg+':factory:dtype=generic', function benchmark( b ) {
298+
var vector;
299+
var arr;
300+
var i;
301+
302+
vector = factory( 'generic' );
303+
304+
b.tic();
305+
for ( i = 0; i < b.iterations; i++ ) {
306+
arr = vector( 0 );
307+
if ( arr.length !== 0 ) {
308+
b.fail( 'should have length 0' );
309+
}
310+
}
311+
b.toc();
312+
if ( !isndarrayLike( arr ) ) {
313+
b.fail( 'should return an ndarray' );
314+
}
315+
b.pass( 'benchmark finished' );
316+
b.end();
317+
});

‎vector/ctor/benchmark/benchmark.factory.size.js

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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 pow = require( '@stdlib/math/base/special/pow' );
25+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
26+
var dtypes = require( './../../../dtypes' );
27+
var pkg = require( './../package.json' ).name;
28+
var factory = require( './../lib' ).factory;
29+
30+
31+
// VARIABLES //
32+
33+
var DTYPES = dtypes();
34+
35+
36+
// FUNCTIONS //
37+
38+
/**
39+
* Creates a benchmark function.
40+
*
41+
* @private
42+
* @param {PositiveInteger} len - array length
43+
* @param {string} dtype - data type
44+
* @returns {Function} benchmark function
45+
*/
46+
function createBenchmark( len, dtype ) {
47+
var vector = factory( dtype );
48+
return benchmark;
49+
50+
/**
51+
* Benchmark function.
52+
*
53+
* @private
54+
* @param {Benchmark} b - benchmark instance
55+
*/
56+
function benchmark( b ) {
57+
var arr;
58+
var i;
59+
60+
b.tic();
61+
for ( i = 0; i < b.iterations; i++ ) {
62+
arr = vector( len );
63+
if ( arr.length !== len ) {
64+
b.fail( 'unexpected length' );
65+
}
66+
}
67+
b.toc();
68+
if ( !isndarrayLike( arr ) ) {
69+
b.fail( 'should return an ndarray' );
70+
}
71+
b.pass( 'benchmark finished' );
72+
b.end();
73+
}
74+
}
75+
76+
77+
// MAIN //
78+
79+
/**
80+
* Main execution sequence.
81+
*
82+
* @private
83+
*/
84+
function main() {
85+
var len;
86+
var min;
87+
var max;
88+
var dt;
89+
var f;
90+
var i;
91+
var j;
92+
93+
min = 1; // 10^min
94+
max = 6; // 10^max
95+
96+
for ( j = 0; j < DTYPES.length; j++ ) {
97+
dt = DTYPES[ j ];
98+
for ( i = min; i <= max; i++ ) {
99+
len = pow( 10, i );
100+
f = createBenchmark( len, dt );
101+
bench( pkg+':factory:dtype='+dt+',size='+len, f );
102+
}
103+
}
104+
}
105+
106+
main();

‎vector/ctor/docs/repl.txt

Lines changed: 50 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,11 @@
3636
--------
3737
> var arr = {{alias}}()
3838
<ndarray>
39-
> var dt = arr.dtype
39+
> var dt = {{alias:@stdlib/ndarray/dtype}}( arr )
4040
'float64'
4141
> arr = {{alias}}( 'float32' )
4242
<ndarray>
43-
> dt = arr.dtype
43+
> dt = {{alias:@stdlib/ndarray/dtype}}( arr )
4444
'float32'
4545

4646

@@ -84,13 +84,13 @@
8484
--------
8585
> var arr = {{alias}}( 5 )
8686
<ndarray>
87-
> var dt = arr.dtype
87+
> var dt = {{alias:@stdlib/ndarray/dtype}}( arr )
8888
'float64'
8989
> var len = {{alias:@stdlib/ndarray/numel}}( arr )
9090
5
9191
> arr = {{alias}}( 5, 'float32' )
9292
<ndarray>
93-
> dt = arr.dtype
93+
> dt = {{alias:@stdlib/ndarray/dtype}}( arr )
9494
'float32'
9595
> len = {{alias:@stdlib/ndarray/numel}}( arr )
9696
5
@@ -137,7 +137,7 @@
137137
> var v = [ 0.5, 0.5, 0.5 ];
138138
> var arr = {{alias}}( v, 'float32' )
139139
<ndarray>
140-
> var dt = arr.dtype
140+
> var dt = {{alias:@stdlib/ndarray/dtype}}( arr )
141141
'float32'
142142
> var len = {{alias:@stdlib/ndarray/numel}}( arr )
143143
3
@@ -192,11 +192,55 @@
192192
> var buf = new {{alias:@stdlib/array/buffer}}( 16 );
193193
> var arr = {{alias}}( buf, 0, 4, 'float32' )
194194
<ndarray>
195-
> var dt = arr.dtype
195+
> var dt = {{alias:@stdlib/ndarray/dtype}}( arr )
196196
'float32'
197197
> var len = {{alias:@stdlib/ndarray/numel}}( arr )
198198
4
199199

200+
201+
{{alias}}.factory( dtype[, options] )
202+
Returns a function for creating a one-dimensional ndarray.
203+
204+
Parameters
205+
----------
206+
dtype: string
207+
Underlying data type.
208+
209+
options: Object (optional)
210+
Options.
211+
212+
options.order: string (optional)
213+
Specifies whether the default memory layout should be row-major (C-
214+
style) or column-major (Fortran-style). Default: 'row-major'.
215+
216+
options.mode: string (optional)
217+
Specifies the default behavior when handling indices which exceed array
218+
dimensions. If equal to 'throw', an ndarray instance throws an error
219+
when an index exceeds array dimensions. If equal to 'normalize', an
220+
ndarray instance normalizes negative indices and throws an error when an
221+
index exceeds array dimensions. If equal to 'wrap', an ndarray instance
222+
wraps around indices exceeding array dimensions using modulo arithmetic.
223+
If equal to 'clamp', an ndarray instance sets an index exceeding array
224+
dimensions to either `0` (minimum index) or the maximum index. Default:
225+
'throw'.
226+
227+
options.readonly: boolean (optional)
228+
Boolean indicating whether an array should be read-only by default.
229+
Default: false.
230+
231+
Returns
232+
-------
233+
fcn: Function
234+
Function for creating a one-dimensional ndarray.
235+
236+
Examples
237+
--------
238+
> var f = {{alias}}.factory( 'float32' );
239+
> var arr = f()
240+
<ndarray>
241+
> var dt = {{alias:@stdlib/ndarray/dtype}}( arr )
242+
'float32'
243+
200244
See Also
201245
--------
202246

‎vector/ctor/docs/types/index.d.ts

Lines changed: 770 additions & 400 deletions
Large diffs are not rendered by default.

‎vector/ctor/docs/types/test.ts

Lines changed: 78 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
* limitations under the License.
1717
*/
1818

19-
import array2iterator = require( '@stdlib/array/to-iterator' );
2019
import ArrayBuffer = require( '@stdlib/array/buffer' );
2120
import vector = require( './index' );
2221

@@ -34,9 +33,6 @@ import vector = require( './index' );
3433
vector( [ 1, 2, 3 ] ); // $ExpectType float64ndarray
3534
vector( [ 1, 2, 3 ], {} ); // $ExpectType float64ndarray
3635

37-
vector( array2iterator( [ 1, 2, 3 ] ) ); // $ExpectType float64ndarray
38-
vector( array2iterator( [ 1, 2, 3 ] ), {} ); // $ExpectType float64ndarray
39-
4036
vector( new ArrayBuffer( 10 ) ); // $ExpectType float64ndarray
4137
vector( new ArrayBuffer( 10 ), {} ); // $ExpectType float64ndarray
4238

@@ -55,9 +51,6 @@ import vector = require( './index' );
5551
vector( [ 1, 2, 3 ], 'int32' ); // $ExpectType int32ndarray
5652
vector( [ 1, 2, 3 ], 'int32', {} ); // $ExpectType int32ndarray
5753

58-
vector( array2iterator( [ 1, 2, 3 ] ), 'int32' ); // $ExpectType int32ndarray
59-
vector( array2iterator( [ 1, 2, 3 ] ), 'int32', {} ); // $ExpectType int32ndarray
60-
6154
vector( new ArrayBuffer( 10 ), 'int32' ); // $ExpectType int32ndarray
6255
vector( new ArrayBuffer( 10 ), 'int32', {} ); // $ExpectType int32ndarray
6356

@@ -81,3 +74,81 @@ import vector = require( './index' );
8174
const buf = new ArrayBuffer( 32 );
8275
vector( buf, 8, 2, 'int32', {}, {} ); // $ExpectError
8376
}
77+
78+
// Attached the main export is a `factory` method which returns a function...
79+
{
80+
vector.factory( 'float64' ); // $ExpectType TypedVector<"float64">
81+
vector.factory( 'float32' ); // $ExpectType TypedVector<"float32">
82+
}
83+
84+
// The `factory` method returns an ndarray...
85+
{
86+
const f1 = vector.factory( 'float64' );
87+
88+
f1(); // $ExpectType float64ndarray
89+
f1( {} ); // $ExpectType float64ndarray
90+
91+
f1( 10 ); // $ExpectType float64ndarray
92+
f1( 10, {} ); // $ExpectType float64ndarray
93+
94+
f1( [ 1, 2, 3 ] ); // $ExpectType float64ndarray
95+
f1( [ 1, 2, 3 ], {} ); // $ExpectType float64ndarray
96+
97+
f1( new ArrayBuffer( 10 ) ); // $ExpectType float64ndarray
98+
f1( new ArrayBuffer( 10 ), {} ); // $ExpectType float64ndarray
99+
100+
f1( new ArrayBuffer( 10 ), 8 ); // $ExpectType float64ndarray
101+
f1( new ArrayBuffer( 10 ), 8, {} ); // $ExpectType float64ndarray
102+
103+
f1( new ArrayBuffer( 10 ), 8, 0 ); // $ExpectType float64ndarray
104+
f1( new ArrayBuffer( 10 ), 8, 0, {} ); // $ExpectType float64ndarray
105+
106+
const f2 = vector.factory( 'float32' );
107+
108+
f2(); // $ExpectType float32ndarray
109+
f2( {} ); // $ExpectType float32ndarray
110+
111+
f2( 10 ); // $ExpectType float32ndarray
112+
f2( 10, {} ); // $ExpectType float32ndarray
113+
114+
f2( [ 1, 2, 3 ] ); // $ExpectType float32ndarray
115+
f2( [ 1, 2, 3 ], {} ); // $ExpectType float32ndarray
116+
117+
f2( new ArrayBuffer( 10 ) ); // $ExpectType float32ndarray
118+
f2( new ArrayBuffer( 10 ), {} ); // $ExpectType float32ndarray
119+
120+
f2( new ArrayBuffer( 10 ), 8 ); // $ExpectType float32ndarray
121+
f2( new ArrayBuffer( 10 ), 8, {} ); // $ExpectType float32ndarray
122+
123+
f2( new ArrayBuffer( 10 ), 8, 0 ); // $ExpectType float32ndarray
124+
f2( new ArrayBuffer( 10 ), 8, 0, {} ); // $ExpectType float32ndarray
125+
126+
const f3 = vector.factory( 'generic' );
127+
128+
f3(); // $ExpectType genericndarray<number>
129+
f3( {} ); // $ExpectType genericndarray<number>
130+
131+
f3( 10 ); // $ExpectType genericndarray<number>
132+
f3( 10, {} ); // $ExpectType genericndarray<number>
133+
134+
f3( [ 1, 2, 3 ] ); // $ExpectType genericndarray<number>
135+
f3( [ 1, 2, 3 ], {} ); // $ExpectType genericndarray<number>
136+
}
137+
138+
// The compiler throws an error if the function returned by the `factory` method is provided a first argument which is not a data type, number, array-like object, iterable, or options objects...
139+
{
140+
const f = vector.factory( 'float64' );
141+
142+
f( true ); // $ExpectError
143+
f( false ); // $ExpectError
144+
f( null ); // $ExpectError
145+
f( ( x: number ): number => x ); // $ExpectError
146+
}
147+
148+
// The compiler throws an error if the function returned by the `factory` method is provided an unsupported number of arguments...
149+
{
150+
const f = vector.factory( 'float64' );
151+
152+
const buf = new ArrayBuffer( 32 );
153+
f( buf, 8, 2, {}, {} ); // $ExpectError
154+
}

‎vector/ctor/examples/index.js

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
2222
var cartesianProduct = require( '@stdlib/array/cartesian-product' );
2323
var unzip = require( '@stdlib/utils/unzip' );
2424
var dtypes = require( './../../../dtypes' );
25-
var getShape = require( './../../../shape' );
25+
var sum = require( '@stdlib/blas/ext/sum' );
2626
var logEachMap = require( '@stdlib/console/log-each-map' );
2727
var vector = require( './../lib' );
2828

@@ -31,20 +31,20 @@ var lens = discreteUniform( 10, 5, 15, {
3131
'dtype': 'int32'
3232
});
3333

34-
// Resolve a list of supported ndarray date types:
35-
var dts = dtypes();
34+
// Resolve a list of supported ndarray real-valued data types:
35+
var dts = dtypes( 'real_and_generic' );
3636

3737
// Create length-dtype pairs:
3838
var pairs = cartesianProduct( lens, dts );
3939

4040
// Split the pairs into individual arguments:
4141
var args = unzip( pairs );
4242

43-
// Define a callback to create a vector and return the vector shape:
43+
// Define a callback to create a random vector and return the sum of all vector elements:
4444
function clbk( len, dtype ) {
45-
var x = vector( len, dtype );
46-
return getShape( x );
45+
var x = vector( discreteUniform( len, 0, 100 ), dtype );
46+
return sum( x ).get();
4747
}
4848

4949
// Apply the callback and print the results:
50-
logEachMap( 'len: %2d. dtype: %10s. shape: [%d].', args[ 0 ], args[ 1 ], clbk );
50+
logEachMap( 'len: %2d. dtype: %7s. sum: %d.', args[ 0 ], args[ 1 ], clbk );

‎vector/ctor/lib/factory.js

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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 max-len */
20+
21+
'use strict';
22+
23+
// MODULES //
24+
25+
var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
26+
var isIterableLike = require( '@stdlib/assert/is-iterable-like' );
27+
var isArrayBuffer = require( '@stdlib/assert/is-arraybuffer' );
28+
var isCollection = require( '@stdlib/assert/is-collection' );
29+
var isDataType = require( './../../../base/assert/is-data-type' );
30+
var objectAssign = require( '@stdlib/object/assign' );
31+
var format = require( '@stdlib/string/format' );
32+
var validate = require( './validate.js' );
33+
var main = require( './main.js' );
34+
35+
36+
// MAIN //
37+
38+
/**
39+
* Returns a function for creating a vector (i.e., a one-dimensional ndarray).
40+
*
41+
* @param {string} dtype - data type
42+
* @param {Options} [options] - function options
43+
* @param {boolean} [options.readonly=false] - boolean indicating whether to return a read-only vector by default
44+
* @param {string} [options.mode='throw'] - specifies the default behavior when handling indices which exceed vector dimensions
45+
* @param {string} [options.order='row-major'] - default memory layout (either row-major or column-major)
46+
* @throws {TypeError} first argument must be a supported data type
47+
* @throws {TypeError} options argument must be an object
48+
* @throws {TypeError} must provide valid options
49+
* @returns {Function} function for creating a vector
50+
*
51+
* @example
52+
* var getDType = require( '@stdlib/ndarray/dtype' );
53+
* var numel = require( '@stdlib/ndarray/numel' );
54+
*
55+
* var Float32Vector = factory( 'float32' );
56+
*
57+
* var arr = new Float32Vector( [ 1, 2, 3 ] );
58+
* // returns <ndarray>
59+
*
60+
* var dt = getDType( arr );
61+
* // returns 'float32'
62+
*
63+
* var len = numel( arr );
64+
* // returns 3
65+
*
66+
* @example
67+
* var getDType = require( '@stdlib/ndarray/dtype' );
68+
* var numel = require( '@stdlib/ndarray/numel' );
69+
*
70+
* var Float32Vector = factory( 'float32' );
71+
*
72+
* var arr = new Float32Vector( 3 );
73+
* // returns <ndarray>
74+
*
75+
* var dt = getDType( arr );
76+
* // returns 'float32'
77+
*
78+
* var len = numel( arr );
79+
* // returns 3
80+
*
81+
* @example
82+
* var ArrayBuffer = require( '@stdlib/array/buffer' );
83+
* var getDType = require( '@stdlib/ndarray/dtype' );
84+
* var numel = require( '@stdlib/ndarray/numel' );
85+
*
86+
* var Float32Vector = factory( 'float32' );
87+
*
88+
* var buf = new ArrayBuffer( 12 );
89+
* var arr = new Float32Vector( buf );
90+
* // returns <ndarray>
91+
*
92+
* var dt = getDType( arr );
93+
* // returns 'float32'
94+
*
95+
* var len = numel( arr );
96+
* // returns 3
97+
*
98+
* @example
99+
* var ArrayBuffer = require( '@stdlib/array/buffer' );
100+
* var getDType = require( '@stdlib/ndarray/dtype' );
101+
* var numel = require( '@stdlib/ndarray/numel' );
102+
*
103+
* var Float32Vector = factory( 'float32' );
104+
*
105+
* var buf = new ArrayBuffer( 12 );
106+
* var arr = new Float32Vector( buf, 4 );
107+
* // returns <ndarray>
108+
*
109+
* var dt = getDType( arr );
110+
* // returns 'float32'
111+
*
112+
* var len = numel( arr );
113+
* // returns 2
114+
*
115+
* @example
116+
* var ArrayBuffer = require( '@stdlib/array/buffer' );
117+
* var getDType = require( '@stdlib/ndarray/dtype' );
118+
* var numel = require( '@stdlib/ndarray/numel' );
119+
*
120+
* var Float32Vector = factory( 'float32' );
121+
*
122+
* var buf = new ArrayBuffer( 12 );
123+
* var arr = new Float32Vector( buf, 4, 1 );
124+
* // returns <ndarray>
125+
*
126+
* var dt = getDType( arr );
127+
* // returns 'float32'
128+
*
129+
* var len = numel( arr );
130+
* // returns 1
131+
*/
132+
function factory( dtype, options ) {
133+
var opts;
134+
var err;
135+
if ( !isDataType( dtype ) ) {
136+
throw new TypeError( format( 'invalid argument. First argument must be a supported data type. Value: `%s`.', dtype ) );
137+
}
138+
opts = {};
139+
if ( arguments.length > 1 ) {
140+
err = validate( opts, options );
141+
if ( err ) {
142+
throw err;
143+
}
144+
}
145+
return vector;
146+
147+
/**
148+
* Creates a vector (i.e., a one-dimensional ndarray).
149+
*
150+
* @private
151+
* @param {(NonNegativeInteger|Collection|ArrayBuffer|Iterable)} [arg] - length, typed array, array-like object, buffer, or iterable
152+
* @param {NonNegativeInteger} [byteOffset=0] - byte offset
153+
* @param {NonNegativeInteger} [length] - view length
154+
* @param {Options} [options] - function options
155+
* @param {boolean} [options.readonly] - boolean indicating whether to return a read-only vector
156+
* @param {string} [options.mode] - specifies how to handle indices which exceed vector dimensions
157+
* @param {string} [options.order] - memory layout (either row-major or column-major)
158+
* @throws {Error} unexpected error
159+
* @returns {ndarray} one-dimensional ndarray
160+
*/
161+
function vector() {
162+
var options;
163+
var nargs;
164+
var arg0;
165+
var arg1;
166+
var err;
167+
168+
options = objectAssign( {}, opts );
169+
nargs = arguments.length;
170+
171+
// Case: vector()
172+
if ( nargs === 0 ) {
173+
return main( dtype, options );
174+
}
175+
// Case: vector( ArrayBuffer, byteOffset, length, options )
176+
if ( nargs > 3 ) {
177+
err = validate( options, arguments[ 3 ] );
178+
if ( err ) {
179+
throw err;
180+
}
181+
return main( arguments[ 0 ], arguments[ 1 ], arguments[ 2 ], dtype, options );
182+
}
183+
// Case: vector( ArrayBuffer, byteOffset, arg2 )
184+
if ( nargs === 3 ) {
185+
// Case: vector( ArrayBuffer, byteOffset, length )
186+
if ( isNonNegativeInteger( arguments[ 2 ] ) ) {
187+
return main( arguments[ 0 ], arguments[ 1 ], arguments[ 2 ], dtype, options );
188+
}
189+
// Case: vector( ArrayBuffer, byteOffset, options )
190+
err = validate( options, arguments[ 2 ] );
191+
if ( err ) {
192+
throw err;
193+
}
194+
return main( arguments[ 0 ], arguments[ 1 ], dtype, options );
195+
}
196+
// Case: vector( arg0, arg1 )
197+
if ( nargs === 2 ) {
198+
arg0 = arguments[ 0 ];
199+
arg1 = arguments[ 1 ];
200+
201+
// Case: vector( length, options )
202+
if ( isNonNegativeInteger( arg0 ) ) {
203+
err = validate( options, arg1 );
204+
if ( err ) {
205+
throw err;
206+
}
207+
return main( arg0, dtype, options );
208+
}
209+
// Case: vector( ArrayBuffer, arg1 )
210+
if ( isArrayBuffer( arg0 ) ) {
211+
// Case: vector( ArrayBuffer, byteOffset )
212+
if ( isNonNegativeInteger( arg1 ) ) {
213+
return main( arg0, arg1, dtype, options );
214+
}
215+
// Case: vector( ArrayBuffer, options )
216+
err = validate( options, arg1 );
217+
if ( err ) {
218+
throw err;
219+
}
220+
return main( arg0, dtype, options );
221+
}
222+
// Case: vector( collection, options )
223+
if ( isCollection( arg0 ) ) {
224+
err = validate( options, arg1 );
225+
if ( err ) {
226+
throw err;
227+
}
228+
return main( arg0, dtype, options );
229+
}
230+
// Case: vector( iterable, options )
231+
err = validate( options, arg1 );
232+
if ( err ) {
233+
throw err;
234+
}
235+
return main( arg0, dtype, options );
236+
}
237+
// nargs === 1
238+
arg0 = arguments[ 0 ];
239+
240+
// Case: vector( length|ArrayBuffer|Collection|Iterable )
241+
if (
242+
isNonNegativeInteger( arg0 ) ||
243+
isArrayBuffer( arg0 ) ||
244+
isCollection( arg0 ) ||
245+
isIterableLike( arg0 )
246+
) {
247+
return main( arg0, dtype, options );
248+
}
249+
// Case: vector( options )
250+
err = validate( options, arg0 );
251+
if ( err ) {
252+
throw err;
253+
}
254+
return main( dtype, options );
255+
}
256+
}
257+
258+
259+
// EXPORTS //
260+
261+
module.exports = factory;

‎vector/ctor/lib/index.js

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,18 @@
116116

117117
// MODULES //
118118

119+
var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
120+
var factory = require( './factory.js' );
119121
var main = require( './main.js' );
120122

121123

124+
// MAIN //
125+
126+
setReadOnly( main, 'factory', factory );
127+
128+
122129
// EXPORTS //
123130

124131
module.exports = main;
132+
133+
// exports: { "factory": "main.factory" }

‎vector/ctor/lib/main.js

Lines changed: 105 additions & 63 deletions
Large diffs are not rendered by default.

‎vector/ctor/lib/validate.js

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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 isObject = require( '@stdlib/assert/is-plain-object' );
24+
var hasOwnProp = require( '@stdlib/assert/has-own-property' );
25+
var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
26+
var isIndexMode = require( './../../../base/assert/is-index-mode' );
27+
var isOrder = require( './../../../base/assert/is-order' );
28+
var format = require( '@stdlib/string/format' );
29+
30+
31+
// MAIN //
32+
33+
/**
34+
* Validates function options.
35+
*
36+
* @private
37+
* @param {Object} opts - destination object
38+
* @param {Options} options - function options
39+
* @param {boolean} [options.readonly] - boolean indicating whether to return a read-only vector
40+
* @param {string} [options.mode] - specifies how to handle indices which exceed vector dimensions
41+
* @param {string} [options.order] - memory layout (either row-major or column-major)
42+
* @returns {(Error|null)} null or an error object
43+
*
44+
* @example
45+
* var opts = {};
46+
* var options = {
47+
* 'readonly': true
48+
* };
49+
* var err = validate( opts, options );
50+
* if ( err ) {
51+
* throw err;
52+
* }
53+
*/
54+
function validate( opts, options ) {
55+
if ( !isObject( options ) ) {
56+
return new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
57+
}
58+
if ( hasOwnProp( options, 'readonly' ) ) {
59+
opts.readonly = options.readonly;
60+
if ( !isBoolean( opts.readonly ) ) {
61+
return new TypeError( format( 'invalid option. `%s` option must be a boolean. Option: `%s`.', 'readonly', opts.readonly ) );
62+
}
63+
}
64+
if ( hasOwnProp( options, 'mode' ) ) {
65+
opts.mode = options.mode;
66+
if ( !isIndexMode( opts.mode ) ) {
67+
return new TypeError( format( 'invalid option. `%s` option must be a valid index mode. Option: `%s`.', 'mode', opts.mode ) );
68+
}
69+
}
70+
if ( hasOwnProp( options, 'order' ) ) {
71+
opts.order = options.order;
72+
if ( !isOrder( opts.order ) ) {
73+
return new TypeError( format( 'invalid option. `%s` option must be a memory layout. Option: `%s`.', 'order', opts.order ) );
74+
}
75+
}
76+
return null;
77+
}
78+
79+
80+
// EXPORTS //
81+
82+
module.exports = validate;

‎vector/ctor/test/test.js

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
// MODULES //
2222

2323
var tape = require( 'tape' );
24+
var isMethod = require( '@stdlib/assert/is-method' );
2425
var vector = require( './../lib' );
2526

2627

@@ -32,4 +33,9 @@ tape( 'main export is a function', function test( t ) {
3233
t.end();
3334
});
3435

35-
// FIXME: add tests
36+
tape( 'attached to the main export is a `factory` method', function test( t ) {
37+
t.strictEqual( isMethod( vector, 'factory' ), true, 'returns expected value' );
38+
t.end();
39+
});
40+
41+
// FIXME: add tests (see array/typed and ndarray/zeros)

0 commit comments

Comments
 (0)
Please sign in to comment.