feat: add iter/cartesian-square

lib/node_modules/@stdlib/iter/cartesian-square/README.md

@@ -0,0 +1,133 @@
+<!--
+
+@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.
+
+-->
+
+# iterCartesianSquare
+
+> Create an iterator which generates the Cartesian square of an input array-like object.
+
+<section class="intro">
+
+</section>
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var iterCartesianSquare = require( '@stdlib/iter/cartesian-square' );
+```
+
+#### iterCartesianSquare( x )
+
+Returns an iterator which generates the Cartesian Square of an input array-like object.
+
+```javascript
+var x = ['a', 'b', 'c'];
+var pair;
+var cartesianSquare = iterCartesianSquare( x, n );
+
+for ( pair of cartesianSquare ) {
+    console.log( pair );
+}
+
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+The function expects only one argument x, an array-like object.
+The returned iterator will generate all possible combinations from the input array x.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+// Example : Generating Cartesian square of an array
+var x = [1, 2, 3];
+var cartesianSquare = iterCartesianSquare( x );
+var pair;
+
+for ( pair of cartesianSquare ) {
+    console.log( pair );
+}
+
+// Output:
+// [ 1, 1 ]
+// [ 1, 2 ]
+// [ 1, 3 ]
+// [ 2, 1 ]
+// [ 2, 2 ]
+// [ 2, 3 ]
+// [ 3, 1 ]
+// [ 3, 2 ]
+// [ 3, 3 ]
+
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- 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">
+
+<!-- <related-links> -->
+
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/iter/cartesian-square/benchmark/benchmark.js

@@ -0,0 +1,59 @@
+
+/**
+* @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 pkg = require('./../package.json').name;
+var iterCartesianSquare = require('./../lib');
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var iterator;
+	var arr = ['a', 'b', 'c'];
+	var v;
+	var i;
+
+	// Run the benchmark...
+	b.tic();
+	for (i = 0; i < b.iterations; i++) {
+		// Reset the iterator:
+		iterator = iterCartesianSquare(arr);
+		v = iterator.next();
+
+		// Iterate over the Cartesian square:
+		while (!v.done) {
+			if (v.done) {
+				b.fail('should iterate over all elements');
+			}
+			v = iterator.next();
+		}
+	}
+	b.toc();
+	if (v.done) {
+		b.pass('benchmark finished');
+	} else {
+		b.fail('should have finished iteration');
+	}
+	b.end();
+});

lib/node_modules/@stdlib/iter/cartesian-square/examples/index.js

@@ -0,0 +1,35 @@
+
+/**
+* @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';
+
+var iterCartesianSquare = require( './../lib' );
+
+// Create an array:
+var arr = [ 'a', 'b', 'c' ];
+
+// Create an iterator:
+var iter = iterCartesianSquare( arr );
+
+// Iterate over the Cartesian square:
+var v = iter.next();
+while ( !v.done ) {
+	console.log( v.value );
+	v = iter.next();
+}

lib/node_modules/@stdlib/iter/cartesian-square/lib/index.js

@@ -0,0 +1,45 @@
+/**
+* @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';
+
+/**
+* Create an iterator which returns Cartesian square.
+*
+* @module @stdlib/iter/cartesian-square
+*
+* @example
+* var iterCartesianSquare = require( '@stdlib/iter/cartesian-square' );
+*
+* var inputArray = [1, 2, 3];
+* var iterator = iterCartesianSquare( inputArray );
+*
+* var result;
+* while (!(result = iterator.next()).done) {
+*     console.log(result.value);
+* }
+*/
+
+// MODULES //
+
+var main = require('./main.js');
+
+
+// EXPORTS //
+
+module.exports = main;

lib/node_modules/@stdlib/iter/cartesian-square/lib/main.js

@@ -0,0 +1,115 @@
+/**
+* @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 setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
+var iteratorSymbol = require( '@stdlib/symbol/iterator' );
+var floor = require( '@stdlib/math/base/special/floor' );
+
+
+// MAIN //
+
+/**
+* Returns an iterator which generates the Cartesian square of an input array-like object.
+*
+* @param {ArrayLike} arr - input array
+* @throws {TypeError} must provide an array-like object
+* @returns {Iterator} iterator
+*
+* @example
+* var iter = iterCartesianSquare( [ 'a', 'b', 'c' ] );
+*
+* var v = iter.next().value;
+* // returns [ 'a', 'a' ]
+*
+* v = iter.next().value;
+* // returns [ 'a', 'b' ]
+*
+* // ...
+*/
+function iterCartesianSquare( arr ) {
+	var iter;
+	var FLG;
+	var i;
+
+	if ( !Array.isArray( arr ) ) {
+		throw new TypeError( 'invalid argument. Must provide an array-like object. Value: `' + arr + '`.' );
+	}
+	iter = {};
+	FLG = false;
+	i = 0;
+	setReadOnly( iter, 'next', next );
+	setReadOnly( iter, 'return', finish );
+
+	if ( iteratorSymbol ) {
+		setReadOnly( iter, iteratorSymbol, factory );
+	}
+	return iter;
+
+	/**
+	* Returns an iterator protocol-compliant object containing the next iterated value.
+* @private
+* @returns {Object} iterator result
+*/
+	function next() {
+		var v;
+		if ( FLG ) {
+			return {
+				'done': true
+			};
+		}
+		v = [ arr[ floor( i / arr.length ) ], arr[ i % arr.length ] ];
+		i += 1;
+		if ( i >= arr.length * arr.length ) {
+			FLG = true;
+		}
+		return {
+			'value': v,
+			'done': false
+		};
+	}
+
+	/**
+	* Finishes an iterator.
+* @private
+* @returns {Object} iterator result
+*/
+	function finish() {
+		FLG = true;
+		return {
+			'done': true
+		};
+	}
+
+	/**
+	* Returns a new iterator.
+* @private
+* @returns {Iterator} iterator
+*/
+	function factory() {
+		return iterCartesianSquare( arr );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = iterCartesianSquare;