@stdlib/ndarray-base 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -20,14 +20,23 @@
20
20
 
21
21
  /* eslint-disable max-lines */
22
22
 
23
+ import any = require( '@stdlib/ndarray-base-any' );
24
+ import anyBy = require( '@stdlib/ndarray-base-any-by' );
23
25
  import assert = require( '@stdlib/ndarray-base-assert' );
24
26
  import assign = require( '@stdlib/ndarray-base-assign' );
27
+ import binary = require( '@stdlib/ndarray-base-binary' );
28
+ import binaryInputCastingDataType = require( '@stdlib/ndarray-base-binary-input-casting-dtype' );
25
29
  import binaryLoopOrder = require( '@stdlib/ndarray-base-binary-loop-interchange-order' );
30
+ import binaryOutputDataType = require( '@stdlib/ndarray-base-binary-output-dtype' );
31
+ import binaryReduceStrided1dDispatch = require( '@stdlib/ndarray-base-binary-reduce-strided1d-dispatch' );
32
+ import binaryReduceStrided1dDispatchFactory = require( '@stdlib/ndarray-base-binary-reduce-strided1d-dispatch-factory' );
26
33
  import binaryBlockSize = require( '@stdlib/ndarray-base-binary-tiling-block-size' );
27
34
  import bind2vind = require( '@stdlib/ndarray-base-bind2vind' );
28
35
  import broadcastArray = require( '@stdlib/ndarray-base-broadcast-array' );
36
+ import broadcastArrayExceptDimensions = require( '@stdlib/ndarray-base-broadcast-array-except-dimensions' );
29
37
  import broadcastArrays = require( '@stdlib/ndarray-base-broadcast-arrays' );
30
38
  import broadcastScalar = require( '@stdlib/ndarray-base-broadcast-scalar' );
39
+ import broadcastScalarLike = require( '@stdlib/ndarray-base-broadcast-scalar-like' );
31
40
  import broadcastShapes = require( '@stdlib/ndarray-base-broadcast-shapes' );
32
41
  import buffer = require( '@stdlib/ndarray-base-buffer' );
33
42
  import bufferCtors = require( '@stdlib/ndarray-base-buffer-ctors' );
@@ -36,58 +45,97 @@ import bufferDataTypeEnum = require( '@stdlib/ndarray-base-buffer-dtype-enum' );
36
45
  import bytesPerElement = require( '@stdlib/ndarray-base-bytes-per-element' );
37
46
  import char2dtype = require( '@stdlib/ndarray-base-char2dtype' );
38
47
  import clampIndex = require( '@stdlib/ndarray-base-clamp-index' );
48
+ import complementShape = require( '@stdlib/ndarray-base-complement-shape' );
49
+ import copy = require( '@stdlib/ndarray-base-copy' );
50
+ import countFalsy = require( '@stdlib/ndarray-base-count-falsy' );
51
+ import countIf = require( '@stdlib/ndarray-base-count-if' );
52
+ import countTruthy = require( '@stdlib/ndarray-base-count-truthy' );
39
53
  import ndarray = require( '@stdlib/ndarray-base-ctor' );
40
54
  import data = require( '@stdlib/ndarray-base-data-buffer' );
41
55
  import dtype = require( '@stdlib/ndarray-base-dtype' );
56
+ import dtypeAlignment = require( '@stdlib/ndarray-base-dtype-alignment' );
42
57
  import dtypeChar = require( '@stdlib/ndarray-base-dtype-char' );
58
+ import dtypeChars = require( '@stdlib/ndarray-base-dtype-chars' );
43
59
  import dtypeDesc = require( '@stdlib/ndarray-base-dtype-desc' );
44
60
  import dtypeEnum2Str = require( '@stdlib/ndarray-base-dtype-enum2str' );
61
+ import dtypeEnums = require( '@stdlib/ndarray-base-dtype-enums' );
62
+ import dtypeObjects = require( '@stdlib/ndarray-base-dtype-objects' );
45
63
  import dtypeResolveEnum = require( '@stdlib/ndarray-base-dtype-resolve-enum' );
46
64
  import dtypeResolveStr = require( '@stdlib/ndarray-base-dtype-resolve-str' );
47
65
  import dtypeStr2Enum = require( '@stdlib/ndarray-base-dtype-str2enum' );
66
+ import dtypeStrings = require( '@stdlib/ndarray-base-dtype-strings' );
48
67
  import dtype2c = require( '@stdlib/ndarray-base-dtype2c' );
68
+ import dtypes2enums = require( '@stdlib/ndarray-base-dtypes2enums' );
49
69
  import dtypes2signatures = require( '@stdlib/ndarray-base-dtypes2signatures' );
70
+ import dtypes2strings = require( '@stdlib/ndarray-base-dtypes2strings' );
50
71
  import empty = require( '@stdlib/ndarray-base-empty' );
51
72
  import emptyLike = require( '@stdlib/ndarray-base-empty-like' );
73
+ import every = require( '@stdlib/ndarray-base-every' );
74
+ import everyBy = require( '@stdlib/ndarray-base-every-by' );
52
75
  import expandDimensions = require( '@stdlib/ndarray-base-expand-dimensions' );
76
+ import fill = require( '@stdlib/ndarray-base-fill' );
77
+ import fillBy = require( '@stdlib/ndarray-base-fill-by' );
78
+ import find = require( '@stdlib/ndarray-base-find' );
53
79
  import flag = require( '@stdlib/ndarray-base-flag' );
54
80
  import flags = require( '@stdlib/ndarray-base-flags' );
81
+ import flattenShape = require( '@stdlib/ndarray-base-flatten-shape' );
82
+ import flattenShapeFrom = require( '@stdlib/ndarray-base-flatten-shape-from' );
55
83
  import fliplr = require( '@stdlib/ndarray-base-fliplr' );
56
84
  import flipud = require( '@stdlib/ndarray-base-flipud' );
57
85
  import forEach = require( '@stdlib/ndarray-base-for-each' );
86
+ import array2ndarray = require( '@stdlib/ndarray-base-from-array' );
58
87
  import scalar2ndarray = require( '@stdlib/ndarray-base-from-scalar' );
88
+ import scalar2ndarrayLike = require( '@stdlib/ndarray-base-from-scalar-like' );
89
+ import includes = require( '@stdlib/ndarray-base-includes' );
59
90
  import ind = require( '@stdlib/ndarray-base-ind' );
60
91
  import ind2sub = require( '@stdlib/ndarray-base-ind2sub' );
61
92
  import iterationOrder = require( '@stdlib/ndarray-base-iteration-order' );
93
+ import loopOrder = require( '@stdlib/ndarray-base-loop-interchange-order' );
94
+ import map = require( '@stdlib/ndarray-base-map' );
62
95
  import maxViewBufferIndex = require( '@stdlib/ndarray-base-max-view-buffer-index' );
63
96
  import maybeBroadcastArray = require( '@stdlib/ndarray-base-maybe-broadcast-array' );
64
97
  import maybeBroadcastArrays = require( '@stdlib/ndarray-base-maybe-broadcast-arrays' );
65
98
  import metaDataProps = require( '@stdlib/ndarray-base-meta-data-props' );
99
+ import minSignedIntegerDataType = require( '@stdlib/ndarray-base-min-signed-integer-dtype' );
100
+ import minUnsignedIntegerDataType = require( '@stdlib/ndarray-base-min-unsigned-integer-dtype' );
66
101
  import minViewBufferIndex = require( '@stdlib/ndarray-base-min-view-buffer-index' );
67
102
  import minmaxViewBufferIndex = require( '@stdlib/ndarray-base-minmax-view-buffer-index' );
103
+ import ndarraylike2ndarray = require( '@stdlib/ndarray-base-ndarraylike2ndarray' );
68
104
  import ndarraylike2object = require( '@stdlib/ndarray-base-ndarraylike2object' );
105
+ import ndarraylike2scalar = require( '@stdlib/ndarray-base-ndarraylike2scalar' );
69
106
  import ndims = require( '@stdlib/ndarray-base-ndims' );
70
107
  import nextCartesianIndex = require( '@stdlib/ndarray-base-next-cartesian-index' );
71
108
  import nonsingletonDimensions = require( '@stdlib/ndarray-base-nonsingleton-dimensions' );
72
109
  import normalizeIndex = require( '@stdlib/ndarray-base-normalize-index' );
110
+ import normalizeIndices = require( '@stdlib/ndarray-base-normalize-indices' );
73
111
  import nullary = require( '@stdlib/ndarray-base-nullary' );
74
112
  import nullaryLoopOrder = require( '@stdlib/ndarray-base-nullary-loop-interchange-order' );
113
+ import nullaryStrided1dDispatch = require( '@stdlib/ndarray-base-nullary-strided1d-dispatch' );
114
+ import nullaryStrided1dDispatchFactory = require( '@stdlib/ndarray-base-nullary-strided1d-dispatch-factory' );
75
115
  import nullaryBlockSize = require( '@stdlib/ndarray-base-nullary-tiling-block-size' );
76
116
  import numel = require( '@stdlib/ndarray-base-numel' );
77
117
  import numelDimension = require( '@stdlib/ndarray-base-numel-dimension' );
78
118
  import offset = require( '@stdlib/ndarray-base-offset' );
79
119
  import order = require( '@stdlib/ndarray-base-order' );
120
+ import outputDataType = require( '@stdlib/ndarray-base-output-dtype' );
80
121
  import outputPolicyEnum2Str = require( '@stdlib/ndarray-base-output-policy-enum2str' );
81
122
  import outputPolicyResolveEnum = require( '@stdlib/ndarray-base-output-policy-resolve-enum' );
82
123
  import outputPolicyResolveStr = require( '@stdlib/ndarray-base-output-policy-resolve-str' );
83
124
  import outputPolicyStr2Enum = require( '@stdlib/ndarray-base-output-policy-str2enum' );
125
+ import pop = require( '@stdlib/ndarray-base-pop' );
84
126
  import prependSingletonDimensions = require( '@stdlib/ndarray-base-prepend-singleton-dimensions' );
127
+ import promoteDataTypes = require( '@stdlib/ndarray-base-promote-dtypes' );
128
+ import quaternaryLoopOrder = require( '@stdlib/ndarray-base-quaternary-loop-interchange-order' );
129
+ import quaternaryBlockSize = require( '@stdlib/ndarray-base-quaternary-tiling-block-size' );
130
+ import quinaryLoopOrder = require( '@stdlib/ndarray-base-quinary-loop-interchange-order' );
131
+ import quinaryBlockSize = require( '@stdlib/ndarray-base-quinary-tiling-block-size' );
85
132
  import removeSingletonDimensions = require( '@stdlib/ndarray-base-remove-singleton-dimensions' );
86
133
  import reverse = require( '@stdlib/ndarray-base-reverse' );
87
134
  import reverseDimension = require( '@stdlib/ndarray-base-reverse-dimension' );
88
135
  import serializeMetaData = require( '@stdlib/ndarray-base-serialize-meta-data' );
89
136
  import shape = require( '@stdlib/ndarray-base-shape' );
90
137
  import shape2strides = require( '@stdlib/ndarray-base-shape2strides' );
138
+ import shift = require( '@stdlib/ndarray-base-shift' );
91
139
  import singletonDimensions = require( '@stdlib/ndarray-base-singleton-dimensions' );
92
140
  import slice = require( '@stdlib/ndarray-base-slice' );
93
141
  import sliceAssign = require( '@stdlib/ndarray-base-slice-assign' );
@@ -96,27 +144,120 @@ import sliceDimensionFrom = require( '@stdlib/ndarray-base-slice-dimension-from'
96
144
  import sliceDimensionTo = require( '@stdlib/ndarray-base-slice-dimension-to' );
97
145
  import sliceFrom = require( '@stdlib/ndarray-base-slice-from' );
98
146
  import sliceTo = require( '@stdlib/ndarray-base-slice-to' );
147
+ import some = require( '@stdlib/ndarray-base-some' );
148
+ import someBy = require( '@stdlib/ndarray-base-some-by' );
149
+ import spreadDimensions = require( '@stdlib/ndarray-base-spread-dimensions' );
99
150
  import stride = require( '@stdlib/ndarray-base-stride' );
100
151
  import strides = require( '@stdlib/ndarray-base-strides' );
101
152
  import strides2offset = require( '@stdlib/ndarray-base-strides2offset' );
102
153
  import strides2order = require( '@stdlib/ndarray-base-strides2order' );
103
154
  import sub2ind = require( '@stdlib/ndarray-base-sub2ind' );
155
+ import ternary = require( '@stdlib/ndarray-base-ternary' );
156
+ import ternaryLoopOrder = require( '@stdlib/ndarray-base-ternary-loop-interchange-order' );
157
+ import ternaryOutputDataType = require( '@stdlib/ndarray-base-ternary-output-dtype' );
158
+ import ternaryBlockSize = require( '@stdlib/ndarray-base-ternary-tiling-block-size' );
159
+ import blockSize = require( '@stdlib/ndarray-base-tiling-block-size' );
104
160
  import ndarray2array = require( '@stdlib/ndarray-base-to-array' );
161
+ import toFlippedlr = require( '@stdlib/ndarray-base-to-flippedlr' );
162
+ import toFlippedud = require( '@stdlib/ndarray-base-to-flippedud' );
163
+ import toNormalizedIndices = require( '@stdlib/ndarray-base-to-normalized-indices' );
164
+ import toReversed = require( '@stdlib/ndarray-base-to-reversed' );
165
+ import toReversedDimension = require( '@stdlib/ndarray-base-to-reversed-dimension' );
166
+ import toUniqueNormalizedIndices = require( '@stdlib/ndarray-base-to-unique-normalized-indices' );
105
167
  import transpose = require( '@stdlib/ndarray-base-transpose' );
106
168
  import unary = require( '@stdlib/ndarray-base-unary' );
169
+ import unaryAccumulate = require( '@stdlib/ndarray-base-unary-accumulate' );
170
+ import unaryAddonDispatch = require( '@stdlib/ndarray-base-unary-addon-dispatch' );
107
171
  import unaryBy = require( '@stdlib/ndarray-base-unary-by' );
172
+ import unaryInputCastingDataType = require( '@stdlib/ndarray-base-unary-input-casting-dtype' );
108
173
  import unaryLoopOrder = require( '@stdlib/ndarray-base-unary-loop-interchange-order' );
109
174
  import unaryOutputDataType = require( '@stdlib/ndarray-base-unary-output-dtype' );
175
+ import unaryReduceStrided1dDispatch = require( '@stdlib/ndarray-base-unary-reduce-strided1d-dispatch' );
176
+ import unaryReduceStrided1dDispatchBy = require( '@stdlib/ndarray-base-unary-reduce-strided1d-dispatch-by' );
177
+ import unaryReduceStrided1dDispatchByFactory = require( '@stdlib/ndarray-base-unary-reduce-strided1d-dispatch-by-factory' );
178
+ import unaryReduceStrided1dDispatchFactory = require( '@stdlib/ndarray-base-unary-reduce-strided1d-dispatch-factory' );
179
+ import unaryReduceSubarrayBy = require( '@stdlib/ndarray-base-unary-reduce-subarray-by' );
180
+ import unaryStrided1dDispatch = require( '@stdlib/ndarray-base-unary-strided1d-dispatch' );
181
+ import unaryStrided1dDispatchFactory = require( '@stdlib/ndarray-base-unary-strided1d-dispatch-factory' );
110
182
  import unaryBlockSize = require( '@stdlib/ndarray-base-unary-tiling-block-size' );
111
183
  import vind2bind = require( '@stdlib/ndarray-base-vind2bind' );
112
184
  import wrapIndex = require( '@stdlib/ndarray-base-wrap-index' );
113
185
  import zeros = require( '@stdlib/ndarray-base-zeros' );
114
186
  import zerosLike = require( '@stdlib/ndarray-base-zeros-like' );
187
+ import zip2views1d = require( '@stdlib/ndarray-base-zip2views1d' );
115
188
 
116
189
  /**
117
190
  * Interface describing the `base` namespace.
118
191
  */
119
192
  interface Namespace {
193
+ /**
194
+ * Tests whether at least one element in an ndarray is truthy.
195
+ *
196
+ * @param arrays - array-like object containing an input ndarray
197
+ * @returns boolean indicating whether at least one element is truthy
198
+ *
199
+ * @example
200
+ * var Float64Array = require( '@stdlib/array-float64' );
201
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
202
+ *
203
+ * // Create a data buffer:
204
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
205
+ *
206
+ * // Define the shape of the array:
207
+ * var shape = [ 3, 1, 2 ];
208
+ *
209
+ * // Define the array strides:
210
+ * var sx = [ 4, 4, 1 ];
211
+ *
212
+ * // Define the index offset:
213
+ * var ox = 1;
214
+ *
215
+ * // Create the input ndarray:
216
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
217
+ *
218
+ * // Test elements:
219
+ * var out = ns.any( [ x ] );
220
+ * // returns true
221
+ */
222
+ any: typeof any;
223
+
224
+ /**
225
+ * Tests whether at least one element in an ndarray passes a test implemented by a predicate function.
226
+ *
227
+ * @param arrays - array-like object containing an input ndarray
228
+ * @param predicate - predicate function
229
+ * @param thisArg - predicate function execution context
230
+ * @returns boolean indicating whether at least one element passes a test
231
+ *
232
+ * @example
233
+ * var Float64Array = require( '@stdlib/array-float64' );
234
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
235
+ *
236
+ * function predicate( value ) {
237
+ * return value > 0.0;
238
+ * }
239
+ *
240
+ * // Create a data buffer:
241
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
242
+ *
243
+ * // Define the shape of the array:
244
+ * var shape = [ 3, 1, 2 ];
245
+ *
246
+ * // Define the array strides:
247
+ * var sx = [ 4, 4, 1 ];
248
+ *
249
+ * // Define the index offset:
250
+ * var ox = 1;
251
+ *
252
+ * // Create the input ndarray:
253
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
254
+ *
255
+ * // Test elements:
256
+ * var out = ns.anyBy( [ x ], predicate );
257
+ * // returns true
258
+ */
259
+ anyBy: typeof anyBy;
260
+
120
261
  /**
121
262
  * Base ndarray assertion utilities.
122
263
  */
@@ -160,6 +301,69 @@ interface Namespace {
160
301
  */
161
302
  assign: typeof assign;
162
303
 
304
+ /**
305
+ * Applies a binary callback to elements in input ndarrays and assigns results to elements in an output ndarray.
306
+ *
307
+ * @param arrays - array-like object containing two input ndarrays and one output ndarray
308
+ * @param fcn - binary callback
309
+ * @throws arrays must have the same number of dimensions
310
+ * @throws arrays must have the same shape
311
+ *
312
+ * @example
313
+ * var Float64Array = require( '@stdlib/array-float64' );
314
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
315
+ * var getData = require( '@stdlib/ndarray-data-buffer' );
316
+ *
317
+ * function add( a, b ) {
318
+ * return a + b;
319
+ * }
320
+ *
321
+ * // Create data buffers:
322
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
323
+ * var ybuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
324
+ * var zbuf = new Float64Array( 6 );
325
+ *
326
+ * // Define the shape of the input and output arrays:
327
+ * var shape = [ 3, 1, 2 ];
328
+ *
329
+ * // Define the array strides:
330
+ * var sx = [ 2, 2, 1 ];
331
+ * var sy = [ 2, 2, 1 ];
332
+ * var sz = [ 2, 2, 1 ];
333
+ *
334
+ * // Define the index offsets:
335
+ * var ox = 0;
336
+ * var oy = 0;
337
+ * var oz = 0;
338
+ *
339
+ * // Create the input and output ndarrays:
340
+ * var x = new ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
341
+ * var y = new ndarray( 'float64', ybuf, shape, sy, oy, 'row-major' );
342
+ * var z = new ndarray( 'float64', zbuf, shape, sz, oz, 'row-major' );
343
+ *
344
+ * // Apply the ns.binary function:
345
+ * ns.binary( [ x, y, z ], add );
346
+ *
347
+ * console.log( getData( z ) );
348
+ * // => <Float64Array>[ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
349
+ */
350
+ binary: typeof binary;
351
+
352
+ /**
353
+ * Resolves the casting data type for an input ndarray provided to a binary function.
354
+ *
355
+ * @param idtype1 - input ndarray data type
356
+ * @param idtype2 - additional input ndarray data type
357
+ * @param odtype - output ndarray data type
358
+ * @param policy - input ndarray casting data type policy
359
+ * @returns input ndarray casting data type
360
+ *
361
+ * @example
362
+ * var dt = ns.binaryInputCastingDataType( 'float64', 'float64', 'float64', 'none' );
363
+ * // returns <string>
364
+ */
365
+ binaryInputCastingDataType: typeof binaryInputCastingDataType;
366
+
163
367
  /**
164
368
  * Reorders ndarray dimensions and associated strides for loop interchange.
165
369
  *
@@ -180,10 +384,10 @@ interface Namespace {
180
384
  *
181
385
  * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
182
386
  *
183
- * @param sh - array dimensions
184
- * @param sx - first input array stride lengths
185
- * @param sy - second input array stride lengths
186
- * @param sz - output array stride lengths
387
+ * @param shape - array dimensions
388
+ * @param stridesX - first input array stride lengths
389
+ * @param stridesY - second input array stride lengths
390
+ * @param stridesZ - output array stride lengths
187
391
  * @returns loop interchange data
188
392
  *
189
393
  * @example
@@ -193,7 +397,7 @@ interface Namespace {
193
397
  * var sy = [ 24, 8, 1 ]; // row-major
194
398
  * var sz = [ 1, -2, 6 ]; // column-major
195
399
  *
196
- * var o = loopOrder( sh, sx, sy, sz );
400
+ * var o = ns.binaryLoopOrder( sh, sx, sy, sz );
197
401
  * // returns {...}
198
402
  *
199
403
  * var ssh = o.sh;
@@ -210,6 +414,94 @@ interface Namespace {
210
414
  */
211
415
  binaryLoopOrder: typeof binaryLoopOrder;
212
416
 
417
+ /**
418
+ * Resolves the output ndarray data type for a binary function.
419
+ *
420
+ * @param xdtype - first input ndarray data type
421
+ * @param ydtype - second input ndarray data type
422
+ * @param policy - output ndarray data type policy
423
+ * @returns output ndarray data type
424
+ *
425
+ * @example
426
+ * var dt = ns.binaryOutputDataType( 'float64', 'float32', 'complex_floating_point' );
427
+ * // returns <DataType>
428
+ */
429
+ binaryOutputDataType: typeof binaryOutputDataType;
430
+
431
+ /**
432
+ * Constructor for performing a reduction on two input ndarrays.
433
+ *
434
+ * @param table - dispatch table
435
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
436
+ * @param odtypes - list of supported output data types
437
+ * @param policies - dispatch policies
438
+ * @returns instance
439
+ *
440
+ * @example
441
+ * var base = require( '@stdlib/blas-base-ndarray-gdot' );
442
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
443
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
444
+ *
445
+ * var idt = dtypes( 'real_and_generic' );
446
+ * var odt = idt;
447
+ * var policies = {
448
+ * 'output': 'promoted',
449
+ * 'casting': 'promoted'
450
+ * };
451
+ *
452
+ * var table = {
453
+ * 'default': base
454
+ * };
455
+ * var dot = new ns.binaryReduceStrided1dDispatch( table, [ idt, idt ], odt, policies );
456
+ *
457
+ * var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ];
458
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
459
+ *
460
+ * var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ];
461
+ * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
462
+ *
463
+ * var z = dot.apply( x, y );
464
+ * // returns <ndarray>[ -5.0 ]
465
+ */
466
+ binaryReduceStrided1dDispatch: typeof binaryReduceStrided1dDispatch;
467
+
468
+ /**
469
+ * Creates a function for performing a reduction on two input ndarrays.
470
+ *
471
+ * @param table - dispatch table
472
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
473
+ * @param odtypes - list of supported output data types
474
+ * @param policies - dispatch policies
475
+ * @returns function for applying a function
476
+ *
477
+ * @example
478
+ * var base = require( '@stdlib/blas-base-ndarray-gdot' );
479
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
480
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
481
+ *
482
+ * var idt = dtypes( 'real_and_generic' );
483
+ * var odt = idt;
484
+ * var policies = {
485
+ * 'output': 'promoted',
486
+ * 'casting': 'promoted'
487
+ * };
488
+ *
489
+ * var table = {
490
+ * 'default': base
491
+ * };
492
+ * var dot = ns.binaryReduceStrided1dDispatchFactory( table, [ idt, idt ], odt, policies );
493
+ *
494
+ * var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ];
495
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
496
+ *
497
+ * var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ];
498
+ * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
499
+ *
500
+ * var z = dot( x, y );
501
+ * // returns <ndarray>[ -5.0 ]
502
+ */
503
+ binaryReduceStrided1dDispatchFactory: typeof binaryReduceStrided1dDispatchFactory;
504
+
213
505
  /**
214
506
  * Returns a loop block size for multi-dimensional array tiled loops.
215
507
  *
@@ -299,6 +591,62 @@ interface Namespace {
299
591
  */
300
592
  broadcastArray: typeof broadcastArray;
301
593
 
594
+ /**
595
+ * Broadcasts an input ndarray to a target shape while keeping a list of specified dimensions unchanged.
596
+ *
597
+ * ## Notes
598
+ *
599
+ * - The function expects that each index in the list of dimensions is negative in order to ensure that indices correspond to the same relative position in the output ndarray shape. For example, given an input ndarray shape `[2,X1,X2]` and a desired shape `[6,7,2,Y1,Y2]`, a list of negative dimensions `[-2,-1]` correctly maps the unchanged dimensions `X` in the input ndarray to ignored dimensions `Y` in the provided target shape. Nonnegative indices, however, afford no such mapping. For example, the list of dimensions `[1,2]` corresponds to `[X1,X2]` in the input ndarray shape, but to `[7,2]` in the target shape, which is not desired. By expecting negative indices, we avoid confusion and ensure that users always refer to dimensions relative to the last broadcasted dimension.
600
+ * - The function throws an error if a provided ndarray is incompatible with a provided shape.
601
+ * - The returned array is a view on the input array data buffer. The view is typically **not** contiguous. As more than one element of a returned view may refer to the same memory location, writing to the view may affect multiple elements. If you need to write to the returned array, copy the array before performing operations which may mutate elements.
602
+ * - The returned array is a "base" ndarray, and, thus, the returned array 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 broadcast an ndarray-like object within internal implementations and to do so with minimal overhead.
603
+ * - The function always returns a new ndarray instance even if the input ndarray shape and the desired shape are the same.
604
+ *
605
+ * @param arr - input array
606
+ * @param shape - desired shape
607
+ * @param dims - list of dimensions to exclude from broadcasting
608
+ * @throws input array cannot have more dimensions than the desired shape
609
+ * @throws broadcasted dimensions in the input array and desired shape must be broadcast compatible
610
+ * @throws dimension indices must not exceed desired shape bounds
611
+ * @throws must provide unique dimension indices
612
+ * @returns broadcasted array
613
+ *
614
+ * @example
615
+ * var array = require( '@stdlib/ndarray-array' );
616
+ * var getShape = require( '@stdlib/ndarray-shape' );
617
+ *
618
+ * var x = array( [ [ 1, 2, 3 ] ] );
619
+ * // returns <ndarray>
620
+ *
621
+ * var shx = getShape( x );
622
+ * // returns [ 1, 3 ]
623
+ *
624
+ * var y = ns.broadcastArrayExceptDimensions( x, [ 2, 2, 3 ], [ -2 ] );
625
+ * // returns <ndarray>
626
+ *
627
+ * var shy = getShape( y );
628
+ * // returns [ 2, 1, 3 ]
629
+ *
630
+ * var v = y.get( 0, 0, 0 );
631
+ * // returns 1
632
+ *
633
+ * v = y.get( 0, 0, 1 );
634
+ * // returns 2
635
+ *
636
+ * v = y.get( 0, 0, 2 );
637
+ * // returns 3
638
+ *
639
+ * v = y.get( 1, 0, 0 );
640
+ * // returns 1
641
+ *
642
+ * v = y.get( 1, 0, 1 );
643
+ * // returns 2
644
+ *
645
+ * v = y.get( 1, 0, 2 );
646
+ * // returns 3
647
+ */
648
+ broadcastArrayExceptDimensions: typeof broadcastArrayExceptDimensions;
649
+
302
650
  /**
303
651
  * Broadcasts ndarrays to a common shape.
304
652
  *
@@ -330,7 +678,7 @@ interface Namespace {
330
678
  * // returns [ 3, 2, 2 ]
331
679
  *
332
680
  * var out = ns.broadcastArrays( [ x1, y1 ] );
333
- * // returns <ndarray>
681
+ * // returns [ <ndarray>, <ndarray> ]
334
682
  *
335
683
  * var x2 = out[ 0 ];
336
684
  * // returns <ndarray>
@@ -386,13 +734,16 @@ interface Namespace {
386
734
  * @returns ndarray
387
735
  *
388
736
  * @example
737
+ * var getShape = require( '@stdlib/ndarray-shape' );
738
+ * var getDType = require( '@stdlib/ndarray-dtype' );
739
+ *
389
740
  * var x = ns.broadcastScalar( 1.0, 'generic', [ 2, 2 ], 'row-major' );
390
741
  * // returns <ndarray>
391
742
  *
392
- * var sh = x.shape;
743
+ * var sh = getShape( x );
393
744
  * // returns [ 2, 2 ]
394
745
  *
395
- * var dt = x.dtype;
746
+ * var dt = String( getDType( x ) );
396
747
  * // returns 'generic'
397
748
  *
398
749
  * var v = x.get( 0, 1 );
@@ -400,6 +751,28 @@ interface Namespace {
400
751
  */
401
752
  broadcastScalar: typeof broadcastScalar;
402
753
 
754
+ /**
755
+ * Broadcasts a scalar value to an ndarray having the same shape and data type as a provided input ndarray.
756
+ *
757
+ * @param x - input array
758
+ * @param value - scalar value
759
+ * @returns output ndarray
760
+ *
761
+ * @example
762
+ * var zeros = require( '@stdlib/ndarray-base-zeros' );
763
+ * var getDType = require( '@stdlib/ndarray-dtype' );
764
+ *
765
+ * var x = zeros( 'float64', [ 2, 2 ], 'row-major' );
766
+ * // returns <ndarray>[ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ]
767
+ *
768
+ * var y = ns.broadcastScalarLike( x, 1.0 );
769
+ * // returns <ndarray>[ [ 1.0, 1.0 ], [ 1.0, 1.0 ] ]
770
+ *
771
+ * var dt = String( getDType( y ) );
772
+ * // returns 'float64'
773
+ */
774
+ broadcastScalarLike: typeof broadcastScalarLike;
775
+
403
776
  /**
404
777
  * Broadcasts array shapes to a single shape.
405
778
  *
@@ -610,7 +983,7 @@ interface Namespace {
610
983
  bufferDataTypeEnum: typeof bufferDataTypeEnum;
611
984
 
612
985
  /**
613
- * Returns the number of bytes per element provided an underlying array data type.
986
+ * Returns the number of bytes per element for a provided underlying ndarray data type.
614
987
  *
615
988
  * @param dtype - data type
616
989
  * @returns number of bytes per element
@@ -655,88 +1028,268 @@ interface Namespace {
655
1028
  clampIndex: typeof clampIndex;
656
1029
 
657
1030
  /**
658
- * ndarray constructor.
659
- *
660
- * ## Notes
1031
+ * Returns the shape defined by the dimensions which are not included in a list of dimensions.
661
1032
  *
662
- * - To create a zero-dimensional array,
1033
+ * @param shape - array shape
1034
+ * @param dims - list of dimensions
1035
+ * @returns output shape
663
1036
  *
664
- * ```javascript
665
- * var buffer = [ 1 ];
666
- * var shape = [];
667
- * var strides = [ 0 ];
668
- * var offset = 0;
1037
+ * @example
1038
+ * var sh = ns.complementShape( [ 3, 2 ], [ -1 ] );
1039
+ * // returns [ 3 ]
669
1040
  *
670
- * var out = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
671
- * ```
1041
+ * sh = ns.complementShape( [ 3, 2, 1 ], [ -2 ] );
1042
+ * // returns [ 3, 1 ]
672
1043
  *
673
- * @param dtype - data type
674
- * @param buffer - data buffer
675
- * @param shape - array shape
676
- * @param strides - array strides
677
- * @param offset - index offset
678
- * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
679
- * @returns ndarray instance
1044
+ * sh = ns.complementShape( [ 3 ], [ 0 ] );
1045
+ * // returns []
680
1046
  *
681
- * @example
682
- * var buffer = [ 1, 2, 3, 4, 5, 6 ];
683
- * var shape = [ 3, 2 ];
684
- * var strides = [ 2, 1 ];
685
- * var offset = 0;
1047
+ * sh = ns.complementShape( [ 3, 2 ], [ 0 ] );
1048
+ * // returns [ 2 ]
686
1049
  *
687
- * var out = ns.ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
1050
+ * sh = ns.complementShape( [], [] );
1051
+ * // returns []
688
1052
  */
689
- ndarray: typeof ndarray;
1053
+ complementShape: typeof complementShape;
690
1054
 
691
1055
  /**
692
- * Returns the underlying data buffer of a provided ndarray.
1056
+ * Copies an input ndarray to a new ndarray having the same shape and data type.
693
1057
  *
694
- * @param x - input ndarray
695
- * @returns underlying data buffer
1058
+ * ## Notes
1059
+ *
1060
+ * - The function performs a full copy in which an ndarray's underlying data is copied to a new underlying data buffer.
1061
+ *
1062
+ * @param x - input array
1063
+ * @returns output array
696
1064
  *
697
1065
  * @example
698
- * var zeros = require( '@stdlib/ndarray-zeros' );
1066
+ * var getShape = require( '@stdlib/ndarray-shape' );
1067
+ * var getDType = require( '@stdlib/ndarray-dtype' );
1068
+ * var zeros = require( '@stdlib/ndarray-base-zeros' );
699
1069
  *
700
- * var x = zeros( [ 3, 3, 3 ], {
701
- * 'dtype': 'float64'
702
- * });
1070
+ * var x = zeros( 'float64', [ 2, 2 ], 'row-major' );
1071
+ * // returns <ndarray>
703
1072
  *
704
- * var out = ns.data( x );
705
- * // returns <Float64Array>
1073
+ * var sh = getShape( x );
1074
+ * // returns [ 2, 2 ]
1075
+ *
1076
+ * var y = ns.copy( x );
1077
+ * // returns <ndarray>
1078
+ *
1079
+ * sh = getShape( y );
1080
+ * // returns [ 2, 2 ]
706
1081
  */
707
- data: typeof data;
1082
+ copy: typeof copy;
708
1083
 
709
1084
  /**
710
- * Returns the data type of a provided ndarray.
1085
+ * Counts the number of falsy elements in an ndarray.
711
1086
  *
712
- * @param x - input ndarray
713
- * @returns data type
1087
+ * @param arrays - array-like object containing an input ndarray
1088
+ * @returns number of falsy elements
714
1089
  *
715
1090
  * @example
716
- * var zeros = require( '@stdlib/ndarray-zeros' );
1091
+ * var Float64Array = require( '@stdlib/array-float64' );
1092
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
717
1093
  *
718
- * var x = zeros( [ 3, 3, 3 ], {
719
- * 'ns.dtype': 'float64'
720
- * });
1094
+ * // Create a data buffer:
1095
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
721
1096
  *
722
- * var dt = ns.dtype( x );
723
- * // returns 'float64'
724
- */
725
- dtype: typeof dtype;
726
-
727
- /**
728
- * Returns an object mapping data type strings to single letter character abbreviations.
1097
+ * // Define the shape of the input array:
1098
+ * var shape = [ 3, 1, 2 ];
729
1099
  *
730
- * @returns object mapping data type strings to single letter character abbreviations
1100
+ * // Define the array strides:
1101
+ * var sx = [ 4, 4, 1 ];
731
1102
  *
732
- * @example
733
- * var obj = ns.dtypeChar();
734
- * // returns {...}
1103
+ * // Define the index offset:
1104
+ * var ox = 1;
1105
+ *
1106
+ * // Create the input ndarray:
1107
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
1108
+ *
1109
+ * // Perform operation:
1110
+ * var out = ns.countFalsy( [ x ] );
1111
+ * // returns 1
735
1112
  */
736
- dtypeChar: typeof dtypeChar;
1113
+ countFalsy: typeof countFalsy;
737
1114
 
738
1115
  /**
739
- * Returns an object mapping data type strings to descriptions.
1116
+ * Counts the number of elements in an ndarray which pass a test implemented by a predicate function.
1117
+ *
1118
+ * @param arrays - array-like object containing an input ndarray
1119
+ * @param predicate - predicate function
1120
+ * @param thisArg - predicate function execution context
1121
+ * @returns result
1122
+ *
1123
+ * @example
1124
+ * var Float64Array = require( '@stdlib/array-float64' );
1125
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
1126
+ *
1127
+ * function predicate( value ) {
1128
+ * return value > 0.0;
1129
+ * }
1130
+ *
1131
+ * // Create a data buffer:
1132
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
1133
+ *
1134
+ * // Define the shape of the array:
1135
+ * var shape = [ 3, 1, 2 ];
1136
+ *
1137
+ * // Define the array strides:
1138
+ * var sx = [ 4, 4, 1 ];
1139
+ *
1140
+ * // Define the index offset:
1141
+ * var ox = 1;
1142
+ *
1143
+ * // Create the input ndarray:
1144
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
1145
+ *
1146
+ * // Perform operation:
1147
+ * var out = ns.countIf( [ x ], predicate );
1148
+ * // returns 5
1149
+ */
1150
+ countIf: typeof countIf;
1151
+
1152
+ /**
1153
+ * Counts the number of truthy elements in an ndarray.
1154
+ *
1155
+ * @param arrays - array-like object containing an input ndarray
1156
+ * @returns number of truthy elements
1157
+ *
1158
+ * @example
1159
+ * var Float64Array = require( '@stdlib/array-float64' );
1160
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
1161
+ *
1162
+ * // Create a data buffer:
1163
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
1164
+ *
1165
+ * // Define the shape of the input array:
1166
+ * var shape = [ 3, 1, 2 ];
1167
+ *
1168
+ * // Define the array strides:
1169
+ * var sx = [ 4, 4, 1 ];
1170
+ *
1171
+ * // Define the index offset:
1172
+ * var ox = 1;
1173
+ *
1174
+ * // Create the input ndarray:
1175
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
1176
+ *
1177
+ * // Perform operation:
1178
+ * var out = ns.countTruthy( [ x ] );
1179
+ * // returns 6
1180
+ */
1181
+ countTruthy: typeof countTruthy;
1182
+
1183
+ /**
1184
+ * ndarray constructor.
1185
+ *
1186
+ * ## Notes
1187
+ *
1188
+ * - To create a zero-dimensional array,
1189
+ *
1190
+ * ```javascript
1191
+ * var buffer = [ 1 ];
1192
+ * var shape = [];
1193
+ * var strides = [ 0 ];
1194
+ * var offset = 0;
1195
+ *
1196
+ * var out = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
1197
+ * ```
1198
+ *
1199
+ * @param dtype - data type
1200
+ * @param buffer - data buffer
1201
+ * @param shape - array shape
1202
+ * @param strides - array strides
1203
+ * @param offset - index offset
1204
+ * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
1205
+ * @returns ndarray instance
1206
+ *
1207
+ * @example
1208
+ * var buffer = [ 1, 2, 3, 4, 5, 6 ];
1209
+ * var shape = [ 3, 2 ];
1210
+ * var strides = [ 2, 1 ];
1211
+ * var offset = 0;
1212
+ *
1213
+ * var out = ns.ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
1214
+ */
1215
+ ndarray: typeof ndarray;
1216
+
1217
+ /**
1218
+ * Returns the underlying data buffer of a provided ndarray.
1219
+ *
1220
+ * @param x - input ndarray
1221
+ * @returns underlying data buffer
1222
+ *
1223
+ * @example
1224
+ * var zeros = require( '@stdlib/ndarray-zeros' );
1225
+ *
1226
+ * var x = zeros( [ 3, 3, 3 ], {
1227
+ * 'dtype': 'float64'
1228
+ * });
1229
+ *
1230
+ * var out = ns.data( x );
1231
+ * // returns <Float64Array>
1232
+ */
1233
+ data: typeof data;
1234
+
1235
+ /**
1236
+ * Returns the data type of a provided ndarray.
1237
+ *
1238
+ * @param x - input ndarray
1239
+ * @returns data type
1240
+ *
1241
+ * @example
1242
+ * var zeros = require( '@stdlib/ndarray-zeros' );
1243
+ *
1244
+ * var x = zeros( [ 3, 3, 3 ], {
1245
+ * 'ns.dtype': 'float64'
1246
+ * });
1247
+ *
1248
+ * var dt = ns.dtype( x );
1249
+ * // returns 'float64'
1250
+ */
1251
+ dtype: typeof dtype;
1252
+
1253
+ /**
1254
+ * Returns an object mapping data type strings to alignments.
1255
+ *
1256
+ * @returns object mapping data type strings to alignments
1257
+ *
1258
+ * @example
1259
+ * var obj = ns.dtypeAlignment();
1260
+ * // returns {...}
1261
+ */
1262
+ dtypeAlignment: typeof dtypeAlignment;
1263
+
1264
+ /**
1265
+ * Returns an object mapping data type strings to single letter character abbreviations.
1266
+ *
1267
+ * @returns object mapping data type strings to single letter character abbreviations
1268
+ *
1269
+ * @example
1270
+ * var obj = ns.dtypeChar();
1271
+ * // returns {...}
1272
+ */
1273
+ dtypeChar: typeof dtypeChar;
1274
+
1275
+ /**
1276
+ * Returns a list of ndarray data type single letter character abbreviations.
1277
+ *
1278
+ * @param kind - data type kind
1279
+ * @returns list of ndarray data type single letter character abbreviations
1280
+ *
1281
+ * @example
1282
+ * var list = ns.dtypeChars();
1283
+ * // returns [...]
1284
+ *
1285
+ * @example
1286
+ * var list = ns.dtypeChars( 'floating_point' );
1287
+ * // returns [...]
1288
+ */
1289
+ dtypeChars: typeof dtypeChars;
1290
+
1291
+ /**
1292
+ * Returns an object mapping data type strings to descriptions.
740
1293
  *
741
1294
  * @returns object mapping data type strings to descriptions
742
1295
  *
@@ -763,6 +1316,33 @@ interface Namespace {
763
1316
  */
764
1317
  dtypeEnum2Str: typeof dtypeEnum2Str;
765
1318
 
1319
+ /**
1320
+ * Returns an object mapping supported data type strings to enumeration constants.
1321
+ *
1322
+ * ## Notes
1323
+ *
1324
+ * - Downstream consumers of this mapping should **not** rely on specific integer values (e.g., `INT8 == 0`). Instead, the object should be used in an opaque manner.
1325
+ * - The main purpose of this function is JavaScript and C inter-operation of ndarray objects.
1326
+ *
1327
+ * @returns object mapping supported data type strings to enumeration constants
1328
+ *
1329
+ * @example
1330
+ * var o = ns.dtypeEnums();
1331
+ * // returns {...}
1332
+ */
1333
+ dtypeEnums: typeof dtypeEnums;
1334
+
1335
+ /**
1336
+ * Returns an object mapping supported data type strings to data type objects.
1337
+ *
1338
+ * @returns object mapping supported data type strings to data type objects
1339
+ *
1340
+ * @example
1341
+ * var o = ns.dtypeObjects();
1342
+ * // returns {...}
1343
+ */
1344
+ dtypeObjects: typeof dtypeObjects;
1345
+
766
1346
  /**
767
1347
  * Returns the enumeration constant associated with an ndarray data type value.
768
1348
  *
@@ -809,6 +1389,22 @@ interface Namespace {
809
1389
  */
810
1390
  dtypeStr2Enum: typeof dtypeStr2Enum;
811
1391
 
1392
+ /**
1393
+ * Returns a list of ndarray data type strings.
1394
+ *
1395
+ * @param kind - data type kind
1396
+ * @returns list of ndarray data type strings
1397
+ *
1398
+ * @example
1399
+ * var list = ns.dtypeStrings();
1400
+ * // returns [...]
1401
+ *
1402
+ * @example
1403
+ * var list = ns.dtypeStrings( 'floating_point' );
1404
+ * // returns [...]
1405
+ */
1406
+ dtypeStrings: typeof dtypeStrings;
1407
+
812
1408
  /**
813
1409
  * Returns the C data type associated with a provided data type value.
814
1410
  *
@@ -824,6 +1420,26 @@ interface Namespace {
824
1420
  */
825
1421
  dtype2c: typeof dtype2c;
826
1422
 
1423
+ /**
1424
+ * Resolves a list of data type enumeration constants.
1425
+ *
1426
+ * ## Notes
1427
+ *
1428
+ * - If the function is unable to resolve an enumeration constant for a provided data type, the corresponding element in the returned array will be `null`.
1429
+ *
1430
+ * @param dtypes - list of data types
1431
+ * @returns results
1432
+ *
1433
+ * @example
1434
+ * var out = ns.dtypes2enums( [ 'float32', 'float64' ] );
1435
+ * // returns [...]
1436
+ *
1437
+ * @example
1438
+ * var out = ns.dtypes2enums( [ 'foo', 'bar' ] );
1439
+ * // returns [ null, null ]
1440
+ */
1441
+ dtypes2enums: typeof dtypes2enums;
1442
+
827
1443
  /**
828
1444
  * Transforms a list of array argument data types into a list of signatures.
829
1445
  *
@@ -848,6 +1464,26 @@ interface Namespace {
848
1464
  */
849
1465
  dtypes2signatures: typeof dtypes2signatures;
850
1466
 
1467
+ /**
1468
+ * Resolves a list of data type strings.
1469
+ *
1470
+ * ## Notes
1471
+ *
1472
+ * - If the function is unable to resolve a data type string for a provided data type, the corresponding element in the returned array will be `null`.
1473
+ *
1474
+ * @param dtypes - list of data types
1475
+ * @returns results
1476
+ *
1477
+ * @example
1478
+ * var out = ns.dtypes2strings( [ 'float32', 'float64' ] );
1479
+ * // returns [...]
1480
+ *
1481
+ * @example
1482
+ * var out = ns.dtypes2strings( [ 'foo', 'bar' ] );
1483
+ * // returns [ null, null ]
1484
+ */
1485
+ dtypes2strings: typeof dtypes2strings;
1486
+
851
1487
  /**
852
1488
  * Creates an uninitialized array having a specified shape and data type.
853
1489
  *
@@ -898,79 +1534,320 @@ interface Namespace {
898
1534
  emptyLike: typeof emptyLike;
899
1535
 
900
1536
  /**
901
- * Expands the shape of an array by inserting a new dimension of size one at a specified axis.
902
- *
903
- * ## Notes
904
- *
905
- * - A provided axis must reside on the interval `[-N-1, N]`, where `N` is the rank (i.e., number of dimensions) of the provided input array. If provided a negative `axis`, the axis position at which to insert a singleton dimension is computed as `N + axis + 1`. Hence, if provided `-1`, the resolved axis position is `N` (i.e., a singleton dimension is appended to the input array).
1537
+ * Tests whether every element in an ndarray is truthy.
906
1538
  *
907
- * @param x - input array
908
- * @param axis - axis at which to insert a singleton dimension
909
- * @returns output array
1539
+ * @param arrays - array-like object containing an input ndarray
1540
+ * @returns boolean indicating whether every element is truthy
910
1541
  *
911
1542
  * @example
912
- * var array = require( '@stdlib/ndarray-array' );
913
- *
914
- * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
915
- * // returns <ndarray>
916
- *
917
- * var shx = x.shape;
918
- * // returns [ 2, 2 ]
1543
+ * var Float64Array = require( '@stdlib/array-float64' );
1544
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
919
1545
  *
920
- * var y = ns.expandDimensions( x, 1 );
921
- * // returns <ndarray>
1546
+ * // Create a data buffer:
1547
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
922
1548
  *
923
- * var shy = y.shape;
924
- * // returns [ 2, 1, 2 ]
1549
+ * // Define the shape of the input array:
1550
+ * var shape = [ 3, 1, 2 ];
925
1551
  *
926
- * var v = y.get( 0, 0, 0 );
927
- * // returns 1
1552
+ * // Define the array strides:
1553
+ * var sx = [ 4, 4, 1 ];
928
1554
  *
929
- * v = y.get( 0, 0, 1 );
930
- * // returns 2
1555
+ * // Define the index offset:
1556
+ * var ox = 1;
931
1557
  *
932
- * v = y.get( 1, 0, 0 );
933
- * // returns 3
1558
+ * // Create the input ndarray:
1559
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
934
1560
  *
935
- * v = y.get( 1, 0, 1 );
936
- * // returns 4
1561
+ * // Test elements:
1562
+ * var out = ns.every( [ x ] );
1563
+ * // returns true
937
1564
  */
938
- expandDimensions: typeof expandDimensions;
1565
+ every: typeof every;
939
1566
 
940
1567
  /**
941
- * Returns a specified flag for a provided ndarray.
1568
+ * Tests whether all elements in an ndarray pass a test implemented by a predicate function.
942
1569
  *
943
- * @param x - input ndarray
944
- * @param name - flag name
945
- * @returns flag value
1570
+ * @param arrays - array-like object containing an input ndarray
1571
+ * @param predicate - predicate function
1572
+ * @param thisArg - predicate function execution context
1573
+ * @returns boolean indicating whether all elements pass a test
946
1574
  *
947
1575
  * @example
948
- * var zeros = require( '@stdlib/ndarray-zeros' );
1576
+ * var Float64Array = require( '@stdlib/array-float64' );
1577
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
949
1578
  *
950
- * var o = ns.flag( zeros( [ 3, 3, 3 ] ), 'READONLY' );
951
- * // returns <boolean>
1579
+ * function predicate( value ) {
1580
+ * return value > 0.0;
1581
+ * }
1582
+ *
1583
+ * // Create a data buffer:
1584
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
1585
+ *
1586
+ * // Define the shape of the array:
1587
+ * var shape = [ 3, 1, 2 ];
1588
+ *
1589
+ * // Define the array strides:
1590
+ * var sx = [ 4, 4, 1 ];
1591
+ *
1592
+ * // Define the index offset:
1593
+ * var ox = 1;
1594
+ *
1595
+ * // Create the input ndarray:
1596
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
1597
+ *
1598
+ * // Test elements:
1599
+ * var out = ns.everyBy( [ x ], predicate );
1600
+ * // returns true
952
1601
  */
953
- flag: typeof flag;
1602
+ everyBy: typeof everyBy;
954
1603
 
955
1604
  /**
956
- * Returns the flags of a provided ndarray.
1605
+ * Expands the shape of an array by inserting a new dimension of size one at a specified dimension index.
957
1606
  *
958
1607
  * ## Notes
959
1608
  *
960
- * - When `copy` is `false`, changes to the returned object may mutate the input ndarray flags. If there is a chance that the returned object will be mutated (either directly or by downstream consumers), set `copy` to `true` to prevent unintended side effects.
1609
+ * - A provided dimension index must reside on the interval `[-N-1, N]`, where `N` is the rank (i.e., number of dimensions) of the provided input array. If provided a negative dimension index, the position at which to insert a singleton dimension is computed as `N + dim + 1`. Hence, if provided `-1`, the resolved position is `N` (i.e., a singleton dimension is appended to the input array).
961
1610
  *
962
- * @param x - input ndarray
963
- * @param copy - boolean indicating whether to explicitly copy the value assigned to the input ndarray's `flags` property
964
- * @returns flags
1611
+ * @param x - input array
1612
+ * @param dim - dimension index at which to insert a singleton dimension
1613
+ * @param writable - boolean indicating whether the returned ndarray should be writable
1614
+ * @returns output array
965
1615
  *
966
1616
  * @example
967
- * var zeros = require( '@stdlib/ndarray-zeros' );
1617
+ * var array = require( '@stdlib/ndarray-array' );
1618
+ *
1619
+ * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
1620
+ * // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
1621
+ *
1622
+ * var y = ns.expandDimensions( x, 1, false );
1623
+ * // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
1624
+ */
1625
+ expandDimensions: typeof expandDimensions;
1626
+
1627
+ /**
1628
+ * Fills an input ndarray with a specified value.
1629
+ *
1630
+ * ## Notes
1631
+ *
1632
+ * - A `value` must be able to safely cast to the input ndarray data type. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a `'float32'` input ndarray).
1633
+ *
1634
+ * @param x - input ndarray
1635
+ * @param value - scalar value
1636
+ * @returns input ndarray
1637
+ *
1638
+ * @example
1639
+ * var Float64Array = require( '@stdlib/array-float64' );
1640
+ *
1641
+ * // Create a data buffer:
1642
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
1643
+ *
1644
+ * // Define the shape of the input array:
1645
+ * var shape = [ 3, 1, 2 ];
1646
+ *
1647
+ * // Define the array strides:
1648
+ * var sx = [ 2, 2, 1 ];
1649
+ *
1650
+ * // Define the index offset:
1651
+ * var ox = 0;
1652
+ *
1653
+ * // Create the input ndarray-like object:
1654
+ * var x = {
1655
+ * 'dtype': 'float64',
1656
+ * 'data': xbuf,
1657
+ * 'shape': shape,
1658
+ * 'strides': sx,
1659
+ * 'offset': ox,
1660
+ * 'order': 'row-major'
1661
+ * };
1662
+ *
1663
+ * var out = ns.fill( x, 10.0 );
1664
+ *
1665
+ * console.log( x.data );
1666
+ * // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
1667
+ *
1668
+ * var bool = ( out === x );
1669
+ * // returns true
1670
+ */
1671
+ fill: typeof fill;
1672
+
1673
+ /**
1674
+ * Fills an input ndarray according to a callback function.
1675
+ *
1676
+ * @param x - input ndarray
1677
+ * @param fcn - callback function
1678
+ * @param thisArg - callback function execution context
1679
+ * @returns input ndarray
1680
+ *
1681
+ * @example
1682
+ * var Float64Array = require( '@stdlib/array-float64' );
1683
+ *
1684
+ * function fcn() {
1685
+ * return 10.0;
1686
+ * }
1687
+ *
1688
+ * // Create a data buffer:
1689
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
1690
+ *
1691
+ * // Define the shape of the input array:
1692
+ * var shape = [ 3, 1, 2 ];
1693
+ *
1694
+ * // Define the array strides:
1695
+ * var sx = [ 2, 2, 1 ];
1696
+ *
1697
+ * // Define the index offset:
1698
+ * var ox = 0;
1699
+ *
1700
+ * // Create the input ndarray-like object:
1701
+ * var x = {
1702
+ * 'dtype': 'float64',
1703
+ * 'data': xbuf,
1704
+ * 'shape': shape,
1705
+ * 'strides': sx,
1706
+ * 'offset': ox,
1707
+ * 'order': 'row-major'
1708
+ * };
1709
+ *
1710
+ * var out = ns.fillBy( x, fcn );
1711
+ *
1712
+ * console.log( x.data );
1713
+ * // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
1714
+ *
1715
+ * var bool = ( out === x );
1716
+ * // returns true
1717
+ */
1718
+ fillBy: typeof fillBy;
1719
+
1720
+ /**
1721
+ * Returns the first element in an ndarray which passes a test implemented by a predicate function.
1722
+ *
1723
+ * ## Notes
1724
+ *
1725
+ * - The function returns the sentinel value if no element in an input ndarray passes a test implemented by a predicate function.
1726
+ *
1727
+ * @param arrays - array-like object containing an input ndarray and a zero-dimensional ndarray containing a sentinel value
1728
+ * @param predicate - predicate function
1729
+ * @param thisArg - predicate function execution context
1730
+ * @returns result
1731
+ *
1732
+ * @example
1733
+ * var Float64Array = require( '@stdlib/array-float64' );
1734
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
1735
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
1736
+ *
1737
+ * function predicate( value ) {
1738
+ * return value % 2.0 === 0.0;
1739
+ * }
1740
+ *
1741
+ * // Create data buffers:
1742
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
1743
+ *
1744
+ * // Define the shape of the input array:
1745
+ * var shape = [ 3, 1, 2 ];
1746
+ *
1747
+ * // Define the array strides:
1748
+ * var sx = [ 4, 4, 1 ];
1749
+ *
1750
+ * // Define the index offset:
1751
+ * var ox = 0;
1752
+ *
1753
+ * // Create the input ndarray:
1754
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
1755
+ *
1756
+ * // Create a zero-dimensional ndarray containing a sentinel value:
1757
+ * var sv = scalar2ndarray( NaN, {
1758
+ * 'dtype': 'float64'
1759
+ * });
1760
+ *
1761
+ * // Perform reduction:
1762
+ * var out = ns.find( [ x, sv ], predicate );
1763
+ * // returns 2.0
1764
+ */
1765
+ find: typeof find;
1766
+
1767
+ /**
1768
+ * Returns a specified flag for a provided ndarray.
1769
+ *
1770
+ * @param x - input ndarray
1771
+ * @param name - flag name
1772
+ * @returns flag value
1773
+ *
1774
+ * @example
1775
+ * var zeros = require( '@stdlib/ndarray-zeros' );
1776
+ *
1777
+ * var o = ns.flag( zeros( [ 3, 3, 3 ] ), 'READONLY' );
1778
+ * // returns <boolean>
1779
+ */
1780
+ flag: typeof flag;
1781
+
1782
+ /**
1783
+ * Returns the flags of a provided ndarray.
1784
+ *
1785
+ * ## Notes
1786
+ *
1787
+ * - When `copy` is `false`, changes to the returned object may mutate the input ndarray flags. If there is a chance that the returned object will be mutated (either directly or by downstream consumers), set `copy` to `true` to prevent unintended side effects.
1788
+ *
1789
+ * @param x - input ndarray
1790
+ * @param copy - boolean indicating whether to explicitly copy the value assigned to the input ndarray's `flags` property
1791
+ * @returns flags
1792
+ *
1793
+ * @example
1794
+ * var zeros = require( '@stdlib/ndarray-zeros' );
968
1795
  *
969
1796
  * var o = ns.flags( zeros( [ 3, 3, 3 ] ), false );
970
1797
  * // returns {...}
971
1798
  */
972
1799
  flags: typeof flags;
973
1800
 
1801
+ /**
1802
+ * Flattens a shape to a specified depth.
1803
+ *
1804
+ * @param shape - array shape
1805
+ * @param depth - maximum depth to flatten
1806
+ * @returns flattened shape
1807
+ *
1808
+ * @example
1809
+ * var sh = ns.flattenShape( [ 3, 2 ], 1 );
1810
+ * // returns [ 6 ]
1811
+ *
1812
+ * sh = ns.flattenShape( [ 3, 2, 1 ], 1 );
1813
+ * // returns [ 6, 1 ]
1814
+ *
1815
+ * sh = ns.flattenShape( [ 3 ], 0 );
1816
+ * // returns [ 3 ]
1817
+ *
1818
+ * sh = ns.flattenShape( [ 3, 2 ], 0 );
1819
+ * // returns [ 3, 2 ]
1820
+ *
1821
+ * sh = ns.flattenShape( [ 3 ], 1 );
1822
+ * // returns [ 3 ]
1823
+ *
1824
+ * sh = ns.flattenShape( [], 1 );
1825
+ * // returns []
1826
+ */
1827
+ flattenShape: typeof flattenShape;
1828
+
1829
+ /**
1830
+ * Flattens a shape starting from a specified dimension.
1831
+ *
1832
+ * @param shape - array shape
1833
+ * @param dim - dimension to start flattening from
1834
+ * @returns flattened shape
1835
+ *
1836
+ * @example
1837
+ * var sh = ns.flattenShapeFrom( [ 3, 3, 2 ], 1 );
1838
+ * // returns [ 3, 6 ]
1839
+ *
1840
+ * sh = ns.flattenShapeFrom( [ 3, 2, 1 ], 1 );
1841
+ * // returns [ 3, 2 ]
1842
+ *
1843
+ * sh = ns.flattenShapeFrom( [ 3 ], 0 );
1844
+ * // returns [ 3 ]
1845
+ *
1846
+ * sh = ns.flattenShapeFrom( [ 3, 2 ], 0 );
1847
+ * // returns [ 6 ]
1848
+ */
1849
+ flattenShapeFrom: typeof flattenShapeFrom;
1850
+
974
1851
  /**
975
1852
  * Returns a view of an input ndarray in which the order of elements along the last dimension is reversed.
976
1853
  *
@@ -981,6 +1858,7 @@ interface Namespace {
981
1858
  * @example
982
1859
  * var typedarray = require( '@stdlib/array-typed' );
983
1860
  * var ndarray = require( '@stdlib/ndarray-ctor' );
1861
+ * var getShape = require( '@stdlib/ndarray-shape' );
984
1862
  * var ndarray2array = require( '@stdlib/ndarray-to-array' );
985
1863
  *
986
1864
  * var buffer = [ 1, 2, 3, 4, 5, 6 ];
@@ -991,7 +1869,7 @@ interface Namespace {
991
1869
  * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
992
1870
  * // returns <ndarray>
993
1871
  *
994
- * var sh = x.shape;
1872
+ * var sh = getShape( x );
995
1873
  * // returns [ 3, 2 ]
996
1874
  *
997
1875
  * var arr = ndarray2array( x );
@@ -1000,7 +1878,7 @@ interface Namespace {
1000
1878
  * var y = ns.fliplr( x, false );
1001
1879
  * // returns <ndarray>
1002
1880
  *
1003
- * sh = y.shape;
1881
+ * sh = getShape( y );
1004
1882
  * // returns [ 3, 2 ]
1005
1883
  *
1006
1884
  * arr = ndarray2array( y );
@@ -1050,10 +1928,12 @@ interface Namespace {
1050
1928
  *
1051
1929
  * @param arrays - array-like object containing an output ndarray
1052
1930
  * @param fcn - callback function
1931
+ * @param thisArg - callback function execution context
1053
1932
  *
1054
1933
  * @example
1055
1934
  * var Float64Array = require( '@stdlib/array-float64' );
1056
1935
  * var naryFunction = require( '@stdlib/utils-nary-function' );
1936
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
1057
1937
  * var log = require( '@stdlib/console-log' );
1058
1938
  *
1059
1939
  * // Create data buffers:
@@ -1076,6 +1956,24 @@ interface Namespace {
1076
1956
  */
1077
1957
  forEach: typeof forEach;
1078
1958
 
1959
+ /**
1960
+ * Converts an array to a one-dimensional ndarray.
1961
+ *
1962
+ * @param buf - input array
1963
+ * @param order - memory layout (row-major or column-major)
1964
+ * @returns one-dimensional ndarray
1965
+ *
1966
+ * @example
1967
+ * var arr = [ 1, 2, 3, 4 ];
1968
+ *
1969
+ * var x = ns.array2ndarray( arr, 'row-major' );
1970
+ * // returns <ndarray>
1971
+ *
1972
+ * var dt = x.dtype;
1973
+ * // returns 'generic'
1974
+ */
1975
+ array2ndarray: typeof array2ndarray;
1976
+
1079
1977
  /**
1080
1978
  * Returns a zero-dimensional ndarray containing a provided scalar value.
1081
1979
  *
@@ -1099,6 +1997,70 @@ interface Namespace {
1099
1997
  */
1100
1998
  scalar2ndarray: typeof scalar2ndarray;
1101
1999
 
2000
+ /**
2001
+ * Returns a zero-dimensional ndarray containing a provided scalar value and having the same data type as a provided input ndarray.
2002
+ *
2003
+ * @param x - input array
2004
+ * @param value - scalar value
2005
+ * @returns zero-dimensional ndarray
2006
+ *
2007
+ * @example
2008
+ * var zeros = require( '@stdlib/ndarray-base-zeros' );
2009
+ *
2010
+ * var x = zeros( 'float64', [ 2, 2 ], 'row-major' );
2011
+ * // returns <ndarray>
2012
+ *
2013
+ * var y = ns.scalar2ndarrayLike( x, 1.0 );
2014
+ * // returns <ndarray>
2015
+ *
2016
+ * var sh = y.shape;
2017
+ * // returns []
2018
+ *
2019
+ * var dt = y.dtype;
2020
+ * // returns 'float64'
2021
+ *
2022
+ * var v = y.get();
2023
+ * // returns 1.0
2024
+ */
2025
+ scalar2ndarrayLike: typeof scalar2ndarrayLike;
2026
+
2027
+ /**
2028
+ * Tests whether an ndarray contains a specified value.
2029
+ *
2030
+ * @param arrays - array-like object containing an input ndarray and a zero-dimensional search element ndarray
2031
+ * @returns boolean indicating whether an ndarray contains a specified value
2032
+ *
2033
+ * @example
2034
+ * var Float64Array = require( '@stdlib/array-float64' );
2035
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
2036
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
2037
+ *
2038
+ * // Create data buffers:
2039
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
2040
+ *
2041
+ * // Define the shape of the input array:
2042
+ * var shape = [ 3, 1, 2 ];
2043
+ *
2044
+ * // Define the array strides:
2045
+ * var sx = [ 4, 4, 1 ];
2046
+ *
2047
+ * // Define the index offset:
2048
+ * var ox = 0;
2049
+ *
2050
+ * // Create the input ndarray:
2051
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
2052
+ *
2053
+ * // Create a zero-dimensional ndarray containing a search element:
2054
+ * var v = scalar2ndarray( 6.0, {
2055
+ * 'dtype': 'float64'
2056
+ * });
2057
+ *
2058
+ * // Perform reduction:
2059
+ * var out = ns.includes( [ x, v ] );
2060
+ * // returns true
2061
+ */
2062
+ includes: typeof includes;
2063
+
1102
2064
  /**
1103
2065
  * Returns an index given an index mode.
1104
2066
  *
@@ -1138,26 +2100,14 @@ interface Namespace {
1138
2100
  * // throws <RangeError>
1139
2101
  *
1140
2102
  * @example
1141
- * var idx = ns.ind( 2, 9, 'normalize' );
1142
- * // returns 2
2103
+ * var idx = ns.ind( 1, 10, 'normalize' );
2104
+ * // returns 1
1143
2105
  *
1144
- * idx = ns.ind( -5, 9, 'normalize' );
1145
- * // returns 5
2106
+ * idx = ns.ind( -4, 10, 'normalize' );
2107
+ * // returns 7
1146
2108
  *
1147
- * idx = ns.ind( -20, 9, 'normalize' );
2109
+ * idx = ns.ind( -100, 10, 'normalize' );
1148
2110
  * // throws <RangeError>
1149
- *
1150
- * @example
1151
- * var fcn = ns.ind.factory( 'clamp' );
1152
- *
1153
- * var idx = fcn( 2, 9 );
1154
- * // returns 2
1155
- *
1156
- * idx = fcn( 10, 9 );
1157
- * // returns 9
1158
- *
1159
- * idx = fcn( -1, 9 );
1160
- * // returns 0
1161
2111
  */
1162
2112
  ind: typeof ind;
1163
2113
 
@@ -1291,51 +2241,148 @@ interface Namespace {
1291
2241
  iterationOrder: typeof iterationOrder;
1292
2242
 
1293
2243
  /**
1294
- * Computes the maximum linear index in an underlying data buffer accessible to an array view.
2244
+ * Reorders ndarray dimensions and associated strides for loop interchange.
1295
2245
  *
1296
- * @param shape - array shape
1297
- * @param strides - stride array
1298
- * @param offset - index offset
1299
- * @returns linear index
2246
+ * ## Notes
1300
2247
  *
1301
- * @example
1302
- * var shape = [ 10, 10 ];
1303
- * var strides = [ 10, 1 ];
1304
- * var offset = 0;
2248
+ * - The returned array has the following elements:
1305
2249
  *
1306
- * var idx = ns.maxViewBufferIndex( shape, strides, offset );
1307
- * // returns 99
2250
+ * ```text
2251
+ * [ <shape>, ...<strides> ]
2252
+ * ```
1308
2253
  *
1309
- * @example
1310
- * var shape = [ 10, 10 ];
1311
- * var strides = [ -10, -1 ];
1312
- * var offset = 99;
2254
+ * where
1313
2255
  *
1314
- * var idx = ns.maxViewBufferIndex( shape, strides, offset );
1315
- * // returns 99
2256
+ * - **shape**: dimensions sorted in loop order.
2257
+ * - **...strides**: strides for each respective ndarray sorted in loop order.
1316
2258
  *
1317
- * @example
1318
- * var shape = [ 10, 10 ];
1319
- * var strides = [ 1, 10 ];
1320
- * var offset = 0;
2259
+ * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
1321
2260
  *
1322
- * var idx = ns.maxViewBufferIndex( shape, strides, offset );
1323
- * // returns 99
2261
+ * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference.
1324
2262
  *
1325
- * @example
1326
- * var shape = [ 10, 10 ];
1327
- * var strides = [ -1, -10 ];
1328
- * var offset = 99;
2263
+ * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order.
1329
2264
  *
1330
- * var idx = ns.maxViewBufferIndex( shape, strides, offset );
1331
- * // returns 99
1332
- */
1333
- maxViewBufferIndex: typeof maxViewBufferIndex;
1334
-
1335
- /**
1336
- * Broadcasts an ndarray to a specified shape if and only if the specified shape differs from the provided ndarray's shape.
2265
+ * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
1337
2266
  *
1338
- * ## Notes
2267
+ * @param shape - array dimensions
2268
+ * @param strides - list of stride arrays containing the stride lengths for each input and output ndarray
2269
+ * @returns loop interchange data
2270
+ *
2271
+ * @example
2272
+ * var sh = [ 2, 3, 4 ];
2273
+ *
2274
+ * var sx = [ 12, 4, 1 ]; // row-major
2275
+ * var sy = [ 24, 8, 1 ]; // row-major
2276
+ * var sz = [ 1, -2, 6 ]; // column-major
2277
+ *
2278
+ * var o = ns.loopOrder( sh, [ sx, sy, sz ] );
2279
+ * // returns [...]
2280
+ *
2281
+ * var ssh = o[ 0 ];
2282
+ * // returns [ 4, 3, 2 ]
2283
+ *
2284
+ * var ssx = o[ 1 ];
2285
+ * // returns [ 1, 4, 12 ]
2286
+ *
2287
+ * var ssy = o[ 2 ];
2288
+ * // returns [ 1, 8, 24 ]
2289
+ *
2290
+ * var ssz = o[ 3 ];
2291
+ * // returns [ 6, -2, 1 ]
2292
+ */
2293
+ loopOrder: typeof loopOrder;
2294
+
2295
+ /**
2296
+ * Applies a callback function to elements in an input ndarray and assigns results to elements in an output ndarray.
2297
+ *
2298
+ * @param arrays - array-like object containing one input ndarray and one output ndarray
2299
+ * @param fcn - callback function
2300
+ * @param thisArg - callback function execution context
2301
+ * @throws arrays must have the same number of dimensions
2302
+ * @throws arrays must have the same shape
2303
+ *
2304
+ * @example
2305
+ * var Float64Array = require( '@stdlib/array-float64' );
2306
+ * var getData = require( '@stdlib/ndarray-data-buffer' );
2307
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
2308
+ *
2309
+ * function scale( x ) {
2310
+ * return x * 10.0;
2311
+ * }
2312
+ *
2313
+ * // Create data buffers:
2314
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
2315
+ * var ybuf = new Float64Array( 6 );
2316
+ *
2317
+ * // Define the shape of the input and output arrays:
2318
+ * var shape = [ 3, 1, 2 ];
2319
+ *
2320
+ * // Define the array strides:
2321
+ * var sx = [ 4, 4, 1 ];
2322
+ * var sy = [ 2, 2, 1 ];
2323
+ *
2324
+ * // Define the index offsets:
2325
+ * var ox = 1;
2326
+ * var oy = 0;
2327
+ *
2328
+ * // Create the input and output ndarrays:
2329
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
2330
+ * var y = ndarray( 'float64', ybuf, shape, sy, oy, 'row-major' );
2331
+ *
2332
+ * // Apply function:
2333
+ * ns.map( [ x, y ], scale );
2334
+ *
2335
+ * console.log( getData( y ) );
2336
+ * // => <Float64Array>[ 20.0, 30.0, 60.0, 70.0, 100.0, 110.0 ]
2337
+ */
2338
+ map: typeof map;
2339
+
2340
+ /**
2341
+ * Computes the maximum linear index in an underlying data buffer accessible to an array view.
2342
+ *
2343
+ * @param shape - array shape
2344
+ * @param strides - stride array
2345
+ * @param offset - index offset
2346
+ * @returns linear index
2347
+ *
2348
+ * @example
2349
+ * var shape = [ 10, 10 ];
2350
+ * var strides = [ 10, 1 ];
2351
+ * var offset = 0;
2352
+ *
2353
+ * var idx = ns.maxViewBufferIndex( shape, strides, offset );
2354
+ * // returns 99
2355
+ *
2356
+ * @example
2357
+ * var shape = [ 10, 10 ];
2358
+ * var strides = [ -10, -1 ];
2359
+ * var offset = 99;
2360
+ *
2361
+ * var idx = ns.maxViewBufferIndex( shape, strides, offset );
2362
+ * // returns 99
2363
+ *
2364
+ * @example
2365
+ * var shape = [ 10, 10 ];
2366
+ * var strides = [ 1, 10 ];
2367
+ * var offset = 0;
2368
+ *
2369
+ * var idx = ns.maxViewBufferIndex( shape, strides, offset );
2370
+ * // returns 99
2371
+ *
2372
+ * @example
2373
+ * var shape = [ 10, 10 ];
2374
+ * var strides = [ -1, -10 ];
2375
+ * var offset = 99;
2376
+ *
2377
+ * var idx = ns.maxViewBufferIndex( shape, strides, offset );
2378
+ * // returns 99
2379
+ */
2380
+ maxViewBufferIndex: typeof maxViewBufferIndex;
2381
+
2382
+ /**
2383
+ * Broadcasts an ndarray to a specified shape if and only if the specified shape differs from the provided ndarray's shape.
2384
+ *
2385
+ * ## Notes
1339
2386
  *
1340
2387
  * - The function throws an error if a provided ndarray is incompatible with a provided shape.
1341
2388
  * - If a provided ndarray has the same shape as the specified shape, the function returns the provided ndarray.
@@ -1414,8 +2461,8 @@ interface Namespace {
1414
2461
  * var shy = y1.shape;
1415
2462
  * // returns [ 3, 2, 2 ]
1416
2463
  *
1417
- * var out = ns.maybeBroadcastArrays( [ x, y ] );
1418
- * // returns <ndarray>
2464
+ * var out = ns.maybeBroadcastArrays( [ x, y1 ] );
2465
+ * // returns [ <ndarray>, <ndarray> ]
1419
2466
  *
1420
2467
  * var x2 = out[ 0 ];
1421
2468
  * // returns <ndarray>
@@ -1483,6 +2530,38 @@ interface Namespace {
1483
2530
  */
1484
2531
  metaDataProps: typeof metaDataProps;
1485
2532
 
2533
+ /**
2534
+ * Returns the minimum ndarray data type for storing a provided signed integer value.
2535
+ *
2536
+ * @param value - scalar value
2537
+ * @returns ndarray data type
2538
+ *
2539
+ * @example
2540
+ * var dt = ns.minSignedIntegerDataType( 1280 );
2541
+ * // returns 'int16'
2542
+ *
2543
+ * @example
2544
+ * var dt = ns.minSignedIntegerDataType( 3 );
2545
+ * // returns 'int8'
2546
+ */
2547
+ minSignedIntegerDataType: typeof minSignedIntegerDataType;
2548
+
2549
+ /**
2550
+ * Returns the minimum ndarray data type for storing a provided unsigned integer value.
2551
+ *
2552
+ * @param value - scalar value
2553
+ * @returns ndarray data type
2554
+ *
2555
+ * @example
2556
+ * var dt = ns.minUnsignedIntegerDataType( 1280 );
2557
+ * // returns 'uint16'
2558
+ *
2559
+ * @example
2560
+ * var dt = ns.minUnsignedIntegerDataType( 3 );
2561
+ * // returns 'uint8'
2562
+ */
2563
+ minUnsignedIntegerDataType: typeof minUnsignedIntegerDataType;
2564
+
1486
2565
  /**
1487
2566
  * Computes the minimum linear index in an underlying data buffer accessible to an array view.
1488
2567
  *
@@ -1568,7 +2647,23 @@ interface Namespace {
1568
2647
  minmaxViewBufferIndex: typeof minmaxViewBufferIndex;
1569
2648
 
1570
2649
  /**
1571
- * Converts an ndarray-like to an object likely to have the same "shape".
2650
+ * Converts an ndarray-like object to an ndarray.
2651
+ *
2652
+ * @param x - input ndarray
2653
+ * @returns ndarray
2654
+ *
2655
+ * @example
2656
+ * var array = require( '@stdlib/ndarray-array' );
2657
+ *
2658
+ * var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] );
2659
+ *
2660
+ * var out = ns.ndarraylike2ndarray( x );
2661
+ * // returns <ndarray>
2662
+ */
2663
+ ndarraylike2ndarray: typeof ndarraylike2ndarray;
2664
+
2665
+ /**
2666
+ * Converts an ndarray-like object to an object likely to have the same "shape".
1572
2667
  *
1573
2668
  * ## Notes
1574
2669
  *
@@ -1587,6 +2682,23 @@ interface Namespace {
1587
2682
  */
1588
2683
  ndarraylike2object: typeof ndarraylike2object;
1589
2684
 
2685
+ /**
2686
+ * Converts an ndarray-like object to a scalar value.
2687
+ *
2688
+ * @param x - input ndarray
2689
+ * @returns scalar value
2690
+ *
2691
+ * @example
2692
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
2693
+ *
2694
+ * var x = scalar2ndarray( 1.0 );
2695
+ * // returns <ndarray>
2696
+ *
2697
+ * var out = ns.ndarraylike2scalar( x );
2698
+ * // returns 1.0
2699
+ */
2700
+ ndarraylike2scalar: typeof ndarraylike2scalar;
2701
+
1590
2702
  /**
1591
2703
  * Returns the number of ndarray dimensions.
1592
2704
  *
@@ -1701,6 +2813,27 @@ interface Namespace {
1701
2813
  */
1702
2814
  normalizeIndex: typeof normalizeIndex;
1703
2815
 
2816
+ /**
2817
+ * Normalizes a list of indices to the interval `[0,max]`.
2818
+ *
2819
+ * ## Notes
2820
+ *
2821
+ * - If provided an out-of-bounds index, the function returns `null`.
2822
+ * - The function mutates the input array, even when provided an out-of-bounds index.
2823
+ *
2824
+ * @param indices - indices
2825
+ * @param max - maximum index
2826
+ * @returns normalized indices or null
2827
+ *
2828
+ * @example
2829
+ * var indices = ns.normalizeIndices( [ -2, 5 ], 10 );
2830
+ * // returns [ 9, 5 ]
2831
+ *
2832
+ * indices = ns.normalizeIndices( [ -2, 15 ], 10 );
2833
+ * // returns null
2834
+ */
2835
+ normalizeIndices: typeof normalizeIndices;
2836
+
1704
2837
  /**
1705
2838
  * Applies a nullary callback and assigns results to elements in an output ndarray.
1706
2839
  *
@@ -1776,6 +2909,90 @@ interface Namespace {
1776
2909
  */
1777
2910
  nullaryLoopOrder: typeof nullaryLoopOrder;
1778
2911
 
2912
+ /**
2913
+ * Constructor for applying a strided function to an ndarray.
2914
+ *
2915
+ * @param table - dispatch table
2916
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
2917
+ * @param odtypes - list of supported output data types
2918
+ * @param options - function options
2919
+ * @returns instance
2920
+ *
2921
+ * @example
2922
+ * var base = require( '@stdlib/blas-ext-base-ndarray-gsorthp' );
2923
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
2924
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
2925
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
2926
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
2927
+ *
2928
+ * var idt = dtypes( 'real_and_generic' );
2929
+ * var odt = dtypes( 'all' );
2930
+ *
2931
+ * var table = {
2932
+ * 'default': base
2933
+ * };
2934
+ * var sorthp = new ns.nullaryStrided1dDispatch( table, [ idt ], odt );
2935
+ *
2936
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
2937
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
2938
+ *
2939
+ * var order = scalar2ndarray( 1.0, {
2940
+ * 'dtype': 'generic'
2941
+ * });
2942
+ *
2943
+ * var out = sorthp.assign( x, order );
2944
+ * // returns <ndarray>
2945
+ *
2946
+ * var arr = ndarray2array( x );
2947
+ * // returns [ -3.0, -1.0, 2.0 ]
2948
+ *
2949
+ * var bool = ( out === x );
2950
+ * // returns true
2951
+ */
2952
+ nullaryStrided1dDispatch: typeof nullaryStrided1dDispatch;
2953
+
2954
+ /**
2955
+ * Creates a function for applying a strided function to an output ndarray.
2956
+ *
2957
+ * @param table - dispatch table
2958
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
2959
+ * @param odtypes - list of supported output data types
2960
+ * @param options - function options
2961
+ * @returns function for applying a nullary function
2962
+ *
2963
+ * @example
2964
+ * var base = require( '@stdlib/blas-ext-base-ndarray-gsorthp' );
2965
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
2966
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
2967
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
2968
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
2969
+ *
2970
+ * var idt = dtypes( 'real_and_generic' );
2971
+ * var odt = dtypes( 'all' );
2972
+ *
2973
+ * var table = {
2974
+ * 'default': base
2975
+ * };
2976
+ * var sorthp = ns.nullaryStrided1dDispatchFactory( table, [ idt ], odt );
2977
+ *
2978
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
2979
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
2980
+ *
2981
+ * var order = scalar2ndarray( 1.0, {
2982
+ * 'dtype': 'generic'
2983
+ * });
2984
+ *
2985
+ * var out = sorthp( x, order );
2986
+ * // returns <ndarray>
2987
+ *
2988
+ * var arr = ndarray2array( out );
2989
+ * // returns [ -3.0, -1.0, 2.0 ]
2990
+ *
2991
+ * var bool = ( out === x );
2992
+ * // returns true
2993
+ */
2994
+ nullaryStrided1dDispatchFactory: typeof nullaryStrided1dDispatchFactory;
2995
+
1779
2996
  /**
1780
2997
  * Returns a loop block size for multi-dimensional array tiled loops.
1781
2998
  *
@@ -1851,6 +3068,19 @@ interface Namespace {
1851
3068
  */
1852
3069
  order: typeof order;
1853
3070
 
3071
+ /**
3072
+ * Resolves the output data type from a list of input ndarray data types.
3073
+ *
3074
+ * @param dtypes - input ndarray data types
3075
+ * @param policy - output ndarray data type policy
3076
+ * @returns output ndarray data type
3077
+ *
3078
+ * @example
3079
+ * var dt = ns.outputDataType( [ 'float64' ], 'complex_floating_point' );
3080
+ * // returns <string>
3081
+ */
3082
+ outputDataType: typeof outputDataType;
3083
+
1854
3084
  /**
1855
3085
  * Returns the policy string associated with an output ndarray data type policy enumeration constant.
1856
3086
  *
@@ -1915,61 +3145,266 @@ interface Namespace {
1915
3145
  outputPolicyStr2Enum: typeof outputPolicyStr2Enum;
1916
3146
 
1917
3147
  /**
1918
- * Returns an array with a specified number of prepended singleton dimensions.
3148
+ * Returns an array containing a truncated view of an input ndarray and a view of the last element(s) along a specified dimension.
3149
+ *
3150
+ * ## Notes
3151
+ *
3152
+ * - The input array must have one or more dimensions.
1919
3153
  *
1920
3154
  * @param x - input array
1921
- * @param n - number of singleton dimensions to prepend
1922
- * @returns output array
3155
+ * @param dim - dimension along which to perform the operation
3156
+ * @param writable - boolean indicating whether returned arrays should be writable
3157
+ * @returns a list of ndarrays
1923
3158
  *
1924
3159
  * @example
1925
- * var array = require( '@stdlib/ndarray-array' );
3160
+ * var Float64Array = require( '@stdlib/array-float64' );
3161
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
3162
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
1926
3163
  *
1927
- * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
3164
+ * var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
3165
+ * var shape = [ 3, 2 ];
3166
+ * var strides = [ 2, 1 ];
3167
+ * var offset = 0;
3168
+ *
3169
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
1928
3170
  * // returns <ndarray>
1929
3171
  *
1930
- * var shx = x.shape;
1931
- * // returns [ 2, 2 ]
3172
+ * var arr = ndarray2array( x );
3173
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
1932
3174
  *
1933
- * var y = ns.prependSingletonDimensions( x, 3 );
1934
- * // returns <ndarray>
3175
+ * var y = ns.pop( x, 0, false );
3176
+ * // returns [ <ndarray>, <ndarray> ]
1935
3177
  *
1936
- * var shy = y.shape;
1937
- * // returns [ 1, 1, 1, 2, 2 ]
3178
+ * arr = ndarray2array( y[ 0 ] );
3179
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]
1938
3180
  *
1939
- * var v = y.get( 0, 0, 0, 0, 0 );
1940
- * // returns 1
3181
+ * arr = ndarray2array( y[ 1 ] );
3182
+ * // returns [ [ 5.0, 6.0 ] ]
3183
+ */
3184
+ pop: typeof pop;
3185
+
3186
+ /**
3187
+ * Returns an array with a specified number of prepended singleton dimensions.
1941
3188
  *
1942
- * v = y.get( 0, 0, 0, 0, 1 );
1943
- * // returns 2
3189
+ * @param x - input array
3190
+ * @param n - number of singleton dimensions to prepend
3191
+ * @param writable - boolean indicating whether a returned array should be writable
3192
+ * @returns output array
1944
3193
  *
1945
- * v = y.get( 0, 0, 0, 1, 0 );
1946
- * // returns 3
3194
+ * @example
3195
+ * var array = require( '@stdlib/ndarray-array' );
1947
3196
  *
1948
- * v = y.get( 0, 0, 0, 1, 1 );
1949
- * // returns 4
3197
+ * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
3198
+ * // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
3199
+ *
3200
+ * var y = ns.prependSingletonDimensions( x, 3, false );
3201
+ * // returns <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
1950
3202
  */
1951
3203
  prependSingletonDimensions: typeof prependSingletonDimensions;
1952
3204
 
1953
3205
  /**
1954
- * Returns an array without singleton dimensions.
3206
+ * Returns a data type that results from applying promotion rules to a provided list of data types.
1955
3207
  *
1956
3208
  * ## Notes
1957
3209
  *
1958
- * - If a provided ndarray does not have any singleton dimensions, the function returns the provided ndarray unchanged.
1959
- * - If a provided ndarray does have singleton dimensions, the function returns a new ndarray view.
3210
+ * - The function returns `null` if provided data types which cannot be safely cast to a promoted data type.
1960
3211
  *
1961
- * @param x - input array
1962
- * @returns squeezed array
3212
+ * @param dtypes - list of data types
3213
+ * @returns result
1963
3214
  *
1964
3215
  * @example
1965
- * var array = require( '@stdlib/ndarray-array' );
1966
- *
1967
- * var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
1968
- * 'ndmin': 5
1969
- * });
1970
- * // returns <ndarray>
3216
+ * var dt = ns.promoteDataTypes( [ 'float32', 'float64' ] );
3217
+ * // returns 'float64'
1971
3218
  *
1972
- * var shx = x.shape;
3219
+ * @example
3220
+ * var dt = ns.promoteDataTypes( [ 'binary', 'complex128' ] );
3221
+ * // returns null
3222
+ */
3223
+ promoteDataTypes: typeof promoteDataTypes;
3224
+
3225
+ /**
3226
+ * Reorders ndarray dimensions and associated strides for loop interchange.
3227
+ *
3228
+ * ## Notes
3229
+ *
3230
+ * - The returned object has the following properties:
3231
+ *
3232
+ * - **sh**: dimensions sorted in loop order.
3233
+ * - **sx**: first input ndarray strides sorted in loop order.
3234
+ * - **sy**: second input ndarray strides sorted in loop order.
3235
+ * - **sz**: third input ndarray strides sorted in loop order.
3236
+ * - **sw**: fourth input ndarray strides sorted in loop order.
3237
+ * - **su**: output ndarray strides sorted in loop order.
3238
+ *
3239
+ * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
3240
+ *
3241
+ * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference.
3242
+ *
3243
+ * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order.
3244
+ *
3245
+ * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
3246
+ *
3247
+ * @param shape - array dimensions
3248
+ * @param stridesX - first input array stride lengths
3249
+ * @param stridesY - second input array stride lengths
3250
+ * @param stridesZ - third input array stride lengths
3251
+ * @param stridesW - fourth input array stride lengths
3252
+ * @param stridesU - output array stride lengths
3253
+ * @returns loop interchange data
3254
+ *
3255
+ * @example
3256
+ * var sh = [ 2, 3, 4 ];
3257
+ *
3258
+ * var sx = [ 12, 4, 1 ]; // row-major
3259
+ * var sy = [ 24, 8, 1 ]; // row-major
3260
+ * var sz = [ 1, 4, 12 ]; // column-major
3261
+ * var sw = [ 1, -2, 6 ]; // column-major
3262
+ * var su = [ 1, -2, 6 ]; // column-major
3263
+ *
3264
+ * var o = ns.quaternaryLoopOrder( sh, sx, sy, sz, sw, su );
3265
+ * // returns {...}
3266
+ *
3267
+ * var ssh = o.sh;
3268
+ * // returns [ 2, 3, 4 ]
3269
+ *
3270
+ * var ssx = o.sx;
3271
+ * // returns [ 12, 4, 1 ]
3272
+ *
3273
+ * var ssy = o.sy;
3274
+ * // returns [ 24, 8, 1 ]
3275
+ *
3276
+ * var ssz = o.sz;
3277
+ * // returns [ 1, 4, 12 ]
3278
+ *
3279
+ * var ssw = o.sw;
3280
+ * // returns [ 1, -2, 6 ]
3281
+ *
3282
+ * var ssu = o.su;
3283
+ * // returns [ 1, -2, 6 ]
3284
+ */
3285
+ quaternaryLoopOrder: typeof quaternaryLoopOrder;
3286
+
3287
+ /**
3288
+ * Returns a loop block size for multi-dimensional array tiled loops.
3289
+ *
3290
+ * @param dtypeX - first input array data type
3291
+ * @param dtypeY - second input array data type
3292
+ * @param dtypeZ - third input array data type
3293
+ * @param dtypeW - fourth input array data type
3294
+ * @param dtypeU - output array data type
3295
+ * @returns block size (in units of elements)
3296
+ *
3297
+ * @example
3298
+ * var bsize = ns.quaternaryBlockSize( 'float64', 'float64', 'float64', 'float64', 'float64' );
3299
+ * // returns <number>
3300
+ */
3301
+ quaternaryBlockSize: typeof quaternaryBlockSize;
3302
+
3303
+ /**
3304
+ * Reorders ndarray dimensions and associated strides for loop interchange.
3305
+ *
3306
+ * ## Notes
3307
+ *
3308
+ * - The returned object has the following properties:
3309
+ *
3310
+ * - **sh**: dimensions sorted in loop order.
3311
+ * - **sx**: first input ndarray strides sorted in loop order.
3312
+ * - **sy**: second input ndarray strides sorted in loop order.
3313
+ * - **sz**: third input ndarray strides sorted in loop order.
3314
+ * - **sw**: fourth input ndarray strides sorted in loop order.
3315
+ * - **su**: fifth input ndarray strides sorted in loop order.
3316
+ * - **sv**: output ndarray strides sorted in loop order.
3317
+ *
3318
+ * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
3319
+ *
3320
+ * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference.
3321
+ *
3322
+ * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order.
3323
+ *
3324
+ * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
3325
+ *
3326
+ * @param shape - array dimensions
3327
+ * @param stridesX - first input array stride lengths
3328
+ * @param stridesY - second input array stride lengths
3329
+ * @param stridesZ - third input array stride lengths
3330
+ * @param stridesW - fourth input array stride lengths
3331
+ * @param stridesU - fifth input array stride lengths
3332
+ * @param stridesV - output array stride lengths
3333
+ * @returns loop interchange data
3334
+ *
3335
+ * @example
3336
+ * var sh = [ 2, 3, 4 ];
3337
+ *
3338
+ * var sx = [ 12, 4, 1 ]; // row-major
3339
+ * var sy = [ 24, 8, 1 ]; // row-major
3340
+ * var sz = [ 12, 4, 1 ]; // row-major
3341
+ * var sw = [ 24, 8, 1 ]; // row-major
3342
+ * var su = [ 1, 4, 12 ]; // column-major
3343
+ * var sv = [ 1, -2, 6 ]; // column-major
3344
+ *
3345
+ * var o = ns.quinaryLoopOrder( sh, sx, sy, sz, sw, su, sv );
3346
+ * // returns {...}
3347
+ *
3348
+ * var ssh = o.sh;
3349
+ * // returns [ 4, 3, 2 ]
3350
+ *
3351
+ * var ssx = o.sx;
3352
+ * // returns [ 1, 4, 12 ]
3353
+ *
3354
+ * var ssy = o.sy;
3355
+ * // returns [ 1, 8, 24 ]
3356
+ *
3357
+ * var ssz = o.sz;
3358
+ * // returns [ 1, 4, 12 ]
3359
+ *
3360
+ * var ssw = o.sw;
3361
+ * // returns [ 1, 8, 24 ]
3362
+ *
3363
+ * var ssu = o.su;
3364
+ * // returns [ 12, 4, 1 ]
3365
+ *
3366
+ * var ssv = o.sv;
3367
+ * // returns [ 6, -2, 1 ]
3368
+ */
3369
+ quinaryLoopOrder: typeof quinaryLoopOrder;
3370
+
3371
+ /**
3372
+ * Returns a loop block size for multi-dimensional array tiled loops.
3373
+ *
3374
+ * @param dtypeX - first input array data type
3375
+ * @param dtypeY - second input array data type
3376
+ * @param dtypeZ - third input array data type
3377
+ * @param dtypeW - fourth input array data type
3378
+ * @param dtypeU - fifth input array data type
3379
+ * @param dtypeV - output array data type
3380
+ * @returns block size (in units of elements)
3381
+ *
3382
+ * @example
3383
+ * var bsize = ns.quinaryBlockSize( 'float64', 'float64', 'float64', 'float64', 'float64', 'float64' );
3384
+ * // returns <number>
3385
+ */
3386
+ quinaryBlockSize: typeof quinaryBlockSize;
3387
+
3388
+ /**
3389
+ * Returns an array without singleton dimensions.
3390
+ *
3391
+ * ## Notes
3392
+ *
3393
+ * - If a provided ndarray does not have any singleton dimensions, the function returns the provided ndarray unchanged.
3394
+ * - If a provided ndarray does have singleton dimensions, the function returns a new ndarray view.
3395
+ *
3396
+ * @param x - input array
3397
+ * @returns squeezed array
3398
+ *
3399
+ * @example
3400
+ * var array = require( '@stdlib/ndarray-array' );
3401
+ *
3402
+ * var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
3403
+ * 'ndmin': 5
3404
+ * });
3405
+ * // returns <ndarray>
3406
+ *
3407
+ * var shx = x.shape;
1973
3408
  * // returns [ 1, 1, 1, 2, 2 ]
1974
3409
  *
1975
3410
  * var y = ns.removeSingletonDimensions( x );
@@ -2004,19 +3439,19 @@ interface Namespace {
2004
3439
  * var ndarray = require( '@stdlib/ndarray-ctor' );
2005
3440
  * var ndarray2array = require( '@stdlib/ndarray-to-array' );
2006
3441
  *
2007
- * var buffer = [ 1, 2, 3, 4, 5, 6 ];
3442
+ * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' );
2008
3443
  * var shape = [ 3, 2 ];
2009
3444
  * var strides = [ 2, 1 ];
2010
3445
  * var offset = 0;
2011
3446
  *
2012
- * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
3447
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
2013
3448
  * // returns <ndarray>
2014
3449
  *
2015
3450
  * var sh = x.shape;
2016
3451
  * // returns [ 3, 2 ]
2017
3452
  *
2018
3453
  * var arr = ndarray2array( x );
2019
- * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ]
3454
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
2020
3455
  *
2021
3456
  * var y = ns.reverse( x, false );
2022
3457
  * // returns <ndarray>
@@ -2025,7 +3460,7 @@ interface Namespace {
2025
3460
  * // returns [ 3, 2 ]
2026
3461
  *
2027
3462
  * arr = ndarray2array( y );
2028
- * // returns [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ]
3463
+ * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ]
2029
3464
  */
2030
3465
  reverse: typeof reverse;
2031
3466
 
@@ -2176,6 +3611,45 @@ interface Namespace {
2176
3611
  */
2177
3612
  shape2strides: typeof shape2strides;
2178
3613
 
3614
+ /**
3615
+ * Returns an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension.
3616
+ *
3617
+ * ## Notes
3618
+ *
3619
+ * - The input array must have one or more dimensions.
3620
+ *
3621
+ * @param x - input array
3622
+ * @param dim - dimension along which to perform the operation
3623
+ * @param writable - boolean indicating whether returned arrays should be writable
3624
+ * @returns a list of ndarrays
3625
+ *
3626
+ * @example
3627
+ * var Float64Array = require( '@stdlib/array-float64' );
3628
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
3629
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
3630
+ *
3631
+ * var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
3632
+ * var shape = [ 3, 2 ];
3633
+ * var strides = [ 2, 1 ];
3634
+ * var offset = 0;
3635
+ *
3636
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
3637
+ * // returns <ndarray>
3638
+ *
3639
+ * var arr = ndarray2array( x );
3640
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
3641
+ *
3642
+ * var y = ns.shift( x, 0, false );
3643
+ * // returns [ <ndarray>, <ndarray> ]
3644
+ *
3645
+ * arr = ndarray2array( y[ 0 ] );
3646
+ * // returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
3647
+ *
3648
+ * arr = ndarray2array( y[ 1 ] );
3649
+ * // returns [ [ 1.0, 2.0 ] ]
3650
+ */
3651
+ shift: typeof shift;
3652
+
2179
3653
  /**
2180
3654
  * Returns the number of singleton dimensions.
2181
3655
  *
@@ -2206,8 +3680,8 @@ interface Namespace {
2206
3680
  * @returns output array
2207
3681
  *
2208
3682
  * @example
2209
- * var Slice = require( '@stdlib/ns.slice-ctor' );
2210
- * var MultiSlice = require( '@stdlib/ns.slice-multi' );
3683
+ * var Slice = require( '@stdlib/slice-ctor' );
3684
+ * var MultiSlice = require( '@stdlib/slice-multi' );
2211
3685
  * var ndarray = require( '@stdlib/ndarray-ctor' );
2212
3686
  * var ndarray2array = require( '@stdlib/ndarray-to-array' );
2213
3687
  *
@@ -2346,6 +3820,7 @@ interface Namespace {
2346
3820
  * Returns a shifted view of an input ndarray along a specified dimension.
2347
3821
  *
2348
3822
  * @param x - input array
3823
+ * @param dim - index of dimension to slice
2349
3824
  * @param start - starting index (inclusive)
2350
3825
  * @param strict - boolean indicating whether to enforce strict bounds checking
2351
3826
  * @param writable - boolean indicating whether a returned array should be writable
@@ -2384,6 +3859,7 @@ interface Namespace {
2384
3859
  * Returns a truncated view of an input ndarray along a specified dimension.
2385
3860
  *
2386
3861
  * @param x - input array
3862
+ * @param dim - index of dimension to slice
2387
3863
  * @param stop - ending index (exclusive)
2388
3864
  * @param strict - boolean indicating whether to enforce strict bounds checking
2389
3865
  * @param writable - boolean indicating whether a returned array should be writable
@@ -2496,6 +3972,125 @@ interface Namespace {
2496
3972
  */
2497
3973
  sliceTo: typeof sliceTo;
2498
3974
 
3975
+ /**
3976
+ * Tests whether at least `n` elements in an ndarray are truthy.
3977
+ *
3978
+ * @param arrays - array-like object containing an input ndarray and a zero-dimensional ndarray specifying the minimum number of elements in the input ndarray that must be truthy
3979
+ * @returns boolean indicating whether `n` elements pass a test
3980
+ *
3981
+ * @example
3982
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
3983
+ * var Float64Array = require( '@stdlib/array-float64' );
3984
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
3985
+ *
3986
+ * // Create a data buffer:
3987
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
3988
+ *
3989
+ * // Define the shape of the array:
3990
+ * var shape = [ 3, 1, 2 ];
3991
+ *
3992
+ * // Define the array strides:
3993
+ * var sx = [ 4, 4, 1 ];
3994
+ *
3995
+ * // Define the index offset:
3996
+ * var ox = 1;
3997
+ *
3998
+ * // Create the input ndarray:
3999
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
4000
+ * var n = scalar2ndarray( 3, {
4001
+ * 'dtype': 'generic'
4002
+ * });
4003
+ *
4004
+ * // Test elements:
4005
+ * var out = ns.some( [ x, n ] );
4006
+ * // returns true
4007
+ */
4008
+ some: typeof some;
4009
+
4010
+ /**
4011
+ * Tests whether at least `n` elements in an ndarray pass a test implemented by a predicate function.
4012
+ *
4013
+ * @param arrays - array-like object containing an input ndarray and a zero-dimensional ndarray specifying the minimum number of elements in the input ndarray that must satisfy the predicate function
4014
+ * @param predicate - predicate function
4015
+ * @param thisArg - predicate function execution context
4016
+ * @returns boolean indicating whether `n` elements pass a test
4017
+ *
4018
+ * @example
4019
+ * var scalar2ndarray = require( '@stdlib/ndarray-from-scalar' );
4020
+ * var Float64Array = require( '@stdlib/array-float64' );
4021
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
4022
+ *
4023
+ * function predicate( value ) {
4024
+ * return value > 0.0;
4025
+ * }
4026
+ *
4027
+ * // Create data buffers:
4028
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
4029
+ *
4030
+ * // Define the shape of the array:
4031
+ * var shape = [ 3, 1, 2 ];
4032
+ *
4033
+ * // Define the array strides:
4034
+ * var sx = [ 4, 4, 1 ];
4035
+ *
4036
+ * // Define the index offset:
4037
+ * var ox = 1;
4038
+ *
4039
+ * // Create the input ndarray:
4040
+ * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
4041
+ * var n = scalar2ndarray( 3, {
4042
+ * 'dtype': 'generic'
4043
+ * });
4044
+ *
4045
+ * // Test elements:
4046
+ * var out = ns.someBy( [ x, n ], predicate );
4047
+ * // returns true
4048
+ */
4049
+ someBy: typeof someBy;
4050
+
4051
+ /**
4052
+ * Expands the shape of an array to a specified dimensionality by spreading its dimensions to specified dimension indices and inserting dimensions of size one for the remaining dimensions.
4053
+ *
4054
+ * ## Notes
4055
+ *
4056
+ * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. If provided a negative dimension index, the position at which to place a respective dimension is computed as `ndims + index`.
4057
+ * - Provided dimension indices must resolve to normalized dimension indices arranged in ascending order.
4058
+ *
4059
+ * @param ndims - number of dimensions in the output array
4060
+ * @param x - input array
4061
+ * @param dims - dimension indices
4062
+ * @param writable - boolean indicating whether a returned array should be writable
4063
+ * @returns output array
4064
+ *
4065
+ * @example
4066
+ * var array = require( '@stdlib/ndarray-array' );
4067
+ *
4068
+ * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
4069
+ * // returns <ndarray>
4070
+ *
4071
+ * var shx = x.shape;
4072
+ * // returns [ 2, 2 ]
4073
+ *
4074
+ * var y = ns.spreadDimensions( 5, x, [ 1, 3 ], false );
4075
+ * // returns <ndarray>
4076
+ *
4077
+ * var shy = y.shape;
4078
+ * // returns [ 1, 2, 1, 2, 1 ]
4079
+ *
4080
+ * var v = y.get( 0, 0, 0, 0, 0 );
4081
+ * // returns 1
4082
+ *
4083
+ * v = y.get( 0, 0, 0, 1, 0 );
4084
+ * // returns 2
4085
+ *
4086
+ * v = y.get( 0, 1, 0, 0, 0 );
4087
+ * // returns 3
4088
+ *
4089
+ * v = y.get( 0, 1, 0, 1, 0 );
4090
+ * // returns 4
4091
+ */
4092
+ spreadDimensions: typeof spreadDimensions;
4093
+
2499
4094
  /**
2500
4095
  * Returns the stride along a specified dimension for a provided ndarray.
2501
4096
  *
@@ -2638,66 +4233,398 @@ interface Namespace {
2638
4233
  * idx = sub2ind( shape, strides, 0, 1, 0, mode );
2639
4234
  * // returns 2
2640
4235
  *
2641
- * idx = sub2ind( shape, strides, 0, 1, 1, mode );
2642
- * // returns 3
4236
+ * idx = sub2ind( shape, strides, 0, 1, 1, mode );
4237
+ * // returns 3
4238
+ *
4239
+ * // From the perspective of an underlying buffer...
4240
+ * idx = sub2ind( shape, strides, offset, 0, 0, mode );
4241
+ * // returns 2
4242
+ *
4243
+ * idx = sub2ind( shape, strides, offset, 0, 1, mode );
4244
+ * // returns 3
4245
+ *
4246
+ * idx = sub2ind( shape, strides, offset, 1, 0, mode );
4247
+ * // returns 0
4248
+ *
4249
+ * idx = sub2ind( shape, strides, offset, 1, 1, mode );
4250
+ * // returns 1
4251
+ * ```
4252
+ *
4253
+ * In short, from the perspective of a view, view data is always ordered.
4254
+ *
4255
+ *
4256
+ * @param shape - array shape
4257
+ * @param strides - stride array
4258
+ * @param offset - location of the first indexed value **based** on the stride array
4259
+ * @param args - subscripts followed by a `mode` specifying how to handle subscripts which exceed array dimensions
4260
+ * @param mode - specifies how to handle subscripts which exceed array dimensions
4261
+ * @throws must provide subscripts which do not exceed array dimensions
4262
+ * @returns linear index
4263
+ *
4264
+ * @example
4265
+ * var shape = [ 3, 3, 3 ];
4266
+ * var strides = [ 9, 3, 1 ];
4267
+ * var offset = 0;
4268
+ * var mode = [ 'throw' ];
4269
+ *
4270
+ * var idx = ns.sub2ind( shape, strides, offset, 1, 2, 2, mode );
4271
+ * // returns 17
4272
+ */
4273
+ sub2ind: typeof sub2ind;
4274
+
4275
+ /**
4276
+ * Applies a ternary callback to elements in input ndarrays and assigns results to elements in an output ndarray.
4277
+ *
4278
+ * @param arrays - array-like object containing three input ndarrays and one output ndarray
4279
+ * @param fcn - ternary callback
4280
+ * @throws arrays must have the same number of dimensions
4281
+ * @throws arrays must have the same shape
4282
+ *
4283
+ * @example
4284
+ * var Float64Array = require( '@stdlib/array-float64' );
4285
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
4286
+ * var getData = require( '@stdlib/ndarray-data-buffer' );
4287
+ * var add3 = require( '@stdlib/number-float64-base-add3' );
4288
+ *
4289
+ * // Create data buffers:
4290
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
4291
+ * var ybuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
4292
+ * var zbuf = new Float64Array( [ 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] );
4293
+ * var wbuf = new Float64Array( 6 );
4294
+ *
4295
+ * // Define the shape of the input and output arrays:
4296
+ * var shape = [ 3, 1, 2 ];
4297
+ *
4298
+ * // Define the array strides:
4299
+ * var sx = [ 2, 2, 1 ];
4300
+ * var sy = [ 2, 2, 1 ];
4301
+ * var sz = [ 2, 2, 1 ];
4302
+ * var sw = [ 2, 2, 1 ];
4303
+ *
4304
+ * // Define the index offsets:
4305
+ * var ox = 0;
4306
+ * var oy = 0;
4307
+ * var oz = 0;
4308
+ * var ow = 0;
4309
+ *
4310
+ * // Create the input and output ndarrays:
4311
+ * var x = new ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
4312
+ * var y = new ndarray( 'float64', ybuf, shape, sy, oy, 'row-major' );
4313
+ * var z = new ndarray( 'float64', zbuf, shape, sz, oz, 'row-major' );
4314
+ * var w = new ndarray( 'float64', wbuf, shape, sw, ow, 'row-major' );
4315
+ *
4316
+ * // Apply the ns.ternary function:
4317
+ * ns.ternary( [ x, y, z, w ], add3 );
4318
+ *
4319
+ * console.log( getData( w ) );
4320
+ * // => <Float64Array>[ 2.5, 4.5, 6.5, 8.5, 10.5, 12.5 ]
4321
+ */
4322
+ ternary: typeof ternary;
4323
+
4324
+ /**
4325
+ * Reorders ndarray dimensions and associated strides for loop interchange.
4326
+ *
4327
+ * ## Notes
4328
+ *
4329
+ * - The returned object has the following properties:
4330
+ *
4331
+ * - **sh**: dimensions sorted in loop order.
4332
+ * - **sx**: first input ndarray strides sorted in loop order.
4333
+ * - **sy**: second input ndarray strides sorted in loop order.
4334
+ * - **sz**: third input ndarray strides sorted in loop order.
4335
+ * - **sw**: output ndarray strides sorted in loop order.
4336
+ *
4337
+ * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
4338
+ *
4339
+ * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference.
4340
+ *
4341
+ * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order.
4342
+ *
4343
+ * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
4344
+ *
4345
+ * @param shape - array dimensions
4346
+ * @param stridesX - first input array stride lengths
4347
+ * @param stridesY - second input array stride lengths
4348
+ * @param stridesZ - third input array stride lengths
4349
+ * @param stridesW - output array stride lengths
4350
+ * @returns loop interchange data
4351
+ *
4352
+ * @example
4353
+ * var sh = [ 2, 3, 4 ];
4354
+ *
4355
+ * var sx = [ 12, 4, 1 ]; // row-major
4356
+ * var sy = [ 24, 8, 1 ]; // row-major
4357
+ * var sz = [ 1, 4, 12 ]; // column-major
4358
+ * var sw = [ 1, -2, 6 ]; // column-major
4359
+ *
4360
+ * var o = ns.ternaryLoopOrder( sh, sx, sy, sz, sw );
4361
+ * // returns {...}
4362
+ *
4363
+ * var ssh = o.sh;
4364
+ * // returns [ 2, 3, 4 ]
4365
+ *
4366
+ * var ssx = o.sx;
4367
+ * // returns [ 12, 4, 1 ]
4368
+ *
4369
+ * var ssy = o.sy;
4370
+ * // returns [ 24, 8, 1 ]
4371
+ *
4372
+ * var ssz = o.sz;
4373
+ * // returns [ 1, 4, 12 ]
4374
+ *
4375
+ * var ssw = o.sw;
4376
+ * // returns [ 1, -2, 6 ]
4377
+ */
4378
+ ternaryLoopOrder: typeof ternaryLoopOrder;
4379
+
4380
+ /**
4381
+ * Resolves the output ndarray data type for a ternary function.
4382
+ *
4383
+ * @param xdtype - first input ndarray data type
4384
+ * @param ydtype - second input ndarray data type
4385
+ * @param zdtype - third input ndarray data type
4386
+ * @param policy - output ndarray data type policy
4387
+ * @returns output ndarray data type
4388
+ *
4389
+ * @example
4390
+ * var dt = ns.ternaryOutputDataType( 'float64', 'float32', 'float32', 'complex_floating_point' );
4391
+ * // returns <DataType>
4392
+ */
4393
+ ternaryOutputDataType: typeof ternaryOutputDataType;
4394
+
4395
+ /**
4396
+ * Returns a loop block size for multi-dimensional array tiled loops.
4397
+ *
4398
+ * @param dtypeX - first input array data type
4399
+ * @param dtypeY - second input array data type
4400
+ * @param dtypeZ - third input array data type
4401
+ * @param dtypeW - output array data type
4402
+ * @returns block size (in units of elements)
4403
+ *
4404
+ * @example
4405
+ * var bsize = ns.ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' );
4406
+ * // returns <number>
4407
+ */
4408
+ ternaryBlockSize: typeof ternaryBlockSize;
4409
+
4410
+ /**
4411
+ * Returns a loop block size for multi-dimensional array tiled loops.
4412
+ *
4413
+ * @param dtypes - list of input and output ndarray data types
4414
+ * @returns block size (in units of elements)
4415
+ *
4416
+ * @example
4417
+ * var bsize = ns.blockSize( [ 'float64', 'float64', 'float64', 'float64' ] );
4418
+ * // returns <number>
4419
+ */
4420
+ blockSize: typeof blockSize;
4421
+
4422
+ /**
4423
+ * Converts an ndarray buffer to a generic array (which may include nested arrays).
4424
+ *
4425
+ * @param buffer - data buffer
4426
+ * @param shape - array shape
4427
+ * @param strides - array strides
4428
+ * @param offset - index offset
4429
+ * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
4430
+ * @returns array (which may include nested arrays)
4431
+ *
4432
+ * @example
4433
+ * var buffer = [ 1, 2, 3, 4 ];
4434
+ * var shape = [ 2, 2 ];
4435
+ * var order = 'row-major';
4436
+ * var strides = [ 2, 1 ];
4437
+ * var offset = 0;
4438
+ *
4439
+ * var out = ns.ndarray2array( buffer, shape, strides, offset, order );
4440
+ * // returns [ [ 1, 2 ], [ 3, 4 ] ]
4441
+ */
4442
+ ndarray2array: typeof ndarray2array;
4443
+
4444
+ /**
4445
+ * Returns a new ndarray where the order of elements along the last dimension of an input ndarray is reversed.
4446
+ *
4447
+ * @param x - input array
4448
+ * @returns output array
4449
+ *
4450
+ * @example
4451
+ * var typedarray = require( '@stdlib/array-typed' );
4452
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
4453
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
4454
+ *
4455
+ * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' );
4456
+ * var shape = [ 3, 2 ];
4457
+ * var strides = [ 2, 1 ];
4458
+ * var offset = 0;
4459
+ *
4460
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
4461
+ * // returns <ndarray>
4462
+ *
4463
+ * var sh = x.shape;
4464
+ * // returns [ 3, 2 ]
4465
+ *
4466
+ * var arr = ndarray2array( x );
4467
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
4468
+ *
4469
+ * var y = ns.toFlippedlr( x );
4470
+ * // returns <ndarray>
4471
+ *
4472
+ * sh = y.shape;
4473
+ * // returns [ 3, 2 ]
4474
+ *
4475
+ * arr = ndarray2array( y );
4476
+ * // returns [ [ 2.0, 1.0 ], [ 4.0, 3.0 ], [ 6.0, 5.0 ] ]
4477
+ */
4478
+ toFlippedlr: typeof toFlippedlr;
4479
+
4480
+ /**
4481
+ * Returns a new ndarray where the order of elements along the second-to-last dimension of an input ndarray is reversed.
4482
+ *
4483
+ * @param x - input array
4484
+ * @returns output array
4485
+ *
4486
+ * @example
4487
+ * var typedarray = require( '@stdlib/array-typed' );
4488
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
4489
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
4490
+ *
4491
+ * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' );
4492
+ * var shape = [ 3, 2 ];
4493
+ * var strides = [ 2, 1 ];
4494
+ * var offset = 0;
4495
+ *
4496
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
4497
+ * // returns <ndarray>
4498
+ *
4499
+ * var sh = x.shape;
4500
+ * // returns [ 3, 2 ]
4501
+ *
4502
+ * var arr = ndarray2array( x );
4503
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
4504
+ *
4505
+ * var y = ns.toFlippedud( x );
4506
+ * // returns <ndarray>
4507
+ *
4508
+ * sh = y.shape;
4509
+ * // returns [ 3, 2 ]
4510
+ *
4511
+ * arr = ndarray2array( y );
4512
+ * // returns [ [ 5.0, 6.0 ], [ 3.0, 4.0 ], [ 1.0, 2.0 ] ]
4513
+ */
4514
+ toFlippedud: typeof toFlippedud;
4515
+
4516
+ /**
4517
+ * Normalizes a list of indices to the interval `[0,max]`.
4518
+ *
4519
+ * ## Notes
4520
+ *
4521
+ * - If provided an out-of-bounds index, the function normalizes the index to `-1`.
4522
+ *
4523
+ * @param indices - indices
4524
+ * @param max - maximum index
4525
+ * @returns normalized indices
4526
+ *
4527
+ * @example
4528
+ * var indices = ns.toNormalizedIndices( [ -2, 5 ], 10 );
4529
+ * // returns [ 9, 5 ]
4530
+ *
4531
+ * indices = ns.toNormalizedIndices( [ -2, 15 ], 10 );
4532
+ * // returns [ 9, -1 ]
4533
+ */
4534
+ toNormalizedIndices: typeof toNormalizedIndices;
4535
+
4536
+ /**
4537
+ * Returns a new ndarray where the order of elements of an input ndarray is reversed along each dimension.
4538
+ *
4539
+ * @param x - input array
4540
+ * @returns output array
4541
+ *
4542
+ * @example
4543
+ * var typedarray = require( '@stdlib/array-typed' );
4544
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
4545
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
4546
+ *
4547
+ * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' );
4548
+ * var shape = [ 3, 2 ];
4549
+ * var strides = [ 2, 1 ];
4550
+ * var offset = 0;
4551
+ *
4552
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
4553
+ * // returns <ndarray>
4554
+ *
4555
+ * var sh = x.shape;
4556
+ * // returns [ 3, 2 ]
4557
+ *
4558
+ * var arr = ndarray2array( x );
4559
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
4560
+ *
4561
+ * var y = ns.toReversed( x );
4562
+ * // returns <ndarray>
4563
+ *
4564
+ * sh = y.shape;
4565
+ * // returns [ 3, 2 ]
4566
+ *
4567
+ * arr = ndarray2array( y );
4568
+ * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ]
4569
+ */
4570
+ toReversed: typeof toReversed;
4571
+
4572
+ /**
4573
+ * Returns a new ndarray where the order of elements of an input ndarray along a specified dimension is reversed.
2643
4574
  *
2644
- * // From the perspective of an underlying buffer...
2645
- * idx = sub2ind( shape, strides, offset, 0, 0, mode );
2646
- * // returns 2
4575
+ * @param x - input array
4576
+ * @param dim - index of dimension to reverse
4577
+ * @returns output array
2647
4578
  *
2648
- * idx = sub2ind( shape, strides, offset, 0, 1, mode );
2649
- * // returns 3
4579
+ * @example
4580
+ * var typedarray = require( '@stdlib/array-typed' );
4581
+ * var ndarray = require( '@stdlib/ndarray-ctor' );
4582
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
2650
4583
  *
2651
- * idx = sub2ind( shape, strides, offset, 1, 0, mode );
2652
- * // returns 0
4584
+ * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' );
4585
+ * var shape = [ 3, 2 ];
4586
+ * var strides = [ 2, 1 ];
4587
+ * var offset = 0;
2653
4588
  *
2654
- * idx = sub2ind( shape, strides, offset, 1, 1, mode );
2655
- * // returns 1
2656
- * ```
4589
+ * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
4590
+ * // returns <ndarray>
2657
4591
  *
2658
- * In short, from the perspective of a view, view data is always ordered.
4592
+ * var sh = x.shape;
4593
+ * // returns [ 3, 2 ]
2659
4594
  *
4595
+ * var arr = ndarray2array( x );
4596
+ * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
2660
4597
  *
2661
- * @param shape - array shape
2662
- * @param strides - stride array
2663
- * @param offset - location of the first indexed value **based** on the stride array
2664
- * @param args - subscripts followed by a `mode` specifying how to handle subscripts which exceed array dimensions
2665
- * @param mode - specifies how to handle subscripts which exceed array dimensions
2666
- * @throws must provide subscripts which do not exceed array dimensions
2667
- * @returns linear index
4598
+ * var y = ns.toReversedDimension( x, 0 );
4599
+ * // returns <ndarray>
2668
4600
  *
2669
- * @example
2670
- * var shape = [ 3, 3, 3 ];
2671
- * var strides = [ 9, 3, 1 ];
2672
- * var offset = 0;
2673
- * var mode = [ 'throw' ]
4601
+ * sh = y.shape;
4602
+ * // returns [ 3, 2 ]
2674
4603
  *
2675
- * var idx = ns.sub2ind( shape, strides, offset, 1, 2, 2, mode );
2676
- * // returns 17
4604
+ * arr = ndarray2array( y );
4605
+ * // returns [ [ 5.0, 6.0 ], [ 3.0, 4.0 ], [ 1.0, 2.0 ] ]
2677
4606
  */
2678
- sub2ind: typeof sub2ind;
4607
+ toReversedDimension: typeof toReversedDimension;
2679
4608
 
2680
4609
  /**
2681
- * Converts an ndarray buffer to a generic array (which may include nested arrays).
4610
+ * Returns a list of unique indices after normalizing to the interval `[0,max]`.
2682
4611
  *
2683
- * @param buffer - data buffer
2684
- * @param shape - array shape
2685
- * @param strides - array strides
2686
- * @param offset - index offset
2687
- * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
2688
- * @returns array (which may include nested arrays)
4612
+ * ## Notes
4613
+ *
4614
+ * - If provided an out-of-bounds index, the function returns `null`.
4615
+ *
4616
+ * @param indices - indices
4617
+ * @param max - maximum index
4618
+ * @returns normalized indices (or null)
2689
4619
  *
2690
4620
  * @example
2691
- * var buffer = [ 1, 2, 3, 4 ];
2692
- * var shape = [ 2, 2 ];
2693
- * var order = 'row-major';
2694
- * var strides = [ 2, 1 ];
2695
- * var offset = 0;
4621
+ * var indices = ns.toUniqueNormalizedIndices( [ -2, 5 ], 10 );
4622
+ * // returns [ 9, 5 ]
2696
4623
  *
2697
- * var out = ns.ndarray2array( buffer, shape, strides, offset, order );
2698
- * // returns [ [ 1, 2 ], [ 3, 4 ] ]
4624
+ * indices = ns.toUniqueNormalizedIndices( [ -2, 15 ], 10 );
4625
+ * // returns null
2699
4626
  */
2700
- ndarray2array: typeof ndarray2array;
4627
+ toUniqueNormalizedIndices: typeof toUniqueNormalizedIndices;
2701
4628
 
2702
4629
  /**
2703
4630
  * Transposes a matrix (or a stack of matrices).
@@ -2773,6 +4700,80 @@ interface Namespace {
2773
4700
  */
2774
4701
  unary: typeof unary;
2775
4702
 
4703
+ /**
4704
+ * Performs a reduction over elements in an ndarray.
4705
+ *
4706
+ * @param arrays - array-like object containing one input ndarray
4707
+ * @param initial - initial value
4708
+ * @param clbk - callback function
4709
+ * @returns accumulated result
4710
+ *
4711
+ * @example
4712
+ * var Float64Array = require( '@stdlib/array-float64' );
4713
+ *
4714
+ * function add( acc, x ) {
4715
+ * return acc + x;
4716
+ * }
4717
+ *
4718
+ * // Create a data buffer:
4719
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
4720
+ *
4721
+ * // Define the shape of the input array:
4722
+ * var shape = [ 3, 1, 2 ];
4723
+ *
4724
+ * // Define the array strides:
4725
+ * var sx = [ 4, 4, 1 ];
4726
+ *
4727
+ * // Define the index offset:
4728
+ * var ox = 1;
4729
+ *
4730
+ * // Create the input ndarray-like object:
4731
+ * var x = {
4732
+ * 'dtype': 'float64',
4733
+ * 'data': xbuf,
4734
+ * 'shape': shape,
4735
+ * 'strides': sx,
4736
+ * 'offset': ox,
4737
+ * 'order': 'row-major'
4738
+ * };
4739
+ *
4740
+ * // Compute the sum:
4741
+ * var v = ns.unaryAccumulate( [ x ], 0.0, add );
4742
+ * // returns 39.0
4743
+ */
4744
+ unaryAccumulate: typeof unaryAccumulate;
4745
+
4746
+ /**
4747
+ * Returns a function which dispatches to a native add-on applying a unary function to an input ndarray.
4748
+ *
4749
+ * @param addon - add-on function
4750
+ * @param fallback - fallback function
4751
+ * @returns dispatch function
4752
+ *
4753
+ * @example
4754
+ * var array = require( '@stdlib/ndarray-array' );
4755
+ * var zeros = require( '@stdlib/ndarray-zeros' );
4756
+ *
4757
+ * function addon( x, metaX, y, metaY ) {
4758
+ * // Call into native add-on...
4759
+ * }
4760
+ *
4761
+ * function fallback( x, y ) {
4762
+ * // Fallback JavaScript implementation...
4763
+ * }
4764
+ *
4765
+ * // Create a ns.unaryAddonDispatch function:
4766
+ * var f = ns.unaryAddonDispatch( addon, fallback );
4767
+ *
4768
+ * // ...
4769
+ *
4770
+ * // Invoke the ns.unaryAddonDispatch function with ndarray arguments:
4771
+ * var x = array( [ [ 1, 2], [ 3, 4 ] ] );
4772
+ * var y = zeros( [ 2, 2 ] );
4773
+ * f( x, y );
4774
+ */
4775
+ unaryAddonDispatch: typeof unaryAddonDispatch;
4776
+
2776
4777
  /**
2777
4778
  * Applies a unary function to elements in an ndarray and assigns results to elements in an ndarray.
2778
4779
  *
@@ -2784,7 +4785,7 @@ interface Namespace {
2784
4785
  * @throws arrays must have the same shape
2785
4786
  *
2786
4787
  * @example
2787
- * var identity = require( '@stdlib/math-base-special-identity' );
4788
+ * var identity = require( '@stdlib/number-float64-base-identity' );
2788
4789
  * var Float64Array = require( '@stdlib/array-float64' );
2789
4790
  * var ndarray = require( '@stdlib/ndarray-ctor' );
2790
4791
  *
@@ -2819,6 +4820,20 @@ interface Namespace {
2819
4820
  */
2820
4821
  unaryBy: typeof unaryBy;
2821
4822
 
4823
+ /**
4824
+ * Resolves the input ndarray casting data type for a unary function.
4825
+ *
4826
+ * @param idtype - input ndarray data type
4827
+ * @param odtype - output ndarray data type
4828
+ * @param policy - input ndarray casting data type policy
4829
+ * @returns input ndarray casting data type
4830
+ *
4831
+ * @example
4832
+ * var dt = ns.unaryInputCastingDataType( 'float64', 'float64', 'none' );
4833
+ * // returns <string>
4834
+ */
4835
+ unaryInputCastingDataType: typeof unaryInputCastingDataType;
4836
+
2822
4837
  /**
2823
4838
  * Reorders ndarray dimensions and associated strides for loop interchange.
2824
4839
  *
@@ -2829,6 +4844,7 @@ interface Namespace {
2829
4844
  * - **sh**: dimensions sorted in loop order.
2830
4845
  * - **sx**: input ndarray strides sorted in loop order.
2831
4846
  * - **sy**: output ndarray strides sorted in loop order.
4847
+ * - **idx**: dimension indices sorted in loop order.
2832
4848
  *
2833
4849
  * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
2834
4850
  *
@@ -2838,9 +4854,9 @@ interface Namespace {
2838
4854
  *
2839
4855
  * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
2840
4856
  *
2841
- * @param sh - array dimensions
2842
- * @param sx - input array stride lengths
2843
- * @param sy - output array stride lengths
4857
+ * @param shape - array dimensions
4858
+ * @param stridesX - input array stride lengths
4859
+ * @param stridesY - output array stride lengths
2844
4860
  * @returns loop interchange data
2845
4861
  *
2846
4862
  * @example
@@ -2860,6 +4876,9 @@ interface Namespace {
2860
4876
  *
2861
4877
  * var ssy = o.sy;
2862
4878
  * // returns [ 6, -2, 1 ]
4879
+ *
4880
+ * var idx = o.idx;
4881
+ * // returns [ 2, 1, 0 ]
2863
4882
  */
2864
4883
  unaryLoopOrder: typeof unaryLoopOrder;
2865
4884
 
@@ -2872,10 +4891,308 @@ interface Namespace {
2872
4891
  *
2873
4892
  * @example
2874
4893
  * var dt = ns.unaryOutputDataType( 'float64', 'complex_floating_point' );
2875
- * // returns <string>
4894
+ * // returns <DataType>
2876
4895
  */
2877
4896
  unaryOutputDataType: typeof unaryOutputDataType;
2878
4897
 
4898
+ /**
4899
+ * Constructor for performing a reduction on an input ndarray.
4900
+ *
4901
+ * @param table - dispatch table
4902
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
4903
+ * @param odtypes - list of supported output data types
4904
+ * @param policies - dispatch policies
4905
+ * @returns instance
4906
+ *
4907
+ * @example
4908
+ * var base = require( '@stdlib/stats-base-ndarray-max' );
4909
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
4910
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
4911
+ *
4912
+ * var idt = dtypes( 'real_and_generic' );
4913
+ * var odt = idt;
4914
+ * var policies = {
4915
+ * 'output': 'same',
4916
+ * 'casting': 'none'
4917
+ * };
4918
+ *
4919
+ * var table = {
4920
+ * 'default': base
4921
+ * };
4922
+ * var max = new ns.unaryReduceStrided1dDispatch( table, [ idt ], odt, policies );
4923
+ *
4924
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
4925
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
4926
+ *
4927
+ * var y = max.apply( x );
4928
+ * // returns <ndarray>
4929
+ *
4930
+ * var v = y.get();
4931
+ * // returns 2.0
4932
+ */
4933
+ unaryReduceStrided1dDispatch: typeof unaryReduceStrided1dDispatch;
4934
+
4935
+ /**
4936
+ * Constructor for performing a reduction on an input ndarray according to a callback function.
4937
+ *
4938
+ * @param table - dispatch table
4939
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
4940
+ * @param odtypes - list of supported output data types
4941
+ * @param policies - dispatch policies
4942
+ * @returns instance
4943
+ *
4944
+ * @example
4945
+ * var base = require( '@stdlib/stats-base-ndarray-max-by' );
4946
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
4947
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
4948
+ *
4949
+ * var idt = dtypes( 'real_and_generic' );
4950
+ * var odt = idt;
4951
+ * var policies = {
4952
+ * 'output': 'same',
4953
+ * 'casting': 'none'
4954
+ * };
4955
+ *
4956
+ * var table = {
4957
+ * 'default': base
4958
+ * };
4959
+ * var maxBy = new ns.unaryReduceStrided1dDispatchBy( table, [ idt ], odt, policies );
4960
+ *
4961
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
4962
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
4963
+ *
4964
+ * function clbk( v ) {
4965
+ * return v * 2.0;
4966
+ * }
4967
+ *
4968
+ * var y = maxBy.apply( x, clbk );
4969
+ * // returns <ndarray>
4970
+ *
4971
+ * var v = y.get();
4972
+ * // returns 4.0
4973
+ */
4974
+ unaryReduceStrided1dDispatchBy: typeof unaryReduceStrided1dDispatchBy;
4975
+
4976
+ /**
4977
+ * Creates a function for performing a reduction on a provided ndarray according to a callback function.
4978
+ *
4979
+ * @param table - dispatch table
4980
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
4981
+ * @param odtypes - list of supported output data types
4982
+ * @param policies - dispatch policies
4983
+ * @returns function for applying a unary function
4984
+ *
4985
+ * @example
4986
+ * var base = require( '@stdlib/stats-base-ndarray-max-by' );
4987
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
4988
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
4989
+ *
4990
+ * var idt = dtypes( 'real_and_generic' );
4991
+ * var odt = idt;
4992
+ * var policies = {
4993
+ * 'output': 'same',
4994
+ * 'casting': 'none'
4995
+ * };
4996
+ *
4997
+ * var table = {
4998
+ * 'default': base
4999
+ * };
5000
+ * var maxBy = ns.unaryReduceStrided1dDispatchByFactory( table, [ idt ], odt, policies );
5001
+ *
5002
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
5003
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
5004
+ *
5005
+ * function clbk( v ) {
5006
+ * return v * 2.0;
5007
+ * }
5008
+ *
5009
+ * var y = maxBy( x, clbk );
5010
+ * // returns <ndarray>
5011
+ *
5012
+ * var v = y.get();
5013
+ * // returns 4.0
5014
+ */
5015
+ unaryReduceStrided1dDispatchByFactory: typeof unaryReduceStrided1dDispatchByFactory;
5016
+
5017
+ /**
5018
+ * Creates a function for performing a reduction on a provided ndarray.
5019
+ *
5020
+ * @param table - dispatch table
5021
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
5022
+ * @param odtypes - list of supported output data types
5023
+ * @param policies - dispatch policies
5024
+ * @returns function for applying a unary function
5025
+ *
5026
+ * @example
5027
+ * var base = require( '@stdlib/stats-base-ndarray-max' );
5028
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
5029
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
5030
+ *
5031
+ * var idt = dtypes( 'real_and_generic' );
5032
+ * var odt = idt;
5033
+ * var policies = {
5034
+ * 'output': 'same',
5035
+ * 'casting': 'none'
5036
+ * };
5037
+ *
5038
+ * var table = {
5039
+ * 'default': base
5040
+ * };
5041
+ * var max = ns.unaryReduceStrided1dDispatchFactory( table, [ idt ], odt, policies );
5042
+ *
5043
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
5044
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
5045
+ *
5046
+ * var y = max( x );
5047
+ * // returns <ndarray>
5048
+ *
5049
+ * var v = y.get();
5050
+ * // returns 2.0
5051
+ */
5052
+ unaryReduceStrided1dDispatchFactory: typeof unaryReduceStrided1dDispatchFactory;
5053
+
5054
+ /**
5055
+ * Performs a reduction over a list of specified dimensions in an input ndarray according to a callback function and assigns results to a provided output ndarray.
5056
+ *
5057
+ * @param fcn - reduction function
5058
+ * @param arrays - array-like object containing ndarrays
5059
+ * @param dims - list of dimensions over which to perform a reduction
5060
+ * @param options - function options
5061
+ * @param clbk - callback function
5062
+ * @param thisArg - callback execution context
5063
+ *
5064
+ * @example
5065
+ * var Float64Array = require( '@stdlib/array-float64' );
5066
+ * var filled = require( '@stdlib/array-base-filled' );
5067
+ * var ndarray2array = require( '@stdlib/ndarray-base-to-array' );
5068
+ * var everyBy = require( '@stdlib/ndarray-base-every-by' );
5069
+ *
5070
+ * function clbk( value ) {
5071
+ * return value > 0.0;
5072
+ * }
5073
+ *
5074
+ * // Create data buffers:
5075
+ * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
5076
+ * var ybuf = filled( false, 3 );
5077
+ *
5078
+ * // Define the array shapes:
5079
+ * var xsh = [ 1, 3, 2, 2 ];
5080
+ * var ysh = [ 1, 3 ];
5081
+ *
5082
+ * // Define the array strides:
5083
+ * var sx = [ 12, 4, 2, 1 ];
5084
+ * var sy = [ 3, 1 ];
5085
+ *
5086
+ * // Define the index offsets:
5087
+ * var ox = 0;
5088
+ * var oy = 0;
5089
+ *
5090
+ * // Create an input ndarray-like object:
5091
+ * var x = {
5092
+ * 'dtype': 'float64',
5093
+ * 'data': xbuf,
5094
+ * 'shape': xsh,
5095
+ * 'strides': sx,
5096
+ * 'offset': ox,
5097
+ * 'order': 'row-major'
5098
+ * };
5099
+ *
5100
+ * // Create an output ndarray-like object:
5101
+ * var y = {
5102
+ * 'dtype': 'generic',
5103
+ * 'data': ybuf,
5104
+ * 'shape': ysh,
5105
+ * 'strides': sy,
5106
+ * 'offset': oy,
5107
+ * 'order': 'row-major'
5108
+ * };
5109
+ *
5110
+ * // Perform a reduction:
5111
+ * ns.unaryReduceSubarrayBy( everyBy, [ x, y ], [ 2, 3 ], clbk );
5112
+ *
5113
+ * var arr = ndarray2array( y.data, y.shape, y.strides, y.offset, y.order );
5114
+ * // returns [ [ true, false, true ] ]
5115
+ */
5116
+ unaryReduceSubarrayBy: typeof unaryReduceSubarrayBy;
5117
+
5118
+ /**
5119
+ * Constructor for applying a strided function to an input ndarray.
5120
+ *
5121
+ * @param table - dispatch table
5122
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
5123
+ * @param odtypes - list of supported output data types
5124
+ * @param policies - dispatch policies
5125
+ * @param options - function options
5126
+ * @returns instance
5127
+ *
5128
+ * @example
5129
+ * var base = require( '@stdlib/stats-base-ndarray-cumax' );
5130
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
5131
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
5132
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
5133
+ *
5134
+ * var idt = dtypes( 'real_and_generic' );
5135
+ * var odt = idt;
5136
+ * var policies = {
5137
+ * 'output': 'same',
5138
+ * 'casting': 'none'
5139
+ * };
5140
+ *
5141
+ * var table = {
5142
+ * 'default': base
5143
+ * };
5144
+ * var cumax = new ns.unaryStrided1dDispatch( table, [ idt ], odt, policies );
5145
+ *
5146
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
5147
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
5148
+ *
5149
+ * var y = cumax.apply( x );
5150
+ * // returns <ndarray>
5151
+ *
5152
+ * var arr = ndarray2array( y );
5153
+ * // returns [ -1.0, 2.0, 2.0 ]
5154
+ */
5155
+ unaryStrided1dDispatch: typeof unaryStrided1dDispatch;
5156
+
5157
+ /**
5158
+ * Creates a function for applying a strided function to a provided ndarray.
5159
+ *
5160
+ * @param table - dispatch table
5161
+ * @param idtypes - list containing lists of supported input data types for each ndarray argument
5162
+ * @param odtypes - list of supported output data types
5163
+ * @param policies - dispatch policies
5164
+ * @param options - function options
5165
+ * @returns function for applying a unary function
5166
+ *
5167
+ * @example
5168
+ * var base = require( '@stdlib/stats-base-ndarray-cumax' );
5169
+ * var dtypes = require( '@stdlib/ndarray-dtypes' );
5170
+ * var ndarray2array = require( '@stdlib/ndarray-to-array' );
5171
+ * var ndarray = require( '@stdlib/ndarray-base-ctor' );
5172
+ *
5173
+ * var idt = dtypes( 'real_and_generic' );
5174
+ * var odt = idt;
5175
+ * var policies = {
5176
+ * 'output': 'same',
5177
+ * 'casting': 'none'
5178
+ * };
5179
+ *
5180
+ * var table = {
5181
+ * 'default': base
5182
+ * };
5183
+ * var cumax = ns.unaryStrided1dDispatchFactory( table, [ idt ], odt, policies );
5184
+ *
5185
+ * var xbuf = [ -1.0, 2.0, -3.0 ];
5186
+ * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
5187
+ *
5188
+ * var y = cumax( x );
5189
+ * // returns <ndarray>
5190
+ *
5191
+ * var arr = ndarray2array( y );
5192
+ * // returns [ -1.0, 2.0, 2.0 ]
5193
+ */
5194
+ unaryStrided1dDispatchFactory: typeof unaryStrided1dDispatchFactory;
5195
+
2879
5196
  /**
2880
5197
  * Returns a loop block size for multi-dimensional array tiled loops.
2881
5198
  *
@@ -2980,6 +5297,56 @@ interface Namespace {
2980
5297
  * // returns 'generic'
2981
5298
  */
2982
5299
  zerosLike: typeof zerosLike;
5300
+
5301
+ /**
5302
+ * Zips one or more one-dimensional ndarrays to an array of composite views.
5303
+ *
5304
+ * ## Notes
5305
+ *
5306
+ * - The function assumes that the list of ndarrays to be zipped all have the same length.
5307
+ * - The list of provided labels should equal the number of ndarrays to be zipped.
5308
+ * - Each view in the returned array shares the same memory as the corresponding elements in the input ndarrays. Accordingly, mutation of either an input ndarray or a view will mutate the other.
5309
+ *
5310
+ * @param arrays - list of ndarrays to be zipped
5311
+ * @param labels - list of labels
5312
+ * @returns output array
5313
+ *
5314
+ * @example
5315
+ * var array2ndarray = require( '@stdlib/ndarray-base-from-array' );
5316
+ *
5317
+ * var x = array2ndarray( [ 1, 2, 3 ], 'row-major' );
5318
+ * var y = array2ndarray( [ 'a', 'b', 'c' ], 'row-major' );
5319
+ *
5320
+ * var labels = [ 'x', 'y' ];
5321
+ *
5322
+ * var z = ns.zip2views1d( [ x, y ], labels );
5323
+ * // returns [ <Object>, <Object>, <Object> ]
5324
+ *
5325
+ * var v0 = z[ 0 ].toJSON();
5326
+ * // returns { 'x': 1, 'y': 'a' }
5327
+ *
5328
+ * var v1 = z[ 1 ].toJSON();
5329
+ * // returns { 'x': 2, 'y': 'b' }
5330
+ *
5331
+ * var v2 = z[ 2 ].toJSON();
5332
+ * // returns { 'x': 3, 'y': 'c' }
5333
+ *
5334
+ * // Mutate one of the input arrays:
5335
+ * x.set( 0, 5 );
5336
+ *
5337
+ * v0 = z[ 0 ].toJSON();
5338
+ * // returns { 'x': 5, 'y': 'a' }
5339
+ *
5340
+ * // Set a view property:
5341
+ * z[ 1 ].y = 'beep';
5342
+ *
5343
+ * v1 = z[ 1 ].toJSON();
5344
+ * // returns { 'x': 2, 'y': 'beep' }
5345
+ *
5346
+ * var v = y.get( 1 );
5347
+ * // returns 'beep'
5348
+ */
5349
+ zip2views1d: typeof zip2views1d;
2983
5350
  }
2984
5351
 
2985
5352
  /**