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 Jan 27, 2024
1 parent 1079580 commit f330b15
Show file tree
Hide file tree
Showing 17 changed files with 971 additions and 12 deletions.
4 changes: 2 additions & 2 deletions base/cartesian-power/docs/types/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@

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

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

/**
* Returns the Cartesian power.
Expand All @@ -40,7 +40,7 @@ import { Collection } from '@stdlib/types/array';
* var out = cartesianPower( x, 2 );
* // returns [ [ 1, 1 ], [ 1, 2 ], [ 2, 1 ], [ 2, 2 ] ]
*/
declare function cartesianPower<T = unknown>( x: Collection<T>, n: number ): Array<Array<T>>;
declare function cartesianPower<T = unknown>( x: Collection<T> | AccessorArrayLike<T>, n: number ): Array<Array<T>>;


// EXPORTS //
Expand Down
11 changes: 8 additions & 3 deletions base/cartesian-power/lib/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

// MODULES //

var resolveGetter = require( './../../../base/resolve-getter' );
var pow = require( '@stdlib/math/base/special/pow' );


Expand All @@ -30,14 +31,14 @@ var pow = require( '@stdlib/math/base/special/pow' );
*
* ## Notes
*
* - The Cartesian power is an n-fold Cartesian product involving a single array. The main insight of this implementation is that the n-fold Cartesian product can be presented as an n-dimensional array stored in row-major order. As such, we can
* - The Cartesian power is an n-fold Cartesian product involving a single array. The main insight of this implementation is that the n-fold Cartesian product can be represented as an n-dimensional array stored in row-major order. As such, we can
*
* - Compute the total number of tuples, which is simply the size of the provided array (set) raised to the specified power `n`. For n-dimensional arrays, this is the equivalent of computing the product of array dimensions to determine the total number of elements.
* - Initialize an array for storing indices for indexing into the provided array. For n-dimensional arrays, the index array is equivalent to an array of subscripts for indexing into each dimension.
* - For the outermost loop, treat the loop index as a linear index into an n-dimensional array and resolve the corresponding subscripts.
* - Continue iterating until all tuples have been generated.
*
* @param {ArrayLikeObject} x - input array
* @param {Collection} x - input array
* @param {NonNegativeInteger} n - power
* @returns {Array<Array>} list of ordered tuples comprising the Cartesian product
*
Expand All @@ -48,6 +49,7 @@ var pow = require( '@stdlib/math/base/special/pow' );
* // returns [ [ 1, 1 ], [ 1, 2 ], [ 2, 1 ], [ 2, 2 ] ]
*/
function cartesianPower( x, n ) {
var get;
var out;
var tmp;
var idx;
Expand All @@ -62,6 +64,9 @@ function cartesianPower( x, n ) {
if ( N <= 0 || n <= 0 ) {
return [];
}
// Resolve an array element accessor:
get = resolveGetter( x );

// Compute the total number of ordered tuples:
len = pow( N, n );

Expand All @@ -84,7 +89,7 @@ function cartesianPower( x, n ) {
// Generate the next ordered tuple...
tmp = [];
for ( j = 0; j < n; j++ ) {
tmp.push( x[ idx[ j ] ] );
tmp.push( get( x, idx[ j ] ) );
}
out.push( tmp );
}
Expand Down
76 changes: 74 additions & 2 deletions base/cartesian-power/test/test.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
// MODULES //

var tape = require( 'tape' );
var toAccessorArray = require( './../../../base/to-accessor-array' );
var cartesianPower = require( './../lib' );


Expand Down Expand Up @@ -84,7 +85,7 @@ tape( 'the function returns the Cartesian power (n=2)', function test( t ) {
t.end();
});

tape( 'the function returns the Cartesian power (n=3)', function test( t ) {
tape( 'the function returns the Cartesian power (n=3; indexed)', function test( t ) {
var expected;
var actual;

Expand Down Expand Up @@ -140,7 +141,63 @@ tape( 'the function returns the Cartesian power (n=3)', function test( t ) {
t.end();
});

tape( 'the function returns an empty array if provided an empty array', function test( t ) {
tape( 'the function returns the Cartesian power (n=3; accessor)', function test( t ) {
var expected;
var actual;

actual = cartesianPower( toAccessorArray( [ 1, 2 ] ), 3 );
expected = [
[ 1, 1, 1 ],
[ 1, 1, 2 ],
[ 1, 2, 1 ],
[ 1, 2, 2 ],
[ 2, 1, 1 ],
[ 2, 1, 2 ],
[ 2, 2, 1 ],
[ 2, 2, 2 ]
];
t.deepEqual( actual, expected, 'returns expected value' );

actual = cartesianPower( toAccessorArray( [ 1 ] ), 3 );
expected = [ [ 1, 1, 1 ] ];
t.deepEqual( actual, expected, 'returns expected value' );

actual = cartesianPower( toAccessorArray( [ 1, 2, 3 ] ), 3 );
expected = [
[ 1, 1, 1 ],
[ 1, 1, 2 ],
[ 1, 1, 3 ],
[ 1, 2, 1 ],
[ 1, 2, 2 ],
[ 1, 2, 3 ],
[ 1, 3, 1 ],
[ 1, 3, 2 ],
[ 1, 3, 3 ],
[ 2, 1, 1 ],
[ 2, 1, 2 ],
[ 2, 1, 3 ],
[ 2, 2, 1 ],
[ 2, 2, 2 ],
[ 2, 2, 3 ],
[ 2, 3, 1 ],
[ 2, 3, 2 ],
[ 2, 3, 3 ],
[ 3, 1, 1 ],
[ 3, 1, 2 ],
[ 3, 1, 3 ],
[ 3, 2, 1 ],
[ 3, 2, 2 ],
[ 3, 2, 3 ],
[ 3, 3, 1 ],
[ 3, 3, 2 ],
[ 3, 3, 3 ]
];
t.deepEqual( actual, expected, 'returns expected value' );

t.end();
});

tape( 'the function returns an empty array if provided an empty array (indexed)', function test( t ) {
var actual;

actual = cartesianPower( [], 1 );
Expand All @@ -155,6 +212,21 @@ tape( 'the function returns an empty array if provided an empty array', function
t.end();
});

tape( 'the function returns an empty array if provided an empty array (accessors)', function test( t ) {
var actual;

actual = cartesianPower( toAccessorArray( [] ), 1 );
t.deepEqual( actual, [], 'returns expected value' );

actual = cartesianPower( toAccessorArray( [] ), 2 );
t.deepEqual( actual, [], 'returns expected value' );

actual = cartesianPower( toAccessorArray( [] ), 3 );
t.deepEqual( actual, [], 'returns expected value' );

t.end();
});

tape( 'the function returns an empty array if provided a power less than or equal to zero', function test( t ) {
var actual;

Expand Down
104 changes: 104 additions & 0 deletions cartesian-power/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<!--
@license Apache-2.0
Copyright (c) 2024 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.
-->

# cartesianPower

> Return the [Cartesian power][cartesian-product].
<section class="usage">

## Usage

```javascript
var cartesianPower = require( '@stdlib/array/cartesian-power' );
```

#### cartesianPower( x, n )

Returns the [Cartesian power][cartesian-product].

```javascript
var x = [ 1, 2 ];

var out = cartesianPower( x, 2 );
// returns [ [ 1, 1 ], [ 1, 2 ], [ 2, 1 ], [ 2, 2 ] ]
```

If provided an empty array, the function returns an empty array.

```javascript
var out = cartesianPower( [], 2 );
// returns []
```

If `n` is less than or equal to zero, the function returns an empty array.

```javascript
var out = cartesianPower( [ 1, 2 ], 0 );
// returns []
```

</section>

<!-- /.usage -->

<section class="notes">

</section>

<!-- /.notes -->

<section class="examples">

## Examples

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

```javascript
var linspace = require( '@stdlib/array/linspace' );
var cartesianPower = require( '@stdlib/array/cartesian-power' );

var x = linspace( 0, 5, 6 );

var out = cartesianPower( x, 3 );
// returns [ [ 0, 0, 0 ], [ 0, 0, 1 ], ..., [ 5, 5, 4 ], [ 5, 5, 5 ] ]
```

</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">

[cartesian-product]: https://en.wikipedia.org/wiki/Cartesian_product

</section>

<!-- /.links -->
52 changes: 52 additions & 0 deletions cartesian-power/benchmark/benchmark.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2024 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 isArrayArray = require( '@stdlib/assert/is-array-array' );
var zeroTo = require( './../../zero-to' );
var pkg = require( './../package.json' ).name;
var cartesianPower = require( './../lib' );


// MAIN //

bench( pkg+':exponent=2,len=100', function benchmark( b ) {
var x;
var i;
var v;

x = zeroTo( 10 );

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
v = cartesianPower( x, 2 );
if ( typeof v !== 'object' ) {
b.fail( 'should return an array' );
}
}
b.toc();
if ( !isArrayArray( v ) ) {
b.fail( 'should return an array of arrays' );
}
b.pass( 'benchmark finished' );
b.end();
});
Loading

0 comments on commit f330b15

Please sign in to comment.