diff --git a/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts index 82e7aa3f15cb..041a8df4342c 100644 --- a/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts @@ -22,9 +22,13 @@ import any = require( '@stdlib/ndarray/base/any' ); import anyBy = require( '@stdlib/ndarray/base/any-by' ); +import appendSingletonDimensions = require( '@stdlib/ndarray/base/append-singleton-dimensions' ); import assert = require( '@stdlib/ndarray/base/assert' ); import assign = require( '@stdlib/ndarray/base/assign' ); import assignScalar = require( '@stdlib/ndarray/base/assign-scalar' ); +import atleast1d = require( '@stdlib/ndarray/base/atleast1d' ); +import atleast2d = require( '@stdlib/ndarray/base/atleast2d' ); +import atleast3d = require( '@stdlib/ndarray/base/atleast3d' ); import atleastnd = require( '@stdlib/ndarray/base/atleastnd' ); import binary = require( '@stdlib/ndarray/base/binary' ); import binaryInputCastingDataType = require( '@stdlib/ndarray/base/binary-input-casting-dtype' ); @@ -48,12 +52,15 @@ import bytesPerElement = require( '@stdlib/ndarray/base/bytes-per-element' ); import char2dtype = require( '@stdlib/ndarray/base/char2dtype' ); import clampIndex = require( '@stdlib/ndarray/base/clamp-index' ); import complementShape = require( '@stdlib/ndarray/base/complement-shape' ); +import consensusOrder = require( '@stdlib/ndarray/base/consensus-order' ); import copy = require( '@stdlib/ndarray/base/copy' ); import countFalsy = require( '@stdlib/ndarray/base/count-falsy' ); import countIf = require( '@stdlib/ndarray/base/count-if' ); import countTruthy = require( '@stdlib/ndarray/base/count-truthy' ); import ndarray = require( '@stdlib/ndarray/base/ctor' ); import data = require( '@stdlib/ndarray/base/data-buffer' ); +import descriptor = require( '@stdlib/ndarray/base/descriptor' ); +import diagonal = require( '@stdlib/ndarray/base/diagonal' ); import dtype = require( '@stdlib/ndarray/base/dtype' ); import dtypeAlignment = require( '@stdlib/ndarray/base/dtype-alignment' ); import dtypeChar = require( '@stdlib/ndarray/base/dtype-char' ); @@ -75,8 +82,11 @@ import emptyLike = require( '@stdlib/ndarray/base/empty-like' ); import every = require( '@stdlib/ndarray/base/every' ); import everyBy = require( '@stdlib/ndarray/base/every-by' ); import expandDimensions = require( '@stdlib/ndarray/base/expand-dimensions' ); +import falses = require( '@stdlib/ndarray/base/falses' ); +import falsesLike = require( '@stdlib/ndarray/base/falses-like' ); import fill = require( '@stdlib/ndarray/base/fill' ); import fillBy = require( '@stdlib/ndarray/base/fill-by' ); +import fillDiagonal = require( '@stdlib/ndarray/base/fill-diagonal' ); import find = require( '@stdlib/ndarray/base/find' ); import flag = require( '@stdlib/ndarray/base/flag' ); import flags = require( '@stdlib/ndarray/base/flags' ); @@ -89,6 +99,7 @@ import array2ndarray = require( '@stdlib/ndarray/base/from-array' ); import scalar2ndarray = require( '@stdlib/ndarray/base/from-scalar' ); import scalar2ndarrayLike = require( '@stdlib/ndarray/base/from-scalar-like' ); import full = require( '@stdlib/ndarray/base/full' ); +import fullBy = require( '@stdlib/ndarray/base/full-by' ); import includes = require( '@stdlib/ndarray/base/includes' ); import ind = require( '@stdlib/ndarray/base/ind' ); import ind2sub = require( '@stdlib/ndarray/base/ind2sub' ); @@ -105,6 +116,8 @@ import minUnsignedIntegerDataType = require( '@stdlib/ndarray/base/min-unsigned- import minViewBufferIndex = require( '@stdlib/ndarray/base/min-view-buffer-index' ); import minmaxViewBufferIndex = require( '@stdlib/ndarray/base/minmax-view-buffer-index' ); import nans = require( '@stdlib/ndarray/base/nans' ); +import nansLike = require( '@stdlib/ndarray/base/nans-like' ); +import ndarraylike2descriptor = require( '@stdlib/ndarray/base/ndarraylike2descriptor' ); import ndarraylike2ndarray = require( '@stdlib/ndarray/base/ndarraylike2ndarray' ); import ndarraylike2object = require( '@stdlib/ndarray/base/ndarraylike2object' ); import ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' ); @@ -119,6 +132,7 @@ import nullaryStrided1dDispatch = require( '@stdlib/ndarray/base/nullary-strided import nullaryStrided1dDispatchFactory = require( '@stdlib/ndarray/base/nullary-strided1d-dispatch-factory' ); import nullaryBlockSize = require( '@stdlib/ndarray/base/nullary-tiling-block-size' ); import nulls = require( '@stdlib/ndarray/base/nulls' ); +import nullsLike = require( '@stdlib/ndarray/base/nulls-like' ); import numel = require( '@stdlib/ndarray/base/numel' ); import numelDimension = require( '@stdlib/ndarray/base/numel-dimension' ); import offset = require( '@stdlib/ndarray/base/offset' ); @@ -126,6 +140,7 @@ import ones = require( '@stdlib/ndarray/base/ones' ); import onesLike = require( '@stdlib/ndarray/base/ones-like' ); import order = require( '@stdlib/ndarray/base/order' ); import outputDataType = require( '@stdlib/ndarray/base/output-dtype' ); +import outputOrder = require( '@stdlib/ndarray/base/output-order' ); import outputPolicyEnum2Str = require( '@stdlib/ndarray/base/output-policy-enum2str' ); import outputPolicyResolveEnum = require( '@stdlib/ndarray/base/output-policy-resolve-enum' ); import outputPolicyResolveStr = require( '@stdlib/ndarray/base/output-policy-resolve-str' ); @@ -137,9 +152,18 @@ import quaternaryLoopOrder = require( '@stdlib/ndarray/base/quaternary-loop-inte import quaternaryBlockSize = require( '@stdlib/ndarray/base/quaternary-tiling-block-size' ); import quinaryLoopOrder = require( '@stdlib/ndarray/base/quinary-loop-interchange-order' ); import quinaryBlockSize = require( '@stdlib/ndarray/base/quinary-tiling-block-size' ); +import reinterpretBoolean = require( '@stdlib/ndarray/base/reinterpret-boolean' ); +import reinterpretComplex = require( '@stdlib/ndarray/base/reinterpret-complex' ); +import reinterpretComplex64 = require( '@stdlib/ndarray/base/reinterpret-complex64' ); +import reinterpretComplex128 = require( '@stdlib/ndarray/base/reinterpret-complex128' ); import removeSingletonDimensions = require( '@stdlib/ndarray/base/remove-singleton-dimensions' ); import reverse = require( '@stdlib/ndarray/base/reverse' ); import reverseDimension = require( '@stdlib/ndarray/base/reverse-dimension' ); +import reverseDimensions = require( '@stdlib/ndarray/base/reverse-dimensions' ); +import rot90 = require( '@stdlib/ndarray/base/rot90' ); +import rot180 = require( '@stdlib/ndarray/base/rot180' ); +import rotl90 = require( '@stdlib/ndarray/base/rotl90' ); +import rotr90 = require( '@stdlib/ndarray/base/rotr90' ); import serializeMetaData = require( '@stdlib/ndarray/base/serialize-meta-data' ); import shape = require( '@stdlib/ndarray/base/shape' ); import shape2strides = require( '@stdlib/ndarray/base/shape2strides' ); @@ -164,6 +188,7 @@ import ternary = require( '@stdlib/ndarray/base/ternary' ); import ternaryLoopOrder = require( '@stdlib/ndarray/base/ternary-loop-interchange-order' ); import ternaryOutputDataType = require( '@stdlib/ndarray/base/ternary-output-dtype' ); import ternaryBlockSize = require( '@stdlib/ndarray/base/ternary-tiling-block-size' ); +import tile = require( '@stdlib/ndarray/base/tile' ); import blockSize = require( '@stdlib/ndarray/base/tiling-block-size' ); import ndarray2array = require( '@stdlib/ndarray/base/to-array' ); import toFlippedlr = require( '@stdlib/ndarray/base/to-flippedlr' ); @@ -171,9 +196,17 @@ import toFlippedud = require( '@stdlib/ndarray/base/to-flippedud' ); import toNormalizedIndices = require( '@stdlib/ndarray/base/to-normalized-indices' ); import toReversed = require( '@stdlib/ndarray/base/to-reversed' ); import toReversedDimension = require( '@stdlib/ndarray/base/to-reversed-dimension' ); +import toReversedDimensions = require( '@stdlib/ndarray/base/to-reversed-dimensions' ); +import toRot90 = require( '@stdlib/ndarray/base/to-rot90' ); +import toRot180 = require( '@stdlib/ndarray/base/to-rot180' ); +import toRotl90 = require( '@stdlib/ndarray/base/to-rotl90' ); +import toRotr90 = require( '@stdlib/ndarray/base/to-rotr90' ); import toTransposed = require( '@stdlib/ndarray/base/to-transposed' ); +import toUnflattened = require( '@stdlib/ndarray/base/to-unflattened' ); import toUniqueNormalizedIndices = require( '@stdlib/ndarray/base/to-unique-normalized-indices' ); import transpose = require( '@stdlib/ndarray/base/transpose' ); +import trues = require( '@stdlib/ndarray/base/trues' ); +import truesLike = require( '@stdlib/ndarray/base/trues-like' ); import unary = require( '@stdlib/ndarray/base/unary' ); import unaryAccumulate = require( '@stdlib/ndarray/base/unary-accumulate' ); import unaryAddonDispatch = require( '@stdlib/ndarray/base/unary-addon-dispatch' ); @@ -189,6 +222,7 @@ import unaryReduceSubarrayBy = require( '@stdlib/ndarray/base/unary-reduce-subar import unaryStrided1dDispatch = require( '@stdlib/ndarray/base/unary-strided1d-dispatch' ); import unaryStrided1dDispatchFactory = require( '@stdlib/ndarray/base/unary-strided1d-dispatch-factory' ); import unaryBlockSize = require( '@stdlib/ndarray/base/unary-tiling-block-size' ); +import unflatten = require( '@stdlib/ndarray/base/unflatten' ); import unflattenShape = require( '@stdlib/ndarray/base/unflatten-shape' ); import vind2bind = require( '@stdlib/ndarray/base/vind2bind' ); import wrapIndex = require( '@stdlib/ndarray/base/wrap-index' ); @@ -268,6 +302,25 @@ interface Namespace { */ anyBy: typeof anyBy; + /** + * Returns an array with a specified number of appended singleton dimensions. + * + * @param x - input array + * @param n - number of singleton dimensions to append + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.appendSingletonDimensions( x, 3, false ); + * // returns [ [ [ [ [ 1 ] ] ], [ [ [ 2 ] ] ] ], [ [ [ [ 3 ] ] ], [ [ [ 4 ] ] ] ] ] + */ + appendSingletonDimensions: typeof appendSingletonDimensions; + /** * Base ndarray assertion utilities. */ @@ -349,6 +402,69 @@ interface Namespace { */ assignScalar: typeof assignScalar; + /** + * Converts a list of values (scalars and/or ndarrays) to ndarrays having at least one dimension. + * + * @param arrays - array-like object containing a list of scalars and/or ndarrays + * @returns an array of ndarrays + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' ); + * + * var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] ); + * // returns [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] + * + * var y = scalar2ndarray( 3.14 ); + * // returns [ 3.14 ] + * + * var out = ns.atleast1d( [ x, y ] ); + * // returns [ , ] + */ + atleast1d: typeof atleast1d; + + /** + * Converts a list of values (scalars and/or ndarrays) to ndarrays having at least two dimensions. + * + * @param arrays - array-like object containing a list of scalars and/or ndarrays + * @returns an array of ndarrays + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' ); + * + * var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] ); + * // returns [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] + * + * var y = scalar2ndarray( 3.14 ); + * // returns [ 3.14 ] + * + * var out = ns.atleast2d( [ x, y ] ); + * // returns [ , ] + */ + atleast2d: typeof atleast2d; + + /** + * Converts a list of values (scalars and/or ndarrays) to ndarrays having at least three dimensions. + * + * @param arrays - array-like object containing a list of scalars and/or ndarrays + * @returns an array of ndarrays + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' ); + * + * var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] ); + * // returns [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] + * + * var y = scalar2ndarray( 3.14 ); + * // returns [ 3.14 ] + * + * var out = ns.atleast3d( [ x, y ] ); + * // returns [ , ] + */ + atleast3d: typeof atleast3d; + /** * Converts a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions. * @@ -1121,6 +1237,42 @@ interface Namespace { */ complementShape: typeof complementShape; + /** + * Resolves the most common underlying storage layout. + * + * ## Notes + * + * - In the event of a tie or when all input array strides are "disorganized" (i.e., neither row- nor column-major), the function returns the default layout. + * + * @param strides - list of array strides + * @returns storage layout + * + * @example + * var strides = [ [ 2, 1 ], [ 4, 1 ] ]; + * + * var order = ns.consensusOrder( strides ); + * // returns 'row-major' + * + * @example + * var strides = [ [ 1, 2 ], [ 1, 4 ] ]; + * + * var order = ns.consensusOrder( strides ); + * // returns 'column-major' + * + * @example + * var strides = [ [ 2, 1 ], [ 1, 4 ] ]; + * + * var order = ns.consensusOrder( strides ); + * // returns + * + * @example + * var strides = [ [ 1, 1 ], [ 1, 1 ] ]; + * + * var order = ns.consensusOrder( strides ); + * // returns + */ + consensusOrder: typeof consensusOrder; + /** * Copies an input ndarray to a new ndarray having the same shape and data type. * @@ -1301,6 +1453,56 @@ interface Namespace { */ data: typeof data; + /** + * Returns a plain object describing how to interpret a data buffer as an n-dimensional array. + * + * @param dtype - data type + * @param buffer - data buffer + * @param shape - array shape + * @param strides - array strides + * @param offset - index offset + * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) + * @returns ndarray descriptor + * + * @example + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var out = ns.descriptor( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns {...} + */ + descriptor: typeof descriptor; + + /** + * Returns a view of the diagonal of a matrix (or stack of matrices). + * + * ## Notes + * + * - The order of the dimension indices contained in `dims` matters. The first element specifies the row-like dimension. The second element specifies the column-like dimension. + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * - The diagonal offset `k` is interpreted as `column - row`. Accordingly, when `k = 0`, the function returns the main diagonal; when `k > 0`, the function returns the diagonal above the main diagonal; and when `k < 0`, the function returns the diagonal below the main diagonal. + * - The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa. + * - The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances. + * + * @param x - input array + * @param dims - dimension indices defining the plane from which to extract the diagonal + * @param k - diagonal offset + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns ndarray view + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ] ); + * // returns [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ] + * + * var y = ns.diagonal( x, [ 0, 1 ], 0, false ); + * // returns [ 1.0, 5.0, 9.0 ] + */ + diagonal: typeof diagonal; + /** * Returns the data type of a provided ndarray. * @@ -1693,6 +1895,58 @@ interface Namespace { */ expandDimensions: typeof expandDimensions; + /** + * Creates an ndarray filled with `false` values and having a specified shape and data type. + * + * @param dtype - underlying data type + * @param shape - array shape + * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) + * @returns `false`-filled array + * + * @example + * var getDType = require( '@stdlib/ndarray/dtype' ); + * + * var arr = ns.falses( 'generic', [ 2, 2 ], 'row-major' ); + * // returns [ [ false, false ], [ false, false ] ] + * + * var dt = String( getDType( arr ) ); + * // returns 'generic' + */ + falses: typeof falses; + + /** + * Creates an ndarray filled with `false` values and having the same shape and data type as a provided input ndarray. + * + * @param x - input array + * @returns filled ndarray + * + * @example + * var getShape = require( '@stdlib/ndarray/shape' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * var empty = require( '@stdlib/ndarray/empty' ); + * + * var x = empty( [ 2, 2 ], { + * 'dtype': 'bool' + * }); + * // returns + * + * var sh = getShape( x ); + * // returns [ 2, 2 ] + * + * var dt = String( getDType( x ) ); + * // returns 'bool' + * + * var y = ns.falsesLike( x ); + * // returns [ [ false, false ], [ false, false ] ] + * + * sh = getShape( y ); + * // returns [ 2, 2 ] + * + * dt = String( getDType( y ) ); + * // returns 'bool' + */ + falsesLike: typeof falsesLike; + /** * Fills an input ndarray with a specified value. * @@ -1786,6 +2040,36 @@ interface Namespace { */ fillBy: typeof fillBy; + /** + * Fills a specified diagonal of a matrix (or stack of matrices) with a scalar value. + * + * ## Notes + * + * - The order of the dimension indices contained in `dims` matters. The first element specifies the row-like dimension. The second element specifies the column-like dimension. + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * - The diagonal offset `k` is interpreted as `column - row`. Accordingly, when `k = 0`, the function fills the main diagonal; when `k > 0`, the function fills the diagonal above the main diagonal; and when `k < 0`, the function fills the diagonal below the main diagonal. + * - The function mutates the input ndarray in-place. + * + * @param x - input array + * @param value - scalar value + * @param dims - dimension indices defining the plane in which to fill the diagonal + * @param k - diagonal offset + * @returns input ndarray + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var x = zeros( [ 3, 3 ] ); + * // returns [ [ 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ] ] + * + * var out = ns.fillDiagonal( x, 1.0, [ 0, 1 ], 0 ); + * // returns [ [ 1.0, 0.0, 0.0 ], [ 0.0, 1.0, 0.0 ], [ 0.0, 0.0, 1.0 ] ] + * + * var bool = ( out === x ); + * // returns true + */ + fillDiagonal: typeof fillDiagonal; + /** * Returns the first element in an ndarray which passes a test implemented by a predicate function. * @@ -2061,27 +2345,36 @@ interface Namespace { /** * Returns a zero-dimensional ndarray containing a provided scalar value and having the same data type as a provided input ndarray. * + * ## Notes + * + * - If provided a number, the function returns a zero-dimensional ndarray containing a complex number whose real component equals the provided scalar value and whose imaginary component is zero. + * * @param x - input array * @param value - scalar value * @returns zero-dimensional ndarray * * @example + * var getShape = require( '@stdlib/ndarray/shape' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * var Complex128 = require( '@stdlib/complex/float64/ctor' ); * var zeros = require( '@stdlib/ndarray/base/zeros' ); * - * var x = zeros( 'float64', [ 2, 2 ], 'row-major' ); + * var x = zeros( 'complex128', [ 2, 2 ], 'row-major' ); * // returns * - * var y = ns.scalar2ndarrayLike( x, 1.0 ); + * var v = new Complex128( 1.0, 2.0 ); + * + * var y = ns.scalar2ndarrayLike( x, v ); * // returns * - * var sh = y.shape; + * var sh = getShape( y ); * // returns [] * - * var dt = y.dtype; - * // returns 'float64' + * var dt = String( getDType( y ) ); + * // returns 'complex128' * * var v = y.get(); - * // returns 1.0 + * // returns [ 1.0, 2.0 ] */ scalar2ndarrayLike: typeof scalar2ndarrayLike; @@ -2109,6 +2402,31 @@ interface Namespace { */ full: typeof full; + /** + * Returns an ndarray filled according to a callback function and having a specified shape and data type. + * + * @param dtype - underlying data type + * @param shape - array shape + * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) + * @param clbk - callback function + * @param thisArg - callback function execution context + * @returns output array + * + * @example + * var getDType = require( '@stdlib/ndarray/dtype' ); + * + * function clbk() { + * return 10.0; + * } + * + * var arr = ns.fullBy( 'float32', [ 2, 2 ], 'row-major', clbk ); + * // returns [ [ 10.0, 10.0 ], [ 10.0, 10.0 ] ] + * + * var dt = String( getDType( arr ) ); + * // returns 'float32' + */ + fullBy: typeof fullBy; + /** * Tests whether an ndarray contains a specified value. * @@ -2482,37 +2800,20 @@ interface Namespace { * @returns broadcasted array * * @example + * var getShape = require( '@stdlib/ndarray/shape' ); * var array = require( '@stdlib/ndarray/array' ); * * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); - * // returns + * // returns [ [ 1, 2 ], [ 3, 4 ] ] * - * var shx = x.shape; + * var shx = getShape( x ); * // returns [ 2, 2 ] * * var y = ns.maybeBroadcastArray( x, [ 3, 2, 2 ] ); - * // returns + * // returns [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ] ] * - * var shy = y.shape; + * var shy = getShape( y ); * // returns [ 3, 2, 2 ] - * - * var v = y.get( 0, 0, 0 ); - * // returns 1 - * - * v = y.get( 0, 0, 1 ); - * // returns 2 - * - * v = y.get( 1, 0, 0 ); - * // returns 1 - * - * v = y.get( 1, 1, 0 ); - * // returns 3 - * - * v = y.get( 2, 0, 0 ); - * // returns 1 - * - * v = y.get( 2, 1, 1 ); - * // returns 4 */ maybeBroadcastArray: typeof maybeBroadcastArray; @@ -2563,66 +2864,49 @@ interface Namespace { * @returns list of broadcasted arrays * * @example + * var getShape = require( '@stdlib/ndarray/shape' ); * var array = require( '@stdlib/ndarray/array' ); * var zeros = require( '@stdlib/ndarray/zeros' ); * - * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); - * // returns + * var x1 = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] * - * var shx = x.shape; + * var shx = getShape( x1 ); * // returns [ 2, 2 ] * * var y1 = zeros( [ 3, 2, 2 ] ); - * // returns + * // returns [ [ [ 0, 0 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 0, 0 ] ] ] * - * var shy = y1.shape; + * var shy = getShape( y1 ); * // returns [ 3, 2, 2 ] * - * var out = ns.maybeBroadcastArrays( [ x, y1 ] ); + * var out = ns.maybeBroadcastArrays( [ x1, y1 ] ); * // returns [ , ] * * var x2 = out[ 0 ]; - * // returns + * // returns [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 2 ], [ 3, 4 ] ] ] * * var y2 = out[ 1 ]; - * // returns + * // returns [ [ [ 0, 0 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 0, 0 ] ] ] * - * shx = x2.shape; + * shx = getShape( x2 ); * // returns [ 3, 2, 2 ] * - * shy = y2.shape; + * shy = getShape( y2 ); * // returns [ 3, 2, 2 ] + */ + maybeBroadcastArrays: typeof maybeBroadcastArrays; + + /** + * Defines non-enumerable read-only properties which expose ndarray function meta data. * - * var v = x2.get( 0, 0, 0 ); - * // returns 1 - * - * v = x2.get( 0, 0, 1 ); - * // returns 2 - * - * v = x2.get( 1, 0, 0 ); - * // returns 1 - * - * v = x2.get( 1, 1, 0 ); - * // returns 3 - * - * v = x2.get( 2, 0, 0 ); - * // returns 1 - * - * v = x2.get( 2, 1, 1 ); - * // returns 4 - */ - maybeBroadcastArrays: typeof maybeBroadcastArrays; - - /** - * Defines non-enumerable read-only properties which expose ndarray function meta data. - * - * @param meta - function meta data - * @param meta.nargs - total number of arguments - * @param meta.nin - total number of input arrays - * @param meta.nout - total number of output arrays - * @param dtypes - list of ndarray data types - * @param obj - object on which to define properties - * @returns object on which properties were defined + * @param meta - function meta data + * @param meta.nargs - total number of arguments + * @param meta.nin - total number of input arrays + * @param meta.nout - total number of output arrays + * @param dtypes - list of ndarray data types + * @param obj - object on which to define properties + * @returns object on which properties were defined * * @example * // Define ndarray function meta data: @@ -2782,6 +3066,51 @@ interface Namespace { */ nans: typeof nans; + /** + * Creates a NaN-filled array having the same shape and data type as a provided input ndarray. + * + * @param x - input array + * @returns NaN-filled array + * + * @example + * var getShape = require( '@stdlib/ndarray/shape' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * var ones = require( '@stdlib/ndarray/base/ones' ); + * + * var x = ones( 'float64', [ 2, 2 ], 'row-major' ); + * // returns [ [ 1.0, 1.0 ], [ 1.0, 1.0 ] ] + * + * var sh = getShape( x ); + * // returns [ 2, 2 ] + * + * var dt = String( getDType( x ) ); + * // returns 'float64' + * + * var y = ns.nansLike( x ); + * // returns [ [ NaN, NaN ], [ NaN, NaN ] ] + * + * sh = getShape( y ); + * // returns [ 2, 2 ] + * + * dt = String( getDType( y ) ); + * // returns 'float64' + */ + nansLike: typeof nansLike; + + /** + * Converts an ndarray-like object to an ndarray descriptor. + * + * @param x - input ndarray + * @returns ndarray descriptor + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var out = ns.ndarraylike2descriptor( zeros( [ 2, 2 ] ) ); + * // returns {...} + */ + ndarraylike2descriptor: typeof ndarraylike2descriptor; + /** * Converts an ndarray-like object to an ndarray. * @@ -3100,7 +3429,6 @@ interface Namespace { * var base = require( '@stdlib/blas/ext/base/ndarray/gsorthp' ); * var dtypes = require( '@stdlib/ndarray/dtypes' ); * var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); * var ndarray = require( '@stdlib/ndarray/base/ctor' ); * * var idt = dtypes( 'real_and_generic' ); @@ -3119,10 +3447,7 @@ interface Namespace { * }); * * var out = sorthp( x, order ); - * // returns - * - * var arr = ndarray2array( out ); - * // returns [ -3.0, -1.0, 2.0 ] + * // returns [ -3.0, -1.0, 2.0 ] * * var bool = ( out === x ); * // returns true @@ -3160,6 +3485,39 @@ interface Namespace { */ nulls: typeof nulls; + /** + * Creates a null-filled array having the same shape and data type as a provided input ndarray. + * + * @param x - input array + * @returns null-filled array + * + * @example + * var getShape = require( '@stdlib/ndarray/shape' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * var empty = require( '@stdlib/ndarray/empty' ); + * + * var x = empty( [ 2, 2 ], { + * 'dtype': 'generic' + * }); + * // returns + * + * var sh = getShape( x ); + * // returns [ 2, 2 ] + * + * var dt = String( getDType( x ) ); + * // returns 'generic' + * + * var y = ns.nullsLike( x ); + * // returns [ [ null, null ], [ null, null ] ] + * + * sh = getShape( y ); + * // returns [ 2, 2 ] + * + * dt = String( getDType( y ) ); + * // returns 'generic' + */ + nullsLike: typeof nullsLike; + /** * Returns the number of elements in an array. * @@ -3290,6 +3648,27 @@ interface Namespace { */ outputDataType: typeof outputDataType; + /** + * Resolves the order (i.e. memory layout) of an output ndarray according to a list of input ndarrays. + * + * ## Notes + * + * - When the layout differs among provided ndarrays, the function returns the default layout. + * + * @param arrays - list of input ndarrays + * @returns storage layout + * + * @example + * var zeros = require( '@stdlib/ndarray/zeros' ); + * + * var x = zeros( [ 2, 2 ] ); + * var y = zeros( [ 2, 2 ] ); + * + * var order = ns.outputOrder( [ x, y ] ); + * // returns + */ + outputOrder: typeof outputOrder; + /** * Returns the policy string associated with an output ndarray data type policy enumeration constant. * @@ -3594,6 +3973,99 @@ interface Namespace { */ quinaryBlockSize: typeof quinaryBlockSize; + /** + * Reinterprets a boolean ndarray as an unsigned 8-bit integer ndarray. + * + * ## Notes + * + * - The returned ndarray is a view on the input ndarray data buffer. + * - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray 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 reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead. + * + * @param x - input ndarray + * @returns unsigned 8-bit integer ndarray view + * + * @example + * var zeros = require( '@stdlib/ndarray/base/zeros' ); + * + * var x = zeros( 'bool', [ 2, 2 ], 'row-major' ); + * // returns [ [ false, false ], [ false, false ] ] + * + * var out = ns.reinterpretBoolean( x ); + * // returns [ [ 0, 0 ], [ 0, 0 ] ] + */ + reinterpretBoolean: typeof reinterpretBoolean; + + /** + * Reinterprets a single-precision complex floating-point ndarray as a real-valued single-precision floating-point ndarray containing interleaved real and imaginary components. + * + * ## Notes + * + * - The returned ndarray is a view on the input ndarray data buffer. + * - The returned ndarray has an additional trailing dimension of size two whose elements correspond to the real and imaginary components, respectively, of each complex-valued element in the input ndarray. + * - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray 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 reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead. + * + * @param x - input ndarray + * @returns single-precision floating-point ndarray view + * + * @example + * var zeroTo = require( '@stdlib/blas/ext/zero-to' ); + * + * var x = zeroTo( [ 2, 2 ], { + * 'dtype': 'complex64' + * }); + * // returns [ [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ] ] + * + * var out = ns.reinterpretComplex( x ); + * // returns [ [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ] ] + */ + reinterpretComplex: typeof reinterpretComplex; + + /** + * Reinterprets a single-precision complex floating-point ndarray as a real-valued single-precision floating-point ndarray containing interleaved real and imaginary components. + * + * ## Notes + * + * - The returned ndarray is a view on the input ndarray data buffer. + * - The returned ndarray has an additional trailing dimension of size two whose elements correspond to the real and imaginary components, respectively, of each complex-valued element in the input ndarray. + * - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray 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 reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead. + * + * @param x - input ndarray + * @returns single-precision floating-point ndarray view + * + * @example + * var ones = require( '@stdlib/ndarray/base/ones' ); + * + * var x = ones( 'complex64', [ 2, 2 ], 'row-major' ); + * // returns [ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ] + * + * var out = ns.reinterpretComplex64( x ); + * // returns [ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ] + */ + reinterpretComplex64: typeof reinterpretComplex64; + + /** + * Reinterprets a double-precision complex floating-point ndarray as a real-valued double-precision floating-point ndarray containing interleaved real and imaginary components. + * + * ## Notes + * + * - The returned ndarray is a view on the input ndarray data buffer. + * - The returned ndarray has an additional trailing dimension of size two whose elements correspond to the real and imaginary components, respectively, of each complex-valued element in the input ndarray. + * - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray 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 reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead. + * + * @param x - input ndarray + * @returns double-precision floating-point ndarray view + * + * @example + * var ones = require( '@stdlib/ndarray/base/ones' ); + * + * var x = ones( 'complex128', [ 2, 2 ], 'row-major' ); + * // returns [ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ] + * + * var out = ns.reinterpretComplex128( x ); + * // returns [ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ] + */ + reinterpretComplex128: typeof reinterpretComplex128; + /** * Returns an ndarray without singleton dimensions. * @@ -3627,8 +4099,8 @@ interface Namespace { * * @example * var typedarray = require( '@stdlib/array/typed' ); + * var getShape = require( '@stdlib/ndarray/shape' ); * var ndarray = require( '@stdlib/ndarray/ctor' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); * * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' ); * var shape = [ 3, 2 ]; @@ -3636,22 +4108,16 @@ interface Namespace { * var offset = 0; * * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); - * // returns + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] * - * var sh = x.shape; + * var sh = getShape( x ); * // returns [ 3, 2 ] * - * var arr = ndarray2array( x ); - * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] - * * var y = ns.reverse( x, false ); - * // returns + * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] * - * sh = y.shape; + * sh = getShape( y ); * // returns [ 3, 2 ] - * - * arr = ndarray2array( y ); - * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] */ reverse: typeof reverse; @@ -3666,33 +4132,133 @@ interface Namespace { * @example * var typedarray = require( '@stdlib/array/typed' ); * var ndarray = require( '@stdlib/ndarray/ctor' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); + * var getShape = require( '@stdlib/ndarray/shape' ); * - * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' ); * var shape = [ 3, 2 ]; * var strides = [ 2, 1 ]; * var offset = 0; * - * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); - * // returns + * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] * - * var sh = x.shape; + * var sh = getShape( x ); * // returns [ 3, 2 ] * - * var arr = ndarray2array( x ); - * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] - * * var y = ns.reverseDimension( x, 0, false ); - * // returns + * // returns [ [ 5.0, 6.0 ], [ 3.0, 4.0 ], [ 1.0, 2.0 ] ] * - * sh = y.shape; + * sh = getShape( y ); * // returns [ 3, 2 ] - * - * arr = ndarray2array( y ); - * // returns [ [ 5, 6 ], [ 3, 4 ], [ 1, 2 ] ] */ reverseDimension: typeof reverseDimension; + /** + * Returns a view of an input ndarray in which the order of elements along specified dimensions is reversed. + * + * @param x - input array + * @param dims - indices of dimensions to reverse + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] ); + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] + * + * var y = ns.reverseDimensions( x, [ 0, 1 ], false ); + * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] + */ + reverseDimensions: typeof reverseDimensions; + + /** + * Rotates an ndarray 90 degrees in a specified plane. + * + * ## Notes + * + * - If `k > 0`, the function rotates the plane from the first specified dimension toward the second specified dimension. This means that, for a two-dimensional ndarray and `dims = [0, 1]`, the function rotates the plane counterclockwise. + * - If `k < 0`, the function rotates the plane from the second specified dimension toward the first specified dimension. This means that, for a two-dimensional ndarray and `dims = [0, 1]`, the function rotates the plane clockwise. + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * + * @param x - input array + * @param dims - dimension indices defining the plane of rotation + * @param k - number of times to rotate by 90 degrees + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns ndarray view + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.rot90( x, [ 0, 1 ], 1, false ); + * // returns [ [ 2, 4 ], [ 1, 3 ] ] + */ + rot90: typeof rot90; + + /** + * Rotates an ndarray 180 degrees in a specified plane. + * + * ## Notes + * + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * + * @param x - input array + * @param dims - dimension indices defining the plane of rotation + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns ndarray view + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.rot180( x, [ 0, 1 ], false ); + * // returns [ [ 4, 3 ], [ 2, 1 ] ] + */ + rot180: typeof rot180; + + /** + * Rotates a matrix (or a stack of matrices) 90 degrees counterclockwise. + * + * @param x - input array + * @param k - number of times to rotate by 90 degrees + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns ndarray view + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.rotl90( x, 1, false ); + * // returns [ [ 2, 4 ], [ 1, 3 ] ] + */ + rotl90: typeof rotl90; + + /** + * Rotates a matrix (or a stack of matrices) 90 degrees clockwise. + * + * @param x - input array + * @param k - number of times to rotate by 90 degrees + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.rotr90( x, 1, false ); + * // returns [ [ 3, 1 ], [ 4, 2 ] ] + */ + rotr90: typeof rotr90; + /** * Serializes ndarray meta data. * @@ -4254,18 +4820,19 @@ interface Namespace { * @returns output array * * @example + * var getShape = require( '@stdlib/ndarray/shape' ); * var array = require( '@stdlib/ndarray/array' ); * * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); * // returns * - * var shx = x.shape; + * var shx = getShape( x ); * // returns [ 2, 2 ] * * var y = ns.spreadDimensions( 5, x, [ 1, 3 ], false ); * // returns * - * var shy = y.shape; + * var shy = getShape( y ); * // returns [ 1, 2, 1, 2, 1 ] * * var v = y.get( 0, 0, 0, 0, 0 ); @@ -4598,6 +5165,29 @@ interface Namespace { */ ternaryBlockSize: typeof ternaryBlockSize; + /** + * Returns an ndarray created by repeating the elements of an input ndarray a specified number of times along each dimension. + * + * ## Notes + * + * - The number of repetitions must have at least as many elements as the number of input dimensions. When the number of repetitions exceeds the number of input dimensions, the input array is treated as if singleton dimensions were prepended. + * - The function always copies data to a new ndarray. + * + * @param x - input array + * @param reps - number of repetitions along each dimension + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.tile( x, [ 2, 2 ] ); + * // returns [ [ 1, 2, 1, 2 ], [ 3, 4, 3, 4 ], [ 1, 2, 1, 2 ], [ 3, 4, 3, 4 ] ] + */ + tile: typeof tile; + /** * Returns a loop block size for multi-dimensional array tiled loops. * @@ -4640,8 +5230,8 @@ interface Namespace { * * @example * var typedarray = require( '@stdlib/array/typed' ); + * var getShape = require( '@stdlib/ndarray/shape' ); * var ndarray = require( '@stdlib/ndarray/ctor' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); * * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' ); * var shape = [ 3, 2 ]; @@ -4649,22 +5239,16 @@ interface Namespace { * var offset = 0; * * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); - * // returns + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] * - * var sh = x.shape; + * var sh = getShape( x ); * // returns [ 3, 2 ] * - * var arr = ndarray2array( x ); - * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] - * * var y = ns.toFlippedlr( x ); - * // returns + * // returns [ [ 2.0, 1.0 ], [ 4.0, 3.0 ], [ 6.0, 5.0 ] ] * - * sh = y.shape; + * sh = getShape( y ); * // returns [ 3, 2 ] - * - * arr = ndarray2array( y ); - * // returns [ [ 2.0, 1.0 ], [ 4.0, 3.0 ], [ 6.0, 5.0 ] ] */ toFlippedlr: typeof toFlippedlr; @@ -4676,8 +5260,8 @@ interface Namespace { * * @example * var typedarray = require( '@stdlib/array/typed' ); + * var getShape = require( '@stdlib/ndarray/shape' ); * var ndarray = require( '@stdlib/ndarray/ctor' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); * * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' ); * var shape = [ 3, 2 ]; @@ -4685,22 +5269,16 @@ interface Namespace { * var offset = 0; * * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); - * // returns + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] * - * var sh = x.shape; + * var sh = getShape( x ); * // returns [ 3, 2 ] * - * var arr = ndarray2array( x ); - * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] - * * var y = ns.toFlippedud( x ); - * // returns + * // returns [ [ 5.0, 6.0 ], [ 3.0, 4.0 ], [ 1.0, 2.0 ] ] * - * sh = y.shape; + * sh = getShape( y ); * // returns [ 3, 2 ] - * - * arr = ndarray2array( y ); - * // returns [ [ 5.0, 6.0 ], [ 3.0, 4.0 ], [ 1.0, 2.0 ] ] */ toFlippedud: typeof toFlippedud; @@ -4732,8 +5310,8 @@ interface Namespace { * * @example * var typedarray = require( '@stdlib/array/typed' ); + * var getShape = require( '@stdlib/ndarray/shape' ); * var ndarray = require( '@stdlib/ndarray/ctor' ); - * var ndarray2array = require( '@stdlib/ndarray/to-array' ); * * var buffer = typedarray( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ], 'float64' ); * var shape = [ 3, 2 ]; @@ -4741,22 +5319,16 @@ interface Namespace { * var offset = 0; * * var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); - * // returns + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] * - * var sh = x.shape; + * var sh = getShape( x ); * // returns [ 3, 2 ] * - * var arr = ndarray2array( x ); - * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] - * * var y = ns.toReversed( x ); - * // returns + * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] * - * sh = y.shape; + * sh = getShape( y ); * // returns [ 3, 2 ] - * - * arr = ndarray2array( y ); - * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] */ toReversed: typeof toReversed; @@ -4797,6 +5369,107 @@ interface Namespace { */ toReversedDimension: typeof toReversedDimension; + /** + * Returns a new ndarray where the order of elements of an input ndarray along specified dimensions is reversed. + * + * @param x - input array + * @param dims - indices of dimensions to reverse + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] ); + * // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] + * + * var y = ns.toReversedDimensions( x, [ 0, 1 ] ); + * // returns [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] + */ + toReversedDimensions: typeof toReversedDimensions; + + /** + * Returns a new ndarray where an ndarray is rotated 90 degrees in a specified plane. + * + * ## Notes + * + * - If `k > 0`, the function rotates the plane from the first specified dimension toward the second specified dimension. This means that, for a two-dimensional ndarray and `dims = [0, 1]`, the function rotates the plane counterclockwise. + * - If `k < 0`, the function rotates the plane from the second specified dimension toward the first specified dimension. This means that, for a two-dimensional ndarray and `dims = [0, 1]`, the function rotates the plane clockwise. + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * + * @param x - input array + * @param dims - dimension indices defining the plane of rotation + * @param k - number of times to rotate by 90 degrees + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.toRot90( x, [ 0, 1 ], 1 ); + * // returns [ [ 2, 4 ], [ 1, 3 ] ] + */ + toRot90: typeof toRot90; + + /** + * Returns a new ndarray where an ndarray is rotated 180 degrees in a specified plane. + * + * ## Notes + * + * - Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. + * + * @param x - input array + * @param dims - dimension indices defining the plane of rotation + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.toRot180( x, [ 0, 1 ] ); + * // returns [ [ 4, 3 ], [ 2, 1 ] ] + */ + toRot180: typeof toRot180; + + /** + * Returns a new ndarray where a matrix (or a stack of matrices) is rotated 90 degrees counterclockwise. + * + * @param x - input array + * @param k - number of times to rotate by 90 degrees + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.toRotl90( x, 1 ); + * // returns [ [ 2, 4 ], [ 1, 3 ] ] + */ + toRotl90: typeof toRotl90; + + /** + * Returns a new ndarray where a matrix (or a stack of matrices) is rotated 90 degrees clockwise. + * + * @param x - input array + * @param k - number of times to rotate by 90 degrees + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + * + * var y = ns.toRotr90( x, 1 ); + * // returns [ [ 3, 1 ], [ 4, 2 ] ] + */ + toRotr90: typeof toRotr90; + /** * Returns a new ndarray containing the elements of an input ndarray but whose last two dimensions are transposed. * @@ -4814,6 +5487,25 @@ interface Namespace { */ toTransposed: typeof toTransposed; + /** + * Returns a new ndarray in which a specified dimension of an input ndarray is expanded over multiple dimensions. + * + * @param x - input array + * @param dim - dimension to be unflattened + * @param sizes - new shape of the unflattened dimension + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + * // returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] + * + * var y = ns.toUnflattened( x, 0, [ 2, 3 ] ); + * // returns [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ] ] + */ + toUnflattened: typeof toUnflattened; + /** * Returns a list of unique indices after normalizing to the interval `[0,max]`. * @@ -4858,6 +5550,58 @@ interface Namespace { */ transpose: typeof transpose; + /** + * Creates an ndarray filled with `true` values and having a specified shape and data type. + * + * @param dtype - underlying data type + * @param shape - array shape + * @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) + * @returns `true`-filled array + * + * @example + * var getDType = require( '@stdlib/ndarray/dtype' ); + * + * var arr = ns.trues( 'generic', [ 2, 2 ], 'row-major' ); + * // returns [ [ true, true ], [ true, true ] ] + * + * var dt = String( getDType( arr ) ); + * // returns 'generic' + */ + trues: typeof trues; + + /** + * Creates an ndarray filled with `true` values and having the same shape and data type as a provided input ndarray. + * + * @param x - input array + * @returns filled ndarray + * + * @example + * var getShape = require( '@stdlib/ndarray/shape' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * var empty = require( '@stdlib/ndarray/empty' ); + * + * var x = empty( [ 2, 2 ], { + * 'dtype': 'bool' + * }); + * // returns + * + * var sh = getShape( x ); + * // returns [ 2, 2 ] + * + * var dt = String( getDType( x ) ); + * // returns 'bool' + * + * var y = ns.truesLike( x ); + * // returns [ [ true, true ], [ true, true ] ] + * + * sh = getShape( y ); + * // returns [ 2, 2 ] + * + * dt = String( getDType( y ) ); + * // returns 'bool' + */ + truesLike: typeof truesLike; + /** * Applies a unary callback to elements in an ndarray and assigns results to elements in an ndarray. * @@ -5407,6 +6151,26 @@ interface Namespace { */ unaryBlockSize: typeof unaryBlockSize; + /** + * Returns a view of an input ndarray in which a specified dimension is expanded over multiple dimensions. + * + * @param x - input array + * @param dim - dimension to be unflattened + * @param sizes - new shape of the unflattened dimension + * @param writable - boolean indicating whether the returned ndarray should be writable + * @returns output array + * + * @example + * var array = require( '@stdlib/ndarray/array' ); + * + * var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + * // returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] + * + * var out = ns.unflatten( x, 0, [ 2, 3 ], false ); + * // returns [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ] ] + */ + unflatten: typeof unflatten; + /** * Expands a dimension over multiple dimensions. *