diff --git a/base/assert/docs/types/index.d.ts b/base/assert/docs/types/index.d.ts index 652de8f3..5e266a40 100644 --- a/base/assert/docs/types/index.d.ts +++ b/base/assert/docs/types/index.d.ts @@ -33,6 +33,7 @@ import isDataType = require( './../../../../base/assert/is-data-type' ); import isFloatingPointDataType = require( './../../../../base/assert/is-floating-point-data-type' ); import isIndexMode = require( './../../../../base/assert/is-index-mode' ); import isIntegerDataType = require( './../../../../base/assert/is-integer-data-type' ); +import isMostlySafeDataTypeCast = require( './../../../../base/assert/is-mostly-safe-data-type-cast' ); import isNumericDataType = require( './../../../../base/assert/is-numeric-data-type' ); import isOrder = require( './../../../../base/assert/is-order' ); import isReadOnly = require( './../../../../base/assert/is-read-only' ); @@ -131,6 +132,9 @@ interface Namespace { * bool = ns.isCastingMode( 'safe' ); * // returns true * + * bool = ns.isCastingMode( 'mostly-safe' ); + * // returns true + * * bool = ns.isCastingMode( 'same-kind' ); * // returns true * @@ -432,6 +436,22 @@ interface Namespace { */ isIntegerDataType: typeof isIntegerDataType; + /** + * Returns a boolean indicating if a provided ndarray data type can be safely cast or, for floating-point data types, downcast to another ndarray data type. + * + * @param from - ndarray data type + * @param to - ndarray data type + * @returns boolean indicating if a data type can be cast to another data type + * + * @example + * var bool = ns.isMostlySafeDataTypeCast( 'float32', 'float64' ); + * // returns true + * + * bool = ns.isMostlySafeDataTypeCast( 'float64', 'int32' ); + * // returns false + */ + isMostlySafeDataTypeCast: typeof isMostlySafeDataTypeCast; + /** * Tests whether an input value is a supported ndarray numeric data type. * diff --git a/base/docs/types/index.d.ts b/base/docs/types/index.d.ts index 22739b89..dcee7db4 100644 --- a/base/docs/types/index.d.ts +++ b/base/docs/types/index.d.ts @@ -22,6 +22,7 @@ /* tslint:disable:max-file-line-count */ import assert = require( './../../../base/assert' ); +import assign = require( './../../../base/assign' ); import binaryLoopOrder = require( './../../../base/binary-loop-interchange-order' ); import binaryBlockSize = require( './../../../base/binary-tiling-block-size' ); import bind2vind = require( './../../../base/bind2vind' ); @@ -36,6 +37,8 @@ import bytesPerElement = require( './../../../base/bytes-per-element' ); import char2dtype = require( './../../../base/char2dtype' ); import clampIndex = require( './../../../base/clamp-index' ); import ndarray = require( './../../../base/ctor' ); +import data = require( './../../../base/data-buffer' ); +import dtype = require( './../../../base/dtype' ); import dtypeChar = require( './../../../base/dtype-char' ); import dtypeDesc = require( './../../../base/dtype-desc' ); import dtypeEnum2Str = require( './../../../base/dtype-enum2str' ); @@ -47,6 +50,8 @@ import dtypes2signatures = require( './../../../base/dtypes2signatures' ); import empty = require( './../../../base/empty' ); import emptyLike = require( './../../../base/empty-like' ); import expandDimensions = require( './../../../base/expand-dimensions' ); +import fliplr = require( './../../../base/fliplr' ); +import flipud = require( './../../../base/flipud' ); import scalar2ndarray = require( './../../../base/from-scalar' ); import ind = require( './../../../base/ind' ); import ind2sub = require( './../../../base/ind2sub' ); @@ -57,20 +62,36 @@ import metaDataProps = require( './../../../base/meta-data-props' ); import minViewBufferIndex = require( './../../../base/min-view-buffer-index' ); import minmaxViewBufferIndex = require( './../../../base/minmax-view-buffer-index' ); import ndarraylike2object = require( './../../../base/ndarraylike2object' ); +import ndims = require( './../../../base/ndims' ); +import nextCartesianIndex = require( './../../../base/next-cartesian-index' ); import nonsingletonDimensions = require( './../../../base/nonsingleton-dimensions' ); +import normalizeIndex = require( './../../../base/normalize-index' ); import nullary = require( './../../../base/nullary' ); import nullaryLoopOrder = require( './../../../base/nullary-loop-interchange-order' ); import nullaryBlockSize = require( './../../../base/nullary-tiling-block-size' ); import numel = require( './../../../base/numel' ); +import offset = require( './../../../base/offset' ); +import order = require( './../../../base/order' ); import outputPolicyEnum2Str = require( './../../../base/output-policy-enum2str' ); import outputPolicyResolveEnum = require( './../../../base/output-policy-resolve-enum' ); import outputPolicyResolveStr = require( './../../../base/output-policy-resolve-str' ); import outputPolicyStr2Enum = require( './../../../base/output-policy-str2enum' ); import prependSingletonDimensions = require( './../../../base/prepend-singleton-dimensions' ); import removeSingletonDimensions = require( './../../../base/remove-singleton-dimensions' ); +import reverse = require( './../../../base/reverse' ); +import reverseDimension = require( './../../../base/reverse-dimension' ); import serializeMetaData = require( './../../../base/serialize-meta-data' ); +import shape = require( './../../../base/shape' ); import shape2strides = require( './../../../base/shape2strides' ); import singletonDimensions = require( './../../../base/singleton-dimensions' ); +import slice = require( './../../../base/slice' ); +import sliceAssign = require( './../../../base/slice-assign' ); +import sliceDimension = require( './../../../base/slice-dimension' ); +import sliceDimensionFrom = require( './../../../base/slice-dimension-from' ); +import sliceDimensionTo = require( './../../../base/slice-dimension-to' ); +import sliceFrom = require( './../../../base/slice-from' ); +import sliceTo = require( './../../../base/slice-to' ); +import strides = require( './../../../base/strides' ); import strides2offset = require( './../../../base/strides2offset' ); import strides2order = require( './../../../base/strides2order' ); import sub2ind = require( './../../../base/sub2ind' ); @@ -95,6 +116,44 @@ interface Namespace { */ assert: typeof assert; + /** + * Assigns elements in an ndarray to elements in an ndarray. + * + * @param arrays - array-like object containing one input ndarray and one output ndarray + * @throws arrays must have the same number of dimensions + * @throws arrays must have the same shape + * + * @example + * var Float64Array = require( `@stdlib/array/float64` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * + * // Create data buffers: + * var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); + * var ybuf = new Float64Array( 6 ); + * + * // Define the shape of the input and output arrays: + * var shape = [ 3, 1, 2 ]; + * + * // Define the array strides: + * var sx = [ 4, 4, 1 ]; + * var sy = [ 2, 2, 1 ]; + * + * // Define the index offsets: + * var ox = 1; + * var oy = 0; + * + * // Create the input and output ndarrays: + * var x = ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' ); + * var y = ndarray( 'float64', ybuf, shape, sy, oy, 'row-major' ); + * + * // Copy elements: + * ns.assign( [ x, y ] ); + * + * console.log( y.data ); + * // => [ 2.0, 3.0, 6.0, 7.0, 10.0, 11.0 ] + */ + assign: typeof assign; + /** * Reorders ndarray dimensions and associated strides for loop interchange. * @@ -546,6 +605,42 @@ interface Namespace { */ ndarray: typeof ndarray; + /** + * Returns the underlying data buffer of a provided ndarray. + * + * @param x - input ndarray + * @returns underlying data buffer + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'dtype': 'float64' + * }); + * + * var out = ns.data( x ); + * // returns + */ + data: typeof data; + + /** + * Returns the data type of a provided ndarray. + * + * @param x - input ndarray + * @returns data type + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'ns.dtype': 'float64' + * }); + * + * var dt = ns.dtype( x ); + * // returns 'float64' + */ + dtype: typeof dtype; + /** * Returns an object mapping data type strings to single letter character abbreviations. * @@ -759,6 +854,80 @@ interface Namespace { */ expandDimensions: typeof expandDimensions; + /** + * Returns a view of an input ndarray in which the order of elements along the last dimension is reversed. + * + * @param x - input array + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var typedarray = require( `@stdlib/array/typed` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.fliplr( x, false ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 2, 1 ], [ 4, 3 ], [ 6, 5 ] ] + */ + fliplr: typeof fliplr; + + /** + * Returns a view of an input ndarray in which the order of elements along the second-to-last dimension is reversed. + * + * @param x - input array + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var typedarray = require( `@stdlib/array/typed` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.flipud( x, false ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 5, 6 ], [ 3, 4 ], [ 1, 2 ] ] + */ + flipud: typeof flipud; + /** * Returns a zero-dimensional ndarray containing a provided scalar value. * @@ -1183,6 +1352,77 @@ interface Namespace { */ ndarraylike2object: typeof ndarraylike2object; + /** + * Returns the number of ndarray dimensions. + * + * @param x - input ndarray + * @returns number of dimensions + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var n = ns.ndims( zeros( [ 3, 3, 3 ] ) ); + * // returns 3 + */ + ndims: typeof ndims; + + /** + * Returns the next Cartesian index (i.e., set of subscripts/dimension indices). + * + * ## Notes + * + * - The function does not check whether the current index is the "last" index. Instead, if the function is provided dimension indices corresponding to the last element, the function will cycle back to the "first" index. + * - If provided an empty shape (i.e., a shape corresponding to a zero-dimensional ndarray) or a dimension index `dim` which is out-of-bounds, the function returns `null`. + * + * @param shape - array shape + * @param order - iteration order + * @param idx - current dimension indices + * @param dim - index of the dimension from which to start incrementing (inclusive) + * @returns updated dimension indices + * + * @example + * var shape = [ 12 ]; + * var idx = ns.nextCartesianIndex( shape, 'row-major', [ 2 ], 0 ); + * // returns [ 3 ] + * + * @example + * var shape = [ 2, 2, 2 ]; + * + * var idx = ns.nextCartesianIndex( shape, 'row-major', [ 0, 0, 1 ], -1 ); + * // returns [ 0, 1, 0 ] + * + * idx = ns.nextCartesianIndex( shape, 'row-major', idx, -1 ); + * // returns [ 0, 1, 1 ] + * + * idx = ns.nextCartesianIndex( shape, 'row-major', idx, -1 ); + * // returns [ 1, 0, 0 ] + * + * idx = ns.nextCartesianIndex( shape, 'row-major', idx, -1 ); + * // returns [ 1, 0, 1 ] + * + * idx = ns.nextCartesianIndex( shape, 'row-major', idx, -1 ); + * // returns [ 1, 1, 0 ] + * + * idx = ns.nextCartesianIndex( shape, 'row-major', idx, -1 ); + * // returns [ 1, 1, 1 ] + * + * @example + * var shape = []; + * var idx = ns.nextCartesianIndex( shape, 'row-major', [], 0 ); + * // returns null + * + * @example + * var shape = [ 12 ]; + * var idx = ns.nextCartesianIndex( shape, 'row-major', [ 2 ], -10 ); + * // returns null + * + * @example + * var shape = [ 12 ]; + * var idx = ns.nextCartesianIndex( shape, 'column-major', [ 2 ], 10 ); + * // returns null + */ + nextCartesianIndex: typeof nextCartesianIndex; + /** * Returns the number of non-singleton dimensions. * @@ -1203,6 +1443,29 @@ interface Namespace { */ nonsingletonDimensions: typeof nonsingletonDimensions; + /** + * Normalizes an index to the interval `[0,max]`. + * + * ## Notes + * + * - If provided an out-of-bounds index, the function returns `-1`. + * + * @param idx - index + * @param max - maximum index + * @returns index + * + * @example + * var idx = ns.normalizeIndex( -2, 10 ); + * // returns 9 + * + * idx = ns.normalizeIndex( 15, 10 ); + * // returns -1 + * + * idx = ns.normalizeIndex( 5, 10 ); + * // returns 5 + */ + normalizeIndex: typeof normalizeIndex; + /** * Applies a nullary callback and assigns results to elements in an output ndarray. * @@ -1298,6 +1561,42 @@ interface Namespace { */ numel: typeof numel; + /** + * Returns the index offset specifying the underlying buffer index of the first iterated ndarray element. + * + * @param x - input ndarray + * @returns index offset + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var n = ns.offset( zeros( [ 3, 3, 3 ] ) ); + * // returns 0 + */ + offset: typeof offset; + + /** + * Returns the layout order of a provided ndarray. + * + * ## Notes + * + * - If unable to resolve a layout order, the function returns `null`. + * + * @param x - input ndarray + * @returns layout order (or null) + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'ns.order': 'row-major' + * }); + * + * var o = ns.order( x ); + * // returns 'row-major' + */ + order: typeof order; + /** * Returns the policy string associated with an output ndarray data type policy enumeration constant. * @@ -1439,6 +1738,81 @@ interface Namespace { */ removeSingletonDimensions: typeof removeSingletonDimensions; + /** + * Returns a view of an input ndarray in which the order of elements along each dimension is reversed. + * + * @param x - input array + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var typedarray = require( `@stdlib/array/typed` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.reverse( x, false ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ] + */ + reverse: typeof reverse; + + /** + * Returns a view of an input ndarray in which the order of elements along a specified dimension is reversed. + * + * @param x - input array + * @param dim - index of dimension to reverse + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var typedarray = require( `@stdlib/array/typed` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.reverseDimension( x, 0, false ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 5, 6 ], [ 3, 4 ], [ 1, 2 ] ] + */ + reverseDimension: typeof reverseDimension; + /** * Serializes ndarray meta data. * @@ -1513,6 +1887,25 @@ interface Namespace { */ serializeMetaData: typeof serializeMetaData; + /** + * Returns the shape of a provided ndarray. + * + * ## Notes + * + * - When `copy` is `false`, changes to the returned shape array may mutate the input ndarray shape. If there is a chance that the returned shape will be mutated (either directly or by downstream consumers), set `copy` to `true` to prevent unintended side effects. + * + * @param x - input ndarray + * @param copy - boolean indicating whether to explicitly copy the value assigned to the input ndarray's `shape` property + * @returns shape + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var sh = ns.shape( zeros( [ 3, 3, 3 ] ), false ); + * // returns [ 3, 3, 3 ] + */ + shape: typeof shape; + /** * Generates a stride array from an array shape. * @@ -1549,6 +1942,325 @@ interface Namespace { */ singletonDimensions: typeof singletonDimensions; + /** + * Returns a view of an input ndarray. + * + * @param x - input array + * @param s - multi-slice object + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var Slice = require( `@stdlib/ns.slice/ctor` ); + * var MultiSlice = require( `@stdlib/ns.slice/multi` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s = new MultiSlice( new Slice( null, null, -2 ), new Slice( null, null, -1 ) ); + * // returns + * + * var y = ns.slice( x, s, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 6, 5 ], [ 2, 1 ] ] + */ + slice: typeof slice; + + /** + * Assigns element values from a broadcasted input ndarray to corresponding elements in an output ndarray view. + * + * ## Notes + * + * - The input array must be broadcast compatible with the output array view to which elements will be assigned. + * - The input array must have a data type which can be safely cast to the output array data type. Floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., element values from a `'float64'` input array can be assigned to corresponding elements in a `'float32'` output array). + * + * @param x - input array + * @param y - output array + * @param s - multi-slice object for the output array + * @param strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var Slice = require( `@stdlib/slice/ctor` ); + * var MultiSlice = require( `@stdlib/slice/multi` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndzeros = require( `@stdlib/ndarray/zeros` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * // Define an input array: + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * // Define an output array: + * var y = ndzeros( [ 2, 3, 2 ], { + * 'dtype': x.dtype + * }); + * + * // Create a slice: + * var s0 = null; + * var s1 = new Slice( null, null, -1 ); + * var s2 = new Slice( null, null, -1 ); + * var s = new MultiSlice( s0, s1, s2 ); + * // returns + * + * // Perform assignment: + * var out = ns.sliceAssign( x, y, s, false ); + * // returns + * + * var bool = ( out === y ); + * // returns true + * + * arr = ndarray2array( y ); + * // returns [ [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ], [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ] ] + */ + sliceAssign: typeof sliceAssign; + + /** + * Returns a view of an input ndarray when sliced along a specified dimension. + * + * @param x - input array + * @param dim - index of dimension to slice + * @param s - slice object or an integer + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var Slice = require( `@stdlib/slice/ctor` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s = new Slice( null, null, -1 ); + * // returns + * + * var y = ns.sliceDimension( x, 0, s, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 5, 6 ], [ 3, 4 ], [ 1, 2 ] ] + */ + sliceDimension: typeof sliceDimension; + + /** + * Returns a shifted view of an input ndarray along a specified dimension. + * + * @param x - input array + * @param start - starting index (inclusive) + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.sliceDimensionFrom( x, 0, 1, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 3, 4 ], [ 5, 6 ] ] + */ + sliceDimensionFrom: typeof sliceDimensionFrom; + + /** + * Returns a truncated view of an input ndarray along a specified dimension. + * + * @param x - input array + * @param stop - ending index (exclusive) + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.sliceDimensionTo( x, 0, 2, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + */ + sliceDimensionTo: typeof sliceDimensionTo; + + /** + * Returns a shifted view of an input ndarray. + * + * @param x - input array + * @param start - starting indices (inclusive) + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s = [ 1, null ]; + * var y = ns.sliceFrom( x, s, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 3, 4 ], [ 5, 6 ] ] + */ + sliceFrom: typeof sliceFrom; + + /** + * Returns a truncated view of an input ndarray. + * + * @param x - input array + * @param stop - ending indices (exclusive) + * @param strict - boolean indicating whether to enforce strict bounds checking + * @param writable - boolean indicating whether a returned array should be writable + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s = [ 2, null ]; + * var y = ns.sliceTo( x, s, false, false ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + */ + sliceTo: typeof sliceTo; + + /** + * Returns the strides of a provided ndarray. + * + * ## Notes + * + * - When `copy` is `false`, changes to the returned strides array may mutate the input ndarray strides. If there is a chance that the returned strides will be mutated (either directly or by downstream consumers), set `copy` to `true` to prevent unintended side effects. + * + * @param x - input ndarray + * @param copy - boolean indicating whether to explicitly copy the value assigned to the input ndarray's `strides` property + * @returns strides + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var st = ns.strides( zeros( [ 3, 3, 3 ] ), false ); + * // returns [ 9, 3, 1 ] + */ + strides: typeof strides; + /** * Returns the index offset which specifies the location of the first indexed value in a multidimensional array based on a stride array. * diff --git a/docs/types/index.d.ts b/docs/types/index.d.ts index 14c7eb60..3b46e8cc 100644 --- a/docs/types/index.d.ts +++ b/docs/types/index.d.ts @@ -23,23 +23,41 @@ import array = require( './../../array' ); import base = require( './../../base' ); +import broadcastArray = require( './../../broadcast-array' ); import ndarrayCastingModes = require( './../../casting-modes' ); import ndarray = require( './../../ctor' ); +import ndarrayDataBuffer = require( './../../data-buffer' ); import defaults = require( './../../defaults' ); import dispatch = require( './../../dispatch' ); +import ndarrayDataType = require( './../../dtype' ); import ndarrayDataTypes = require( './../../dtypes' ); import ndempty = require( './../../empty' ); import ndemptyLike = require( './../../empty-like' ); +import FancyArray = require( './../../fancy' ); import scalar2ndarray = require( './../../from-scalar' ); import ind2sub = require( './../../ind2sub' ); import ndarrayIndexModes = require( './../../index-modes' ); +import iter = require( './../../iter' ); +import maybeBroadcastArray = require( './../../maybe-broadcast-array' ); import ndarrayMinDataType = require( './../../min-dtype' ); +import ndarrayMostlySafeCasts = require( './../../mostly-safe-casts' ); +import ndims = require( './../../ndims' ); import ndarrayNextDataType = require( './../../next-dtype' ); +import numel = require( './../../numel' ); +import ndarrayOffset = require( './../../offset' ); +import ndarrayOrder = require( './../../order' ); import ndarrayOrders = require( './../../orders' ); import ndarrayOutputDataTypePolicies = require( './../../output-dtype-policies' ); import ndarrayPromotionRules = require( './../../promotion-rules' ); import ndarraySafeCasts = require( './../../safe-casts' ); import ndarraySameKindCasts = require( './../../same-kind-casts' ); +import ndarrayShape = require( './../../shape' ); +import ndslice = require( './../../slice' ); +import ndsliceAssign = require( './../../slice-assign' ); +import ndsliceDimension = require( './../../slice-dimension' ); +import ndsliceDimensionFrom = require( './../../slice-dimension-from' ); +import ndsliceDimensionTo = require( './../../slice-dimension-to' ); +import ndarrayStrides = require( './../../strides' ); import sub2ind = require( './../../sub2ind' ); import ndarray2array = require( './../../to-array' ); import ndzeros = require( './../../zeros' ); @@ -110,6 +128,56 @@ interface Namespace { */ base: typeof base; + /** + * Broadcasts an ndarray to a specified shape. + * + * ## Notes + * + * - The function throws an error if a provided ndarray is incompatible with a provided shape. + * - The returned array is a **read-only** view on the input array data buffer. 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 input array may affect multiple elements. If you need to write to the input array, copy the input array before broadcasting. + * - The function always returns a new ndarray instance even if the input ndarray shape and the desired shape are the same. + * + * @param x - input array + * @param shape - desired shape + * @throws input array cannot have more dimensions than the desired shape + * @throws input array dimension sizes must be `1` or equal to the corresponding dimension in the provided shape + * @returns broadcasted array + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns + * + * var shx = x.shape; + * // returns [ 2, 2 ] + * + * var y = ns.broadcastArray( x, [ 3, 2, 2 ] ); + * // returns + * + * var shy = y.shape; + * // 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 + */ + broadcastArray: typeof broadcastArray; + /** * Returns a list of ndarray casting modes. * @@ -120,6 +188,7 @@ interface Namespace { * - 'none': only allow casting between identical types * - 'equiv': allow casting between identical and byte swapped types * - 'safe': only allow "safe" casts + * - 'mostly-safe': allow "safe" casts and, for floating-point data types, downcasts * - 'same-kind': allow "safe" casts and casts within the same kind (e.g., * between signed integers or between floats) * - 'unsafe': allow casting between all types (including between integers and @@ -129,7 +198,7 @@ interface Namespace { * * @example * var list = ns.ndarrayCastingModes(); - * // returns [ 'none', 'equiv', 'safe', 'same-kind', 'unsafe' ] + * // returns [ 'none', 'equiv', 'safe', 'mostly-safe', 'same-kind', 'unsafe' ] */ ndarrayCastingModes: typeof ndarrayCastingModes; @@ -168,6 +237,24 @@ interface Namespace { */ ndarray: typeof ndarray; + /** + * Returns the underlying data buffer of a provided ndarray. + * + * @param x - input ndarray + * @returns underlying data buffer + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'dtype': 'float64' + * }); + * + * var out = ns.ndarrayDataBuffer( x ); + * // returns + */ + ndarrayDataBuffer: typeof ndarrayDataBuffer; + /** * Returns default ndarray settings. * @@ -233,6 +320,24 @@ interface Namespace { */ dispatch: typeof dispatch; + /** + * Returns the data type of a provided ndarray. + * + * @param x - input ndarray + * @returns data type + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'ns.ndarrayDataType': 'float64' + * }); + * + * var dt = ns.ndarrayDataType( x ); + * // returns 'float64' + */ + ndarrayDataType: typeof ndarrayDataType; + /** * Returns a list of ndarray data types. * @@ -327,6 +432,41 @@ interface Namespace { */ ndemptyLike: typeof ndemptyLike; + /** + * Fancy array constructor. + * + * @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) + * @param options - function options + * @param options.mode - specifies how to handle indices which exceed array dimensions (default: 'throw') + * @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis (default: ['throw']) + * @param options.readonly - specifies whether an array should be read-only (default: false) + * @throws `buffer` argument `get` and `set` properties must be functions + * @throws `shape` argument must be an array-like object containing nonnegative integers + * @throws `shape` argument length must equal the number of dimensions + * @throws `strides` argument must be an array-like object containing integers + * @throws `strides` argument length must equal the number of dimensions (except for zero-dimensional arrays; in which case, the `strides` argument length must be equal to `1`) + * @throws for zero-dimensional ndarrays, the `strides` argument must contain a single element equal to `0` + * @throws `offset` argument must be a nonnegative integer + * @throws `buffer` argument must be compatible with specified meta data + * @throws must provide valid options + * @throws too many dimensions + * @returns an ndarray + * + * @example + * var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var out = new ns.FancyArray( 'generic', buffer, shape, strides, offset, 'row-major' ); + */ + FancyArray: typeof FancyArray; + /** * Returns a zero-dimensional ndarray containing a provided scalar value. * @@ -420,6 +560,62 @@ interface Namespace { */ ndarrayIndexModes: typeof ndarrayIndexModes; + /** + * Multidimensional array iterators. + */ + iter: typeof iter; + + /** + * Broadcasts an ndarray to a specified shape if and only if the specified shape differs from the provided ndarray's shape. + * + * ## Notes + * + * - The function throws an error if a provided ndarray is incompatible with a provided shape. + * - If a provided ndarray has the same shape as the specified shape, the function returns the provided ndarray. + * - If a provided ndarray has a different (broadcast compatible) shape than the specified shape, the function returns a new **read-only** ndarray view of the provided ndarray'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 input array may affect multiple elements. If you need to write to the input array, copy the array before broadcasting. + * + * @param x - input array + * @param shape - desired shape + * @throws input array cannot have more dimensions than the desired shape + * @throws input array dimension sizes must be `1` or equal to the corresponding dimension in the provided shape + * @throws input array and desired shape must be broadcast compatible + * @returns broadcasted array + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * + * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); + * // returns + * + * var shx = x.shape; + * // returns [ 2, 2 ] + * + * var y = ns.maybeBroadcastArray( x, [ 3, 2, 2 ] ); + * // returns + * + * var shy = y.shape; + * // 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; + /** * Returns the minimum ndarray data type of the closest "kind" necessary for storing a provided scalar value. * @@ -436,6 +632,37 @@ interface Namespace { */ ndarrayMinDataType: typeof ndarrayMinDataType; + /** + * Returns a list of ndarray data types to which a provided ndarray data type can be safely cast and, for floating-point data types, can be downcast. + * + * ## Notes + * + * - If not provided an ndarray data type, the function returns a casting table. + * - If provided an unrecognized ndarray data type, the function returns `null`. + * + * @param dtype - ndarray data type value + * @returns list of ndarray data types or null + * + * @example + * var list = ns.ndarrayMostlySafeCasts( 'float32' ); + * // returns [...] + */ + ndarrayMostlySafeCasts: typeof ndarrayMostlySafeCasts; + + /** + * Returns the number of ndarray dimensions. + * + * @param x - input ndarray + * @returns number of dimensions + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var n = ns.ndims( zeros( [ 3, 3, 3 ] ) ); + * // returns 3 + */ + ndims: typeof ndims; + /** * Returns the next larger ndarray data type of the same kind. * @@ -454,6 +681,56 @@ interface Namespace { */ ndarrayNextDataType: typeof ndarrayNextDataType; + /** + * Returns the number of elements in an ndarray. + * + * @param x - input ndarray + * @returns number of elements + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var n = ns.numel( zeros( [ 3, 3, 3 ] ) ); + * // returns 27 + */ + numel: typeof numel; + + /** + * Returns the index offset specifying the underlying buffer index of the first iterated ndarray element. + * + * @param x - input ndarray + * @returns index offset + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var n = ns.ndarrayOffset( zeros( [ 3, 3, 3 ] ) ); + * // returns 0 + */ + ndarrayOffset: typeof ndarrayOffset; + + /** + * Returns the layout order of a provided ndarray. + * + * ## Notes + * + * - If unable to resolve a layout order, the function returns `null`. + * + * @param x - input ndarray + * @returns layout order (or null) + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var x = zeros( [ 3, 3, 3 ], { + * 'ns.ndarrayOrder': 'row-major' + * }); + * + * var o = ns.ndarrayOrder( x ); + * // returns 'row-major' + */ + ndarrayOrder: typeof ndarrayOrder; + /** * Returns a list of ndarray orders. * @@ -545,6 +822,256 @@ interface Namespace { */ ndarraySameKindCasts: typeof ndarraySameKindCasts; + /** + * Returns the shape of a provided ndarray. + * + * @param x - input ndarray + * @returns shape + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var sh = ns.ndarrayShape( zeros( [ 3, 3, 3 ] ) ); + * // returns [ 3, 3, 3 ] + */ + ndarrayShape: typeof ndarrayShape; + + /** + * Returns a read-only view of an input ndarray. + * + * @param x - input array + * @param slices - slice arguments + * @param options - function options + * @param options.strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var Slice = require( `@stdlib/ns.ndslice/ctor` ); + * var MultiSlice = require( `@stdlib/ns.ndslice/multi` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s0 = new Slice( null, null, -2 ); + * var s1 = new Slice( null, null, -1 ); + * + * var y = ns.ndslice( x, s0, s1 ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 6, 5 ], [ 2, 1 ] ] + */ + ndslice: typeof ndslice; + + /** + * Assigns element values from a broadcasted input ndarray to corresponding elements in an output ndarray view. + * + * ## Notes + * + * - The input array must be broadcast compatible with the output array view to which elements will be assigned. + * - The input array must have a data type which can be safely cast to the output array data type. Floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., element values from a `'float64'` input array can be assigned to corresponding elements in a `'float32'` output array). + * + * @param x - input array + * @param y - output array + * @param slices - slice arguments + * @param options - function options + * @param options.strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var Slice = require( `@stdlib/slice/ctor` ); + * var MultiSlice = require( `@stdlib/slice/multi` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndzeros = require( `@stdlib/ndarray/zeros` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * // Define an input array: + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * // Define an output array: + * var y = ndzeros( [ 2, 3, 2 ], { + * 'dtype': x.dtype + * }); + * + * // Create a slice: + * var s0 = null; + * var s1 = new Slice( null, null, -1 ); + * var s2 = new Slice( null, null, -1 ); + * // returns + * + * // Perform assignment: + * var out = ns.ndsliceAssign( x, y, s0, s1, s2 ); + * // returns + * + * var bool = ( out === y ); + * // returns true + * + * arr = ndarray2array( y ); + * // returns [ [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ], [ [ 6, 5 ], [ 4, 3 ], [ 2, 1 ] ] ] + */ + ndsliceAssign: typeof ndsliceAssign; + + /** + * Returns a read-only view of an input ndarray when sliced along a specified dimension. + * + * @param x - input array + * @param dim - index of dimension to slice + * @param s - slice object or an integer + * @param options - function options + * @param options.strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var Slice = require( `@stdlib/slice/ctor` ); + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var s = new Slice( null, null, -1 ); + * // returns + * + * var y = ns.ndsliceDimension( x, 0, s ); + * // returns + * + * sh = y.shape; + * // returns [ 3, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 5, 6 ], [ 3, 4 ], [ 1, 2 ] ] + */ + ndsliceDimension: typeof ndsliceDimension; + + /** + * Returns a read-only shifted view of an input ndarray along a specified dimension. + * + * @param x - input array + * @param start - starting index (inclusive) + * @param options - function options + * @param options.strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.ndsliceDimensionFrom( x, 0, 1 ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 3, 4 ], [ 5, 6 ] ] + */ + ndsliceDimensionFrom: typeof ndsliceDimensionFrom; + + /** + * Returns a read-only truncated view of an input ndarray along a specified dimension. + * + * @param x - input array + * @param stop - ending index (exclusive) + * @param options - function options + * @param options.strict - boolean indicating whether to enforce strict bounds checking + * @returns output array + * + * @example + * var ndarray = require( `@stdlib/ndarray/ctor` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var buffer = [ 1, 2, 3, 4, 5, 6 ]; + * var shape = [ 3, 2 ]; + * var strides = [ 2, 1 ]; + * var offset = 0; + * + * var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); + * // returns + * + * var sh = x.shape; + * // returns [ 3, 2 ] + * + * var arr = ndarray2array( x ); + * // returns [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ] + * + * var y = ns.ndsliceDimensionTo( x, 0, 2 ); + * // returns + * + * sh = y.shape; + * // returns [ 2, 2 ] + * + * arr = ndarray2array( y ); + * // returns [ [ 1, 2 ], [ 3, 4 ] ] + */ + ndsliceDimensionTo: typeof ndsliceDimensionTo; + + /** + * Returns the strides of a provided ndarray. + * + * @param x - input ndarray + * @returns strides + * + * @example + * var zeros = require( `@stdlib/ndarray/zeros` ); + * + * var sh = ns.ndarrayStrides( zeros( [ 3, 3, 3 ] ) ); + * // returns [ 9, 3, 1 ] + */ + ndarrayStrides: typeof ndarrayStrides; + /** * Converts subscripts to a linear index. * @@ -577,7 +1104,7 @@ interface Namespace { /** * Converts an ndarray to a generic array (which may include nested arrays). * - * @param arr - input ndarray + * @param x - input ndarray * @returns array (which may include nested arrays) * * @example diff --git a/iter/docs/types/index.d.ts b/iter/docs/types/index.d.ts index 9dbf5ca2..6d986611 100644 --- a/iter/docs/types/index.d.ts +++ b/iter/docs/types/index.d.ts @@ -21,16 +21,228 @@ /* tslint:disable:max-line-length */ /* tslint:disable:max-file-line-count */ +import nditerColumns = require( './../../../iter/columns' ); +import nditerEntries = require( './../../../iter/entries' ); +import nditerIndices = require( './../../../iter/indices' ); import nditerRows = require( './../../../iter/rows' ); +import nditer2arrayEach = require( './../../../iter/to-array-each' ); +import nditerValues = require( './../../../iter/values' ); /** * Interface describing the `iter` namespace. */ interface Namespace { /** - * Iterator for iterating over matrix rows. + * Returns an iterator which iterates over each column in a matrix (or stack of matrices). + * + * @param x - input value + * @param options - function options + * @param options.readonly - boolean indicating whether returned views should be read-only + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], { + * 'dtype': 'float64' + * }); + * // returns + * + * var iter = ns.nditerColumns( x ); + * + * var v = iter.next().value; + * // returns + * + * var arr = ndarray2array( v ); + * // returns [ 1, 3 ] + * + * v = iter.next().value; + * // returns + * + * arr = ndarray2array( v ); + * // returns [ 2, 4 ] + * + * v = iter.next().value; + * // returns + * + * arr = ndarray2array( v ); + * // returns [ 5, 7 ] + * + * // ... + */ + nditerColumns: typeof nditerColumns; + + /** + * Returns an iterator which returns `[index, value]` pairs for each element in a provided ndarray. + * + * ## Notes + * + * - Each returned index is a Cartesian index (i.e., an array of subscripts/dimension indices). + * + * @param x - input array + * @param options - function options + * @param options.order - index iteration order + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], { + * 'dtype': 'float64' + * }); + * // returns + * + * var iter = ns.nditerEntries( x ); + * + * var v = iter.next().value; + * // returns [ [ 0, 0, 0 ], 1 ] + * + * v = iter.next().value; + * // returns [ [ 0, 0, 1 ], 2 ] + * + * v = iter.next().value; + * // returns [ [ 0, 1, 0 ], 3 ] + * + * // ... + */ + nditerEntries: typeof nditerEntries; + + /** + * Returns an iterator which returns indices for use indexing into an ndarray having a specified shape. + * + * @param shape - input shape + * @param options - function options + * @param options.order - index iteration order + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], { + * 'dtype': 'float64' + * }); + * // returns + * + * var iter = ns.nditerIndices( x.shape ); + * + * var v = iter.next().value; + * // returns [ 0, 0, 0 ] + * + * v = iter.next().value; + * // returns [ 0, 0, 1 ] + * + * v = iter.next().value; + * // returns [ 0, 1, 0 ] + * + * // ... + */ + nditerIndices: typeof nditerIndices; + + /** + * Returns an iterator which iterates over each row in a matrix (or stack of matrices). + * + * @param x - input value + * @param options - function options + * @param options.readonly - boolean indicating whether returned views should be read-only + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], { + * 'dtype': 'float64' + * }); + * // returns + * + * var iter = ns.nditerRows( x ); + * + * var v = iter.next().value; + * // returns + * + * var arr = ndarray2array( v ); + * // returns [ 1, 2 ] + * + * v = iter.next().value; + * // returns + * + * arr = ndarray2array( v ); + * // returns [ 3, 4 ] + * + * v = iter.next().value; + * // returns + * + * arr = ndarray2array( v ); + * // returns [ 5, 6 ] + * + * // ... */ nditerRows: typeof nditerRows; + + /** + * Returns an iterator which converts each iterated ndarray to a generic array. + * + * ## Notes + * + * - If an environment supports `Symbol.iterator` and a provided iterator is iterable, the returned iterator is iterable. + * + * @param iterator - input iterator + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * var ndarray2array = require( `@stdlib/ndarray/to-array` ); + * var nditerRows = require( `@stdlib/ndarray/iter/rows` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] ); + * // returns + * + * var iter = ns.nditer2arrayEach( nditerRows( x ) ); + * + * var v = iter.next().value; + * // returns [ 1, 2 ] + * + * v = iter.next().value; + * // returns [ 3, 4 ] + * + * v = iter.next().value; + * // returns [ 5, 6 ] + * + * // ... + */ + nditer2arrayEach: typeof nditer2arrayEach; + + /** + * Returns an iterator which returns individual elements of a provided ndarray. + * + * @param x - input array + * @param options - function options + * @param options.order - index iteration order + * @returns iterator + * + * @example + * var array = require( `@stdlib/ndarray/array` ); + * + * var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], { + * 'dtype': 'float64' + * }); + * // returns + * + * var iter = ns.nditerValues( x ); + * + * var v = iter.next().value; + * // returns 1 + * + * v = iter.next().value; + * // returns 2 + * + * v = iter.next().value; + * // returns 3 + * + * // ... + */ + nditerValues: typeof nditerValues; } /**