Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x | /**
* @license Apache-2.0
*
* Copyright (c) 2026 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
'use strict';
// MODULES //
var broadcast = require( '@stdlib/ndarray/base/broadcast-array-except-dimensions' );
var normalizeIndices = require( '@stdlib/ndarray/base/to-unique-normalized-indices' );
var getShape = require( '@stdlib/ndarray/base/shape' );
var copy = require( '@stdlib/array/base/copy' );
var join = require( '@stdlib/array/base/join' );
var format = require( '@stdlib/string/format' );
// MAIN //
/**
* Broadcasts an ndarray to a specified shape while keeping a list of specified dimensions unchanged if and only if the specified shape differs from the provided ndarray's shape.
*
* ## Notes
*
* - 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.
*
* @param {ndarray} arr - input array
* @param {NonNegativeIntegerArray} shape - desired shape
* @param {NegativeIntegerArray} dims - list of dimensions to exclude from broadcasting
* @throws {Error} input array cannot have more dimensions than the desired shape
* @throws {Error} broadcasted dimensions in the input array and desired shape must be broadcast compatible
* @throws {RangeError} dimension indices must not exceed desired shape bounds
* @throws {Error} must provide unique dimension indices
* @returns {ndarray} broadcasted array
*
* @example
* var array = require( '@stdlib/ndarray/array' );
* var getShape = require( '@stdlib/ndarray/shape' );
*
* var x = array( [ [ 1, 2, 3 ] ] );
* // returns <ndarray>[ [ 1, 2, 3 ] ]
*
* var y = maybeBroadcastArrayExceptDimensions( x, [ 2, 2, 3 ], [ -2 ] );
* // returns <ndarray>[ [ [ 1, 2, 3 ] ], [ [ 1, 2, 3 ] ] ]
*/
function maybeBroadcastArrayExceptDimensions( arr, shape, dims ) { // eslint-disable-line id-length
var idx;
var sh;
var dl;
var N;
var M;
var i;
var j;
// Resolve the shape of the input array:
sh = getShape( arr, false );
N = shape.length;
M = sh.length;
// Check whether we need to broadcast the input array...
if ( M === N ) {
// Copy input arguments to avoid unintended mutation:
idx = copy( dims );
// Verify that we've been provided a list of unique dimension indices...
dl = idx.length;
idx = normalizeIndices( idx, M-1 );
if ( idx === null ) {
throw new RangeError( format( 'invalid argument. Third argument contains an out-of-bounds dimension index. Value: [%s].', join( dims, ',' ) ) );
}
idx.sort(); // sort in ascending order
if ( idx.length !== dl ) {
throw new Error( format( 'invalid argument. Third argument must contain a list of unique dimension indices. Value: [%s].', join( dims, ',' ) ) );
}
j = 0;
for ( i = 0; i < N; i++ ) {
// Check for a skipped dimension...
if ( j < dl && i === idx[ j ] ) {
j += 1;
continue;
}
// Check whether dimensions match...
if ( sh[ i ] !== shape[ i ] ) {
// We found a mismatched dimension; delegate to `broadcast` to ensure that the input array is broadcast compatible with the desired array shape...
return broadcast( arr, shape, dims );
}
}
return arr;
}
// If we are provided an array having a different rank (i.e., number of dimensions) than the desired shape, assume we need to broadcast, delegating to `broadcast` to ensure that the input array is broadcast compatible with the desired array shape...
return broadcast( arr, shape, dims );
}
// EXPORTS //
module.exports = maybeBroadcastArrayExceptDimensions;
|