diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/README.md b/lib/node_modules/@stdlib/ndarray/base/shift/README.md new file mode 100644 index 000000000000..c1180483163e --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/README.md @@ -0,0 +1,154 @@ + + +# shift + +> Return an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var shift = require( '@stdlib/ndarray/base/shift' ); +``` + +#### shift( x, dim, writable ) + +Returns an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension. + +```javascript +var ndarray = require( '@stdlib/ndarray/ctor' ); +var getShape = require( '@stdlib/ndarray/shape' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); + +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 x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); +// returns + +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 = shift( x, 0, false ); +// returns [ , ] + +arr = ndarray2array( y[ 0 ] ); +// returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] + +arr = ndarray2array( y[ 1 ] ); +// returns [ [ 1.0, 2.0 ] ] +``` + +The function accepts the following arguments: + +- **x**: input ndarray. +- **dim**: dimension along which to perform the operation. If provided an integer less than zero, the dimension index is resolved relative to the last dimension, with the last dimension corresponding to the value `-1`. +- **writable**: boolean indicating whether a returned ndarray should be writable. + +
+ + + + + +
+ +## Notes + +- The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances. + +
+ + + + + +
+ +## Examples + + + +```javascript +var array = require( '@stdlib/ndarray/array' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var shift = require( '@stdlib/ndarray/base/shift' ); + +// Create a linear ndarray buffer: +var buf = zeroTo( 27 ); + +// Create an ndarray which is a stack of three 3x3 matrices: +var x = array( buf, { + 'shape': [ 3, 3, 3 ] +}); + +// Remove the first row from each matrix: +var y = shift( x, 1, false ); +// returns [ , ] + +console.log( ndarray2array( y[ 0 ] ) ); +console.log( ndarray2array( y[ 1 ] ) ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +
+ + + + + +
+ +
+ + diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/benchmark/benchmark.js b/lib/node_modules/@stdlib/ndarray/base/shift/benchmark/benchmark.js new file mode 100644 index 000000000000..485840f3d061 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/benchmark/benchmark.js @@ -0,0 +1,190 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var empty = require( '@stdlib/ndarray/empty' ); +var pkg = require( './../package.json' ).name; +var shift = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::1d', function benchmark( b ) { + var values; + var v; + var i; + + /* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + values = [ + empty( [ 2 ], { 'dtype': 'float64' } ), + empty( [ 2 ], { 'dtype': 'float32' } ), + empty( [ 2 ], { 'dtype': 'int32' } ), + empty( [ 2 ], { 'dtype': 'complex128' } ), + empty( [ 2 ], { 'dtype': 'generic' } ) + ]; + + /* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = shift( values[ i%values.length ], 0, false ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array of ndarrays' ); + } + } + b.toc(); + if ( !isndarrayLike( v[0] ) || !isndarrayLike( v[1] ) ) { + b.fail( 'should return an array of ndarrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+'::2d', function benchmark( b ) { + var values; + var v; + var i; + + /* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + values = [ + empty( [ 2, 2 ], { 'dtype': 'float64' } ), + empty( [ 2, 2 ], { 'dtype': 'float32' } ), + empty( [ 2, 2 ], { 'dtype': 'int32' } ), + empty( [ 2, 2 ], { 'dtype': 'complex128' } ), + empty( [ 2, 2 ], { 'dtype': 'generic' } ) + ]; + + /* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = shift( values[ i%values.length ], 0, false ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array of ndarrays' ); + } + } + b.toc(); + if ( !isndarrayLike( v[0] ) || !isndarrayLike( v[1] ) ) { + b.fail( 'should return an array of ndarrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+'::3d', function benchmark( b ) { + var values; + var v; + var i; + + /* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + values = [ + empty( [ 2, 2, 2 ], { 'dtype': 'float64' } ), + empty( [ 2, 2, 2 ], { 'dtype': 'float32' } ), + empty( [ 2, 2, 2 ], { 'dtype': 'int32' } ), + empty( [ 2, 2, 2 ], { 'dtype': 'complex128' } ), + empty( [ 2, 2, 2 ], { 'dtype': 'generic' } ) + ]; + + /* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = shift( values[ i%values.length ], 0, false ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array of ndarrays' ); + } + } + b.toc(); + if ( !isndarrayLike( v[0] ) || !isndarrayLike( v[1] ) ) { + b.fail( 'should return an array of ndarrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+'::4d', function benchmark( b ) { + var values; + var v; + var i; + + /* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + values = [ + empty( [ 2, 2, 2, 2 ], { 'dtype': 'float64' } ), + empty( [ 2, 2, 2, 2 ], { 'dtype': 'float32' } ), + empty( [ 2, 2, 2, 2 ], { 'dtype': 'int32' } ), + empty( [ 2, 2, 2, 2 ], { 'dtype': 'complex128' } ), + empty( [ 2, 2, 2, 2 ], { 'dtype': 'generic' } ) + ]; + + /* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = shift( values[ i%values.length ], 0, false ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array of ndarrays' ); + } + } + b.toc(); + if ( !isndarrayLike( v[0] ) || !isndarrayLike( v[1] ) ) { + b.fail( 'should return an array of ndarrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+'::5d', function benchmark( b ) { + var values; + var v; + var i; + + /* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + values = [ + empty( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float64' } ), + empty( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float32' } ), + empty( [ 2, 2, 2, 2, 2 ], { 'dtype': 'int32' } ), + empty( [ 2, 2, 2, 2, 2 ], { 'dtype': 'complex128' } ), + empty( [ 2, 2, 2, 2, 2 ], { 'dtype': 'generic' } ) + ]; + + /* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */ + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = shift( values[ i%values.length ], 0, false ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array of ndarrays' ); + } + } + b.toc(); + if ( !isndarrayLike( v[0] ) || !isndarrayLike( v[1] ) ) { + b.fail( 'should return an array of ndarrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/base/shift/docs/repl.txt new file mode 100644 index 000000000000..d448ecb630c2 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/docs/repl.txt @@ -0,0 +1,39 @@ + +{{alias}}( x, dim, writable ) + Returns an array containing a truncated view of an input ndarray and a view + of the first element(s) along a specified dimension. + + Parameters + ---------- + x: ndarray + Input array. + + dim: integer + Dimension along which to perform the operation. If provided an integer + less than zero, the dimension index is resolved relative to the last + dimension, with the last dimension corresponding to the value `-1`. + + writable: boolean + Boolean indicating whether a returned ndarray should be writable. This + parameter only applies to ndarray constructors which support read-only + instances. + + Returns + ------- + out: Array + An array containing a truncated view of an input ndarray and a view of + the first element(s) along a specified dimension. + + Examples + -------- + > var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] ) + + > var y = {{alias}}( x, 1, false ) + [ , ] + > {{alias:@stdlib/ndarray/to-array}}( y[0] ) + [ [ 2 ], [ 4 ] ] + > {{alias:@stdlib/ndarray/to-array}}( y[1] ) + [ [ 1 ], [ 3 ] ] + + See Also + -------- diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/index.d.ts new file mode 100644 index 000000000000..b20d0542c1c8 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/index.d.ts @@ -0,0 +1,64 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +// TypeScript Version: 4.1 + +/// + +import { ndarray } from '@stdlib/types/ndarray'; + + +/** +* Returns an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension. +* +* @param x - input array +* @param dim - dimension along which to perform the operation +* @param writable - boolean indicating whether returned arrays should be writable +* @returns a list of ndarrays +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var ndarray2array = require( '@stdlib/ndarray/to-array' ); +* +* var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* var shape = [ 3, 2 ]; +* var strides = [ 2, 1 ]; +* var offset = 0; +* +* var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); +* // returns +* +* var arr = ndarray2array( x ); +* // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* var y = shift( x, 0, false ); +* // returns [ , ] +* +* arr = ndarray2array( y[ 0 ] ); +* // returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* arr = ndarray2array( y[ 1 ] ); +* // returns [ [ 1.0, 2.0 ] ] +*/ +declare function shift( x: T, dim: number, writable: boolean ): [ T, T ]; + + +// EXPORTS // + +export = shift; diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/test.ts new file mode 100644 index 000000000000..504b9a89c303 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/docs/types/test.ts @@ -0,0 +1,81 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +import empty = require( '@stdlib/ndarray/base/empty' ); +import shift = require( './index' ); + + +// TESTS // + +// The function returns an array of ndarrays... +{ + const order = 'row-major'; + const sh = [ 2, 2 ]; + + shift( empty( 'float64', sh, order ), 1, false ); // $ExpectType [float64ndarray, float64ndarray] + shift( empty( 'complex64', sh, order ), 1, false ); // $ExpectType [complex64ndarray, complex64ndarray] + shift( empty( 'uint8', sh, order ), 1, false ); // $ExpectType [uint8ndarray, uint8ndarray] +} + +// The compiler throws an error if the function is provided a first argument which is not an ndarray... +{ + shift( '10', 1, false ); // $ExpectError + shift( 10, 1, false ); // $ExpectError + shift( false, 1, false ); // $ExpectError + shift( true, 1, false ); // $ExpectError + shift( null, 1, false ); // $ExpectError + shift( [], 1, false ); // $ExpectError + shift( {}, 1, false ); // $ExpectError + shift( ( x: number ): number => x, 1, false ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not an integer... +{ + const x = empty( 'float64', [ 2, 2 ], 'row-major' ); + + shift( x, '5', false ); // $ExpectError + shift( x, false, false ); // $ExpectError + shift( x, true, false ); // $ExpectError + shift( x, null, false ); // $ExpectError + shift( x, undefined, false ); // $ExpectError + shift( x, [ '5' ], false ); // $ExpectError + shift( x, {}, false ); // $ExpectError + shift( x, ( x: number ): number => x, false ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a boolean... +{ + const x = empty( 'float64', [ 2, 2 ], 'row-major' ); + + shift( x, 1, '5' ); // $ExpectError + shift( x, 1, 5 ); // $ExpectError + shift( x, 1, null ); // $ExpectError + shift( x, 1, undefined ); // $ExpectError + shift( x, 1, [ '5' ] ); // $ExpectError + shift( x, 1, {} ); // $ExpectError + shift( x, 1, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + const x = empty( 'float64', [ 2, 2 ], 'row-major' ); + + shift( x ); // $ExpectError + shift( x, 1 ); // $ExpectError + shift( x, 1, false, {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/examples/index.js b/lib/node_modules/@stdlib/ndarray/base/shift/examples/index.js new file mode 100644 index 000000000000..79402d072ba4 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/examples/index.js @@ -0,0 +1,39 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +var array = require( '@stdlib/ndarray/array' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var shift = require( './../lib' ); + +// Create a linear ndarray buffer: +var buf = zeroTo( 27 ); + +// Create an ndarray: +var x = array( buf, { + 'shape': [ 3, 3, 3 ] +}); +console.log( ndarray2array( x ) ); + +// Remove the first row from each matrix: +var y = shift( x, 1, false ); + +console.log( ndarray2array( y[ 0 ] ) ); +console.log( ndarray2array( y[ 1 ] ) ); diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/lib/index.js b/lib/node_modules/@stdlib/ndarray/base/shift/lib/index.js new file mode 100644 index 000000000000..e3b0749a781e --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/lib/index.js @@ -0,0 +1,59 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/** +* Return an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension. +* +* @module @stdlib/ndarray/base/shift +* +* @example +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var ndarray2array = require( '@stdlib/ndarray/to-array' ); +* var shift = require( '@stdlib/ndarray/base/shift' ); +* +* 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 x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); +* // returns +* +* var arr = ndarray2array( x ); +* // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* var y = shift( x, 0, false ); +* // returns [ , ] +* +* arr = ndarray2array( y[ 0 ] ); +* // returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* arr = ndarray2array( y[ 1 ] ); +* // returns [ [ 1.0, 2.0 ] ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/lib/main.js b/lib/node_modules/@stdlib/ndarray/base/shift/lib/main.js new file mode 100644 index 000000000000..637a15a63626 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/lib/main.js @@ -0,0 +1,101 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var normalizeIndex = require( '@stdlib/ndarray/base/normalize-index' ); +var ndims = require( '@stdlib/ndarray/base/ndims' ); +var sliceFrom = require( '@stdlib/ndarray/base/slice-from' ); +var sliceTo = require( '@stdlib/ndarray/base/slice-to' ); +var nulls = require( '@stdlib/array/base/nulls' ); +var format = require( '@stdlib/string/format' ); + + +// MAIN // + +/** +* Returns an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension. +* +* @param {ndarray} x - input array +* @param {integer} dim - dimension along which to perform the operation +* @param {boolean} writable - boolean indicating whether returned arrays should be writable +* @throws {TypeError} first argument must be an ndarray having one or more dimensions +* @throws {RangeError} dimension index exceeds the number of dimensions +* @returns {Array} a list of ndarrays +* +* @example +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var ndarray2array = require( '@stdlib/ndarray/to-array' ); +* +* 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 x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' ); +* // returns +* +* var arr = ndarray2array( x ); +* // returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* var y = shift( x, 0, false ); +* // returns [ , ] +* +* arr = ndarray2array( y[ 0 ] ); +* // returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] +* +* arr = ndarray2array( y[ 1 ] ); +* // returns [ [ 1.0, 2.0 ] ] +*/ +function shift( x, dim, writable ) { + var v0; + var v1; + var N; + var s; + + // Retrieve array meta data: + N = ndims( x ); + + // Check whether we were provided a zero-dimensional array... + if ( N === 0 ) { + throw new TypeError( format( 'invalid argument. First argument must be an ndarray having one or more dimensions. Number of dimensions: %d.', N ) ); + } + // Normalize the dimension index: + dim = normalizeIndex( dim, N-1 ); + if ( dim === -1 ) { + throw new RangeError( format( 'invalid argument. Dimension index exceeds the number of dimensions. Number of dimensions: %d. Value: `%d`.', N, dim ) ); + } + // Define a list of slice arguments: + s = nulls( N ); + s[ dim ] = 1; + + // Create a truncated view: + v0 = sliceFrom( x, s, false, writable ); + + // Create a view of the first element(s): + v1 = sliceTo( x, s, false, writable ); + + return [ v0, v1 ]; +} + + +// EXPORTS // + +module.exports = shift; diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/package.json b/lib/node_modules/@stdlib/ndarray/base/shift/package.json new file mode 100644 index 000000000000..fac244fcf27f --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/package.json @@ -0,0 +1,67 @@ +{ + "name": "@stdlib/ndarray/base/shift", + "version": "0.0.0", + "description": "Return an array containing a truncated view of an input ndarray and a view of the first element(s) along a specified dimension.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdtypes", + "types", + "base", + "data", + "structure", + "vector", + "ndarray", + "matrix", + "slice", + "shift", + "view", + "remove", + "truncate" + ] +} diff --git a/lib/node_modules/@stdlib/ndarray/base/shift/test/test.js b/lib/node_modules/@stdlib/ndarray/base/shift/test/test.js new file mode 100644 index 000000000000..87eef35829a0 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/shift/test/test.js @@ -0,0 +1,425 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var isReadOnly = require( '@stdlib/ndarray/base/assert/is-read-only' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var zeros = require( '@stdlib/ndarray/zeros' ); +var getShape = require( '@stdlib/ndarray/shape' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); +var ndarray = require( '@stdlib/ndarray/ctor' ); +var shift = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof shift, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if provided a zero-dimensional array', function test( t ) { + var values; + var i; + + values = [ + zeros( [] ) + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), TypeError, 'throws an error' ); + } + t.end(); + + function badValue( x ) { + return function badValue() { + shift( x, 0, false ); + }; + } +}); + +tape( 'the function throws an error if the dimension index exceeds the number of dimensions', function test( t ) { + var values; + var i; + + values = [ + zeros( [ 1 ] ), + zeros( [ 1, 1 ] ), + zeros( [ 1, 1, 1 ] ), + zeros( [ 1, 1, 1, 1 ] ) + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ], 10 ), RangeError, 'throws an error when provided ' + values[ i ].shape.join( 'x' ) ); + t.throws( badValue( values[ i ], -10 ), RangeError, 'throws an error when provided ' + values[ i ].shape.join( 'x' ) ); + } + t.end(); + + function badValue( x, dim ) { + return function badValue() { + shift( x, dim, false ); + }; + } +}); + +tape( 'the function returns an array containing ndarrays (ndims=1, readonly)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 6, 'float64' ); + sh = [ 6 ]; + st = [ 1 ]; + o = 0; + ord = 'row-major'; + + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, 0, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 5 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ 1, 2, 3, 4, 5 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ 0 ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an array containing ndarrays (ndims=1, writable)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 6, 'float64' ); + sh = [ 6 ]; + st = [ 1 ]; + o = 0; + ord = 'row-major'; + + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, -1, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 5 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ 1, 2, 3, 4, 5 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ 0 ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an array containing ndarrays (ndims=2, readonly)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 8, 'float64' ); + sh = [ 2, 4 ]; + st = [ 4, 1 ]; + o = 0; + ord = 'row-major'; + + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, 0, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 1, 4 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1, 4 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ 4, 5, 6, 7 ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ 0, 1, 2, 3 ] ], 'returns expected value' ); + + actual = shift( x, 1, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 3 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ 1, 2, 3 ], [ 5, 6, 7 ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ 0 ], [ 4 ] ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an array containing ndarrays (ndims=2, writable)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 8, 'float64' ); + sh = [ 2, 4 ]; + st = [ 4, 1 ]; + o = 0; + ord = 'row-major'; + + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, -2, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 1, 4 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1, 4 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ 4, 5, 6, 7 ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ 0, 1, 2, 3 ] ], 'returns expected value' ); + + actual = shift( x, -1, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 3 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ 1, 2, 3 ], [ 5, 6, 7 ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ 0 ], [ 4 ] ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an array containing ndarrays (ndims=3, readonly)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 8, 'float64' ); + sh = [ 2, 2, 2 ]; + st = [ 4, 2, 1 ]; + o = 0; + ord = 'row-major'; + + /* + * [ + * [ + * [ 0, 1 ], + * [ 2, 3 ] + * ], + * [ + * [ 4, 5 ], + * [ 6, 7 ] + * ] + *]; + */ + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, 0, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 1, 2, 2 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1, 2, 2 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 4, 5 ], [ 6, 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0, 1 ], [ 2, 3 ] ] ], 'returns expected value' ); + + actual = shift( x, 1, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 1, 2 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 1, 2 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 2, 3 ] ], [ [ 6, 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0, 1 ] ], [ [ 4, 5 ] ] ], 'returns expected value' ); + + actual = shift( x, 2, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 2, 1 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 2, 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 1 ], [ 3 ] ], [ [ 5 ], [ 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0 ], [ 2 ] ], [ [ 4 ], [ 6 ] ] ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an array containing ndarrays (ndims=3, writable)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 8, 'float64' ); + sh = [ 2, 2, 2 ]; + st = [ 4, 2, 1 ]; + o = 0; + ord = 'row-major'; + + /* + * [ + * [ + * [ 0, 1 ], + * [ 2, 3 ] + * ], + * [ + * [ 4, 5 ], + * [ 6, 7 ] + * ] + *]; + */ + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, -3, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 1, 2, 2 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1, 2, 2 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 4, 5 ], [ 6, 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0, 1 ], [ 2, 3 ] ] ], 'returns expected value' ); + + actual = shift( x, -2, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 1, 2 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 1, 2 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 2, 3 ] ], [ [ 6, 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0, 1 ] ], [ [ 4, 5 ] ] ], 'returns expected value' ); + + actual = shift( x, -1, true ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), false, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), false, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 2, 1 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 2, 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [ [ [ 1 ], [ 3 ] ], [ [ 5 ], [ 7 ] ] ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [ [ [ 0 ], [ 2 ] ], [ [ 4 ], [ 6 ] ] ], 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns empty views if provided an empty array (ndims=2)', function test( t ) { + var actual; + var buf; + var ord; + var sh; + var st; + var o; + var x; + + buf = zeroTo( 8, 'float64' ); + st = [ 4, 1 ]; + o = 0; + ord = 'row-major'; + + sh = [ 2, 0 ]; + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, 0, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 1, 0 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 1, 0 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [], 'returns expected value' ); + + actual = shift( x, 1, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 2, 0 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 2, 0 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [], 'returns expected value' ); + + sh = [ 0, 4 ]; + x = new ndarray( 'float64', buf, sh, st, o, ord ); + + actual = shift( x, 0, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 0, 4 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 0, 4 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [], 'returns expected value' ); + + actual = shift( x, 1, false ); + + t.strictEqual( isndarrayLike( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isndarrayLike( actual[1] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[0] ), true, 'returns expected value' ); + t.strictEqual( isReadOnly( actual[1] ), true, 'returns expected value' ); + t.deepEqual( getShape( actual[0] ), [ 0, 3 ], 'returns expected value' ); + t.deepEqual( getShape( actual[1] ), [ 0, 1 ], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[0] ), [], 'returns expected value' ); + t.deepEqual( ndarray2array( actual[1] ), [], 'returns expected value' ); + + t.end(); +});