Skip to content

Commit

Permalink
Auto-generated commit
Browse files Browse the repository at this point in the history
  • Loading branch information
stdlib-bot committed Nov 23, 2023
1 parent dcb2555 commit fc599be
Show file tree
Hide file tree
Showing 13 changed files with 655 additions and 5 deletions.
106 changes: 106 additions & 0 deletions base/from-strided/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
<!--
@license Apache-2.0
Copyright (c) 2023 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.
-->

# strided2array

> Convert a strided array to a non-strided generic array.
<section class="intro">

</section>

<!-- /.intro -->

<section class="usage">

## Usage

```javascript
var strided2array = require( '@stdlib/array/base/from-strided' );
```

#### strided2array( N, x, stride, offset )

Converts a strided array to a non-strided generic array.

```javascript
var x = [ 1, 2, 3, 4, 5, 6 ];

var arr = strided2array( 3, x, 2, 0 );
// returns [ 1, 3, 5 ]
```

The function accepts the following arguments:

- **N**: number of indexed elements.
- **x**: input array.
- **stride**: index stride.
- **offset**: index of the first indexed value in the input array.

</section>

<!-- /.usage -->

<section class="notes">

## Notes

- The function assumes that the input array is compatible with the specified number of elements, index stride, and index offset.

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var zeroTo = require( '@stdlib/array/base/zero-to' );
var strided2array = require( '@stdlib/array/base/from-strided' );

var x = zeroTo( 10 );
console.log( x );

var y = strided2array( 5, x, -2, x.length-1 );
console.log( y );
```

</section>

<!-- /.examples -->

<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->

<section class="related">

</section>

<!-- /.related -->

<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="links">

</section>

<!-- /.links -->
96 changes: 96 additions & 0 deletions base/from-strided/benchmark/benchmark.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2023 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 isnan = require( '@stdlib/math/base/assert/is-nan' );
var pow = require( '@stdlib/math/base/special/pow' );
var zeroTo = require( './../../../base/zero-to' );
var pkg = require( './../package.json' ).name;
var strided2array = require( './../lib' );


// FUNCTIONS //

/**
* Creates a benchmark function.
*
* @private
* @param {PositiveInteger} N - number of elements
* @returns {Function} benchmark function
*/
function createBenchmark( N ) {
var x = zeroTo( N );
return benchmark;

/**
* Benchmark function.
*
* @private
* @param {Benchmark} b - benchmark instance
*/
function benchmark( b ) {
var out;
var i;

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
out = strided2array( N, x, 1, 0 );
if ( isnan( out[ i%N ] ) ) {
b.fail( 'should not return NaN' );
}
}
b.toc();

if ( isnan( out[ i%N ] ) ) {
b.fail( 'should not return NaN' );
}
b.pass( 'benchmark finished' );
b.end();
}
}


// MAIN //

/**
* Main execution sequence.
*
* @private
*/
function main() {
var min;
var max;
var N;
var f;
var i;

min = 1; // 10^min
max = 6; // 10^max

for ( i = min; i <= max; i++ ) {
N = pow( 10, i );
f = createBenchmark( N );
bench( pkg+':len='+N, f );
}
}

main();
30 changes: 30 additions & 0 deletions base/from-strided/docs/repl.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@

{{alias}}( N, x, stride, offset )
Converts a strided array to a non-strided generic array.

The function assumes that the input array is compatible with the specified
number of elements, index stride, and index offset.

Parameters
----------
N: integer
Number of indexed elements.

x: ArrayLikeObject
Input array.

stride: integer
Index stride.

offset: integer
Index of the first indexed value in the input array.

Examples
--------
> var x = [ 1.0, 2.0, 3.0, 4.0 ];
> var y = {{alias}}( 2, x, 2, 0 )
[ 1.0, 3.0 ]

See Also
--------

49 changes: 49 additions & 0 deletions base/from-strided/docs/types/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
/*
* @license Apache-2.0
*
* Copyright (c) 2023 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

/// <reference types="@stdlib/types"/>

import { Collection } from '@stdlib/types/array';

/**
* Converts a strided array to a non-strided generic array.
*
* ## Notes
*
* - The function assumes that the input array is compatible with the specified number of elements, index stride, and index offset.
*
* @param N - number of indexed elements
* @param x - input array
* @param stride - index stride
* @param offset - index of the first indexed value in the input array
* @returns two-dimensional nested array
*
* @example
* var x = [ 1, 2, 3, 4, 5, 6 ];
*
* var arr = strided2array( 3, x, 2, 0 );
* // returns [ 1, 3, 5 ]
*/
declare function strided2array<T = unknown, U = T>( N: number, x: Collection<T>, stride: number, offset: number ): Array<U>;


// EXPORTS //

export = strided2array;
89 changes: 89 additions & 0 deletions base/from-strided/docs/types/test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
/*
* @license Apache-2.0
*
* Copyright (c) 2023 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 strided2array = require( './index' );


// TESTS //

// The function returns an array...
{
const x = [ 1.0, 2.0, 3.0, 4.0 ];

strided2array( x.length, x, 1, 0 ); // $ExpectType Array<number>
}

// The compiler throws an error if the function is provided a first argument which is not a number...
{
const x = [ 1.0, 2.0, 3.0, 4.0 ];

strided2array( 'abc', x, 1, 0 ); // $ExpectError
strided2array( true, x, 1, 0 ); // $ExpectError
strided2array( false, x, 1, 0 ); // $ExpectError
strided2array( null, x, 1, 0 ); // $ExpectError
strided2array( [ '1' ], x, 1, 0 ); // $ExpectError
strided2array( {}, x, 1, 0 ); // $ExpectError
strided2array( ( x: number ): number => x, x, 1, 0 ); // $ExpectError
}

// The compiler throws an error if the function is provided a second argument which is not an array...
{
strided2array( 10, 3.14, 1, 0 ); // $ExpectError
strided2array( 10, true, 1, 0 ); // $ExpectError
strided2array( 10, false, 1, 0 ); // $ExpectError
strided2array( 10, null, 1, 0 ); // $ExpectError
strided2array( 10, {}, 1, 0 ); // $ExpectError
strided2array( 10, ( x: number ): number => x, 1, 0 ); // $ExpectError
}

// The compiler throws an error if the function is provided a third argument which is not a number...
{
const x = [ 1.0, 2.0, 3.0, 4.0 ];

strided2array( x.length, x, 'abc', 0 ); // $ExpectError
strided2array( x.length, x, true, 0 ); // $ExpectError
strided2array( x.length, x, false, 0 ); // $ExpectError
strided2array( x.length, x, null, 0 ); // $ExpectError
strided2array( x.length, x, [ '1' ], 0 ); // $ExpectError
strided2array( x.length, x, {}, 0 ); // $ExpectError
strided2array( x.length, x, ( x: number ): number => x, 0 ); // $ExpectError
}

// The compiler throws an error if the function is provided a fourth argument which is not a number...
{
const x = [ 1.0, 2.0, 3.0, 4.0 ];

strided2array( x.length, x, 1, 'abc' ); // $ExpectError
strided2array( x.length, x, 1, true ); // $ExpectError
strided2array( x.length, x, 1, false ); // $ExpectError
strided2array( x.length, x, 1, null ); // $ExpectError
strided2array( x.length, x, 1, [ '1' ] ); // $ExpectError
strided2array( x.length, x, 1, {} ); // $ExpectError
strided2array( x.length, x, 1, ( x: number ): number => x ); // $ExpectError
}

// The compiler throws an error if the function is provided an unsupported number of arguments...
{
const x = [ 1.0, 2.0, 3.0, 4.0 ];

strided2array(); // $ExpectError
strided2array( x.length ); // $ExpectError
strided2array( x.length, x ); // $ExpectError
strided2array( x.length, x, 1 ); // $ExpectError
strided2array( x.length, x, 1, 0, {} ); // $ExpectError
}
Loading

0 comments on commit fc599be

Please sign in to comment.