## Usage ```javascript var maybeBroadcastArray = require( '@stdlib/ndarray/base/maybe-broadcast-array' ); ``` #### maybeBroadcastArray( arr, shape ) Broadcasts an [ndarray][@stdlib/ndarray/base/ctor] to a specified `shape` if and only if the specified `shape` differs from the provided [ndarray][@stdlib/ndarray/base/ctor]'s shape. ```javascript var array = require( '@stdlib/ndarray/array' ); // Create a 1x2 ndarray: var x = array( [ [ 1, 2 ] ] ); // returns [ [ 1, 2 ] ] // Broadcast to a 2x2x2 ndarray: var y = maybeBroadcastArray( x, [ 2, 2, 2 ] ); // returns [ [ [ 1, 2 ], [ 1, 2 ] ], [ [ 1, 2 ], [ 1, 2 ] ] ] ```

## Notes - The function throws an error if a provided [ndarray][@stdlib/ndarray/base/ctor] is [incompatible][@stdlib/ndarray/base/broadcast-shapes] with a provided shape. - If a provided [ndarray][@stdlib/ndarray/base/ctor] has the same shape as the specified shape, the function returns the provided [ndarray][@stdlib/ndarray/base/ctor]. - If a provided [ndarray][@stdlib/ndarray/base/ctor] has a different (broadcast compatible) shape than the specified shape, the function returns a new (base) [ndarray][@stdlib/ndarray/base/ctor] view of the provided [ndarray][@stdlib/ndarray/base/ctor]'s data. 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 [ndarray][@stdlib/ndarray/base/ctor], copy the [ndarray][@stdlib/ndarray/base/ctor] **before** performing operations which may mutate elements. - A returned [ndarray][@stdlib/ndarray/base/ctor] is a "base" [ndarray][@stdlib/ndarray/base/ctor], and, thus, a returned [ndarray][@stdlib/ndarray/base/ctor] view does not perform bounds checking or afford any of the guarantees of the non-base [ndarray][@stdlib/ndarray/ctor] constructor. The primary intent of this function is to broadcast an ndarray-like object within internal implementations and to do so with minimal overhead.

## Examples ```javascript var array = require( '@stdlib/ndarray/array' ); var ndarray2array = require( '@stdlib/ndarray/to-array' ); var maybeBroadcastArray = require( '@stdlib/ndarray/base/maybe-broadcast-array' ); // Create a 2x2 array: var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); // returns [ [ 1, 2 ], [ 3, 4 ] ] // Broadcast the array to 3x2x2: var y = maybeBroadcastArray( x, [ 3, 2, 2 ] ); // returns [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ] ] ```