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 | 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 29x 29x 29x 29x 29x 29x 29x 29x 29x 29x 4x 7x 7x 3x 3x 3x 7x 1x 1x 25x 25x 29x 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 getShape = require( '@stdlib/ndarray/base/shape' );
// 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 ) {
var sh;
var N;
var i;
N = shape.length;
sh = getShape( arr, false );
// Check whether we need to broadcast the input array...
if ( sh.length === N ) {
for ( i = 0; i < N; i++ ) {
// 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;
|