Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Features
 
+-   [`05cf2e6`](https://github.com/stdlib-js/stdlib/commit/05cf2e6e36c42b9db322e14f5bc78adf4d3901f9) - add support for returning empty tuples
 -   [`5d9761c`](https://github.com/stdlib-js/stdlib/commit/5d9761cfdea3389f82ca75aa262a9fc3ddf89439) - implement `toLocaleString` method in `dstructs/named-typed-tuple` [(#8009)](https://github.com/stdlib-js/stdlib/pull/8009)
 -   [`54f310f`](https://github.com/stdlib-js/stdlib/commit/54f310fb122b05038de174d03acbec6d2f84a5a9) - add `dstructs/named-typed-tuple`
 
@@ -35,6 +36,7 @@ This release closes the following issue:
 
 <details>
 
+-   [`05cf2e6`](https://github.com/stdlib-js/stdlib/commit/05cf2e6e36c42b9db322e14f5bc78adf4d3901f9) - **feat:** add support for returning empty tuples _(by Athan Reines)_
 -   [`9629e2e`](https://github.com/stdlib-js/stdlib/commit/9629e2ee35e901567a51fcd79e2c13156ed46053) - **test:** add tests for `slice` method in `dstructs/named-typed-tuple` [(#8057)](https://github.com/stdlib-js/stdlib/pull/8057) _(by Gaurav Kaushik, Athan Reines)_
 -   [`d8ad76b`](https://github.com/stdlib-js/stdlib/commit/d8ad76b37fa2b01cd66585f6389f415f61246a63) - **test:** add tests for `toJSON` method in `dstructs/named-typed-tuple` [(#8049)](https://github.com/stdlib-js/stdlib/pull/8049) _(by Gaurav Kaushik, Athan Reines)_
 -   [`a540e07`](https://github.com/stdlib-js/stdlib/commit/a540e076b9bfeacd4c7e85add92d095f1ca042bf) - **test:** add tests for `forEach` method in `dstructs/named-typed-tuple` [(#8042)](https://github.com/stdlib-js/stdlib/pull/8042) _(by Gaurav Kaushik, Athan Reines)_

README.md

@@ -1831,6 +1831,19 @@ var y = p2.y;
 // returns 0.0
 ```
 
+If the method is unable to resolve indices to a non-empty tuple subsequence, the method returns an empty tuple.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var p1 = factory( [ 1.0, 0.0, -1.0 ] );
+
+var p2 = p1.slice( 10, -1 );
+
+var len = p2.length;
+// returns 0
+```
+
 <a name="method-some"></a>
 
 #### tuple.some( predicate\[, thisArg] )
@@ -2107,15 +2120,17 @@ var y = p2.y;
 // returns 0.0
 ```
 
-If the method is unable to resolve indices to a non-empty tuple subsequence, the method returns `null`.
+If the method is unable to resolve indices to a non-empty tuple subsequence, the method returns an empty tuple.
 
 ```javascript
 var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
 
 var p1 = factory( [ 1.0, 0.0, -1.0 ] );
 
 var p2 = p1.subtuple( 10, -1 );
-// returns null
+
+var len = p2.length;
+// returns 0
 ```
 
 <a name="method-to-json"></a>
@@ -2145,7 +2160,7 @@ var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
 var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
 
 var str = tuple.toLocaleString();
-// returns '1,0,-1'
+// returns 'tuple(x=1, y=0, z=-1)'
 ```
 
 <a name="method-to-string"></a>

dist/index.js

@@ -1144,7 +1144,7 @@ tuple.slice( [begin[, end]] )
     the host tuple.
 
     If the method is unable to resolve indices to a non-empty tuple subsequence,
-    the method returns `null`.
+    the method returns an empty typed array.
 
     Parameters
     ----------
@@ -1303,8 +1303,8 @@ tuple.subtuple( [begin[, end]] )
     Creates a new named typed tuple over the same underlying ArrayBuffer and
     with the same underlying data type as the host tuple.
 
-    If the function is unable to resolve indices to a non-empty tuple
-    subsequence, the function returns `null`.
+    If the method is unable to resolve indices to a non-empty tuple subsequence,
+    the method returns an empty typed array.
 
     Parameters
     ----------
@@ -1318,7 +1318,7 @@ tuple.subtuple( [begin[, end]] )
 
     Returns
     -------
-    tuple: TypedArray|null
+    tuple: TypedArray
         A new named typed tuple.
 
     Examples

dist/index.js.map

@@ -23,6 +23,7 @@
 // MODULES //
 
 var isStringArray = require( '@stdlib/assert-is-string-array' ).primitives;
+var isEmptyArrayLikeObject = require( '@stdlib/assert-is-empty-array-like-object' );
 var isString = require( '@stdlib/assert-is-string' ).isPrimitive;
 var isArrayBuffer = require( '@stdlib/assert-is-arraybuffer' );
 var isFunction = require( '@stdlib/assert-is-function' );
@@ -95,7 +96,7 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 	var opts;
 	var err;
 	var i;
-	if ( !isStringArray( names ) ) {
+	if ( !isStringArray( names ) && !isEmptyArrayLikeObject( names ) ) {
 		throw new TypeError( format( 'invalid argument. Must provide an array of strings. Value: `%s`.', names ) );
 	}
 	if ( !hasDistinctElements( names ) ) {
@@ -251,17 +252,6 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 			}
 		}
 
-		/**
-		* Returns the list of tuple fields.
-		*
-		* @private
-		* @memberof tuple
-		* @returns {StringArray} tuple fields
-		*/
-		function getFields() {
-			return fields.slice();
-		}
-
 		/**
 		* Returns the list of tuple fields in index order.
 		*
@@ -943,18 +933,14 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 		/**
 		* Copies elements to a new tuple with the same underlying data type as the host tuple.
 		*
-		* ## Notes
-		*
-		* -   If the function is unable to resolve indices to a non-empty tuple subsequence, the function returns `null`.
-		*
 		* @private
 		* @memberof tuple
 		* @param {integer} [begin=0] - start element index (inclusive)
 		* @param {integer} [end=tuple.length] - end element index (exclusive)
 		* @throws {TypeError} `this` must be the host tuple
 		* @throws {TypeError} first argument must be an integer
 		* @throws {TypeError} second argument must be an integer
-		* @returns {(TypedArray|null)} new tuple
+		* @returns {TypedArray} new tuple
 		*/
 		function slice( begin, end ) {
 			var tmp;
@@ -994,9 +980,6 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 					j = nfields;
 				}
 			}
-			if ( i >= j ) {
-				return null;
-			}
 			f = [];
 			tmp = [];
 			for ( ; i < j; i++ ) {
@@ -1117,18 +1100,14 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 		/**
 		* Creates a new tuple over the same underlying `ArrayBuffer` and with the same underlying data type as the host tuple.
 		*
-		* ## Notes
-		*
-		* -   If the function is unable to resolve indices to a non-empty tuple subsequence, the function returns `null`.
-		*
 		* @private
 		* @memberof tuple
 		* @param {integer} [begin=0] - start element index (inclusive)
 		* @param {integer} [end=tuple.length] - end element index (exclusive)
 		* @throws {TypeError} `this` must be the host tuple
 		* @throws {TypeError} first argument must be an integer
 		* @throws {TypeError} second argument must be an integer
-		* @returns {(TypedArray|null)} new tuple
+		* @returns {TypedArray} new tuple
 		*/
 		function subtuple( begin, end ) {
 			var f;
@@ -1168,8 +1147,8 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 					j = nfields;
 				}
 			}
-			if ( i >= j ) {
-				return null;
+			if ( j <= i ) {
+				return factory( [], opts )( tuple.buffer, tuple.byteOffset, dtype );
 			}
 			f = [];
 			for ( k = i; k < j; k++ ) {
@@ -1275,6 +1254,17 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 		}
 	}
 
+	/**
+	* Returns the list of tuple fields.
+	*
+	* @private
+	* @memberof tuple
+	* @returns {StringArray} tuple fields
+	*/
+	function getFields() {
+		return fields.slice();
+	}
+
 	// Note: keep the following methods in alphabetical order...
 
 	/**

docs/repl.txt

@@ -45,6 +45,7 @@
     "@stdlib/assert-has-own-property": "^0.2.2",
     "@stdlib/assert-is-arraybuffer": "^0.2.2",
     "@stdlib/assert-is-collection": "^0.2.2",
+    "@stdlib/assert-is-empty-array-like-object": "^0.2.2",
     "@stdlib/assert-is-function": "^0.2.2",
     "@stdlib/assert-is-integer": "^0.2.2",
     "@stdlib/assert-is-object": "^0.2.2",

lib/main.js

@@ -339,7 +339,7 @@ tape( 'the method supports negative indices', function test( t ) {
 	t.end();
 });
 
-tape( 'the method returns null if a resolved beginning index exceeds a resolved ending index', function test( t ) {
+tape( 'the method returns an empty tuple if a resolved beginning index exceeds a resolved ending index', function test( t ) {
 	var actual;
 	var Point;
 	var p;
@@ -348,11 +348,12 @@ tape( 'the method returns null if a resolved beginning index exceeds a resolved
 	p = new Point( [ 1, 2, 3, 4 ] );
 	actual = p.slice( 2, 0 );
 
-	t.strictEqual( actual, null, 'returns expected value' );
+	t.strictEqual( actual.length, 0, 'returns expected value' );
+	t.deepEqual( actual.fields, [], 'returns expected value' );
 	t.end();
 });
 
-tape( 'the method returns null if a resolved beginning index exceeds the maximum tuple index', function test( t ) {
+tape( 'the method returns an empty tuple if a resolved beginning index exceeds the maximum tuple index', function test( t ) {
 	var actual;
 	var Point;
 	var p;
@@ -361,11 +362,12 @@ tape( 'the method returns null if a resolved beginning index exceeds the maximum
 	p = new Point( [ 1, 2, 3 ] );
 	actual = p.slice( 5 );
 
-	t.strictEqual( actual, null, 'returns expected value' );
+	t.strictEqual( actual.length, 0, 'returns expected value' );
+	t.deepEqual( actual.fields, [], 'returns expected value' );
 	t.end();
 });
 
-tape( 'the method returns null if a resolved ending index is less than or equal to zero', function test( t ) {
+tape( 'the method returns an empty tuple if a resolved ending index is less than or equal to zero', function test( t ) {
 	var actual;
 	var Point;
 	var p;
@@ -374,9 +376,11 @@ tape( 'the method returns null if a resolved ending index is less than or equal
 	p = new Point( [ 1, 2, 3, 4 ] );
 
 	actual = p.slice( 2, -8 );
-	t.strictEqual( actual, null, 'returns expected value' );
+	t.strictEqual( actual.length, 0, 'returns expected value' );
+	t.deepEqual( actual.fields, [], 'returns expected value' );
 
 	actual = p.slice( 1, 0 );
-	t.strictEqual( actual, null, 'returns expected value' );
+	t.strictEqual( actual.length, 0, 'returns expected value' );
+	t.deepEqual( actual.fields, [], 'returns expected value' );
 	t.end();
 });