importbroadcastShapesfrom'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-base-broadcast-shapes@esm/index.mjs';

Broadcasts array shapes to a single shape.

varsh1=[8,1,6,1];varsh2=[7,1,5];varsh=broadcastShapes([sh1,sh2]);// returns [ 8, 7, 6, 5 ]

• When operating on two arrays, the function compares their shapes element-wise, beginning with the trailing (i.e., rightmost) dimension. The following are examples of compatible shapes and their corresponding broadcasted shape:

  A      (4d array):  8 x 1 x 6 x 1B      (3d array):      7 x 1 x 5---------------------------------Result (4d array):  8 x 7 x 6 x 5A      (2d array):  5 x 4B      (1d array):      1-------------------------Result (2d array):  5 x 4A      (2d array):  5 x 4B      (1d array):      4-------------------------Result (2d array):  5 x 4A      (3d array):  15 x 3 x 5B      (3d array):  15 x 1 x 5------------------------------Result (3d array):  15 x 3 x 5A      (3d array):  15 x 3 x 5B      (2d array):       3 x 5------------------------------Result (3d array):  15 x 3 x 5A      (3d array):  15 x 3 x 5B      (2d array):       3 x 1------------------------------Result (3d array):  15 x 3 x 5A      (5d array):  8 x 1 x 1 x 6 x 1B      (4d array):      1 x 7 x 1 x 5C      (5d array):  8 x 4 x 1 x 6 x 5-------------------------------------Result (5d array):  8 x 4 x 7 x 6 x 5A      (5d array):  8 x 1 x 1 x 6 x 1B      (1d array):                  0-------------------------------------Result (5d array):  8 x 1 x 1 x 6 x 0A      (5d array):  8 x 0 x 1 x 6 x 1B      (2d array):              6 x 5-------------------------------------Result (5d array):  8 x 0 x 1 x 6 x 5A      (5d array):  8 x 1 x 1 x 6 x 1B      (5d array):  8 x 0 x 1 x 6 x 1-------------------------------------Result (5d array):  8 x 0 x 1 x 6 x 1A      (3d array):  3 x 2 x 1B      (0d array):-----------------------------Result (3d array):  3 x 2 x 1A      (0d array):B      (3d array):  3 x 2 x 1-----------------------------Result (3d array):  3 x 2 x 1

  As demonstrated above, arrays are not required to have the same number of dimensions in order to be broadcast compatible. Array shapes with fewer dimensions are implicitly prepended with singleton dimensions (i.e., dimensions equal to1). Accordingly, the following example

  A      (2d array):  5 x 4B      (1d array):      4-------------------------Result (2d array):  5 x 4

  is equivalent to

  A      (2d array):  5 x 4B      (2d array):  1 x 4-------------------------Result (2d array):  5 x 4

  Similarly, a zero-dimensional array is expanded (by prepending singleton dimensions) from

  A      (3d array):  3 x 2 x 1B      (0d array):-----------------------------Result (3d array):  3 x 2 x 1

  to

  A      (3d array):  3 x 2 x 1B      (3d array):  1 x 1 x 1-----------------------------Result (3d array):  3 x 2 x 1

  Stated otherwise, every array has implicit leading dimensions of size1. During broadcasting, a3 x 4 matrix is the same as a3 x 4 x 1 x 1 x 1 multidimensional array.

• Two respective dimensions in two shape arrays are compatible if

  1. the dimensions are equal.
  2. one dimension is1.

  The two aforementioned rules apply to empty arrays or arrays that have a dimension of size0. For unequal dimensions, the size of the dimension which is not1 determines the size of the output shape dimension.

  Accordingly, dimensions of size0 must be paired with a dimension of size0 or1. In such cases, by the rules above, the size of the corresponding output shape dimension is0.

• The function returnsnull if provided incompatible shapes (i.e., shapes which cannot be broadcast with one another).

  varsh1=[3,2];varsh2=[2,3];varsh=broadcastShapes([sh1,sh2]);// returns null

  The following are examples of array shapes which arenot compatible and donot broadcast:

  A      (1d array):  3B      (1d array):  4                   # dimension does not matchA      (2d array):      2 x 1B      (3d array):  8 x 4 x 3           # second dimension does not matchA      (3d array):  15 x 3 x 5B      (2d array):  15 x 3              # singleton dimensions can only be prepended, not appendedA      (5d array):  8 x 8 x 1 x 6 x 1B      (5d array):  8 x 0 x 1 x 6 x 1   # second dimension does not match

This package is part ofstdlib, a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to developstdlib, see the main projectrepository.

SeeLICENSE.

Copyright © 2016-2025. The StdlibAuthors.