feat: add missing typed array methods to dstructs/named-typed-tuple

lib/node_modules/@stdlib/dstructs/named-typed-tuple/README.md

@@ -1147,6 +1147,198 @@ var n = ctx.count;
 // returns 3
 ```
 
+<a name="method-find-last"></a>
+
+#### tuple.findLast( predicate\[, thisArg] )
+
+Returns the last tuple element for which a provided `predicate` function returns a truthy value.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < 1.0 );
+}
+
+var v = tuple.findLast( predicate );
+// returns -1.0
+```
+
+If a `predicate` function does not return a truthy value for any tuple element, the method returns `undefined`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < -10.0 );
+}
+
+var v = tuple.findLast( predicate );
+// returns undefined
+```
+
+A `predicate` function is provided four arguments:
+
+-   `value`: tuple element.
+-   `index`: tuple index.
+-   `field`: tuple field name.
+-   `tuple`: tuple on which the method is invoked.
+
+To set the callback execution context, provide a `thisArg`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    this.count += 1;
+    return ( v < 0.0 );
+}
+
+var ctx = {
+    'count': 0
+};
+
+var v = tuple.findLast( predicate, ctx );
+// returns -1.0
+
+var n = ctx.count;
+// returns 1
+```
+
+<a name="method-find-last-index"></a>
+
+#### tuple.findLastIndex( predicate\[, thisArg] )
+
+Returns the index of the last tuple element for which a provided `predicate` function returns a truthy value.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < 1.0 );
+}
+
+var idx = tuple.findLastIndex( predicate );
+// returns 2
+```
+
+If a `predicate` function does not return a truthy value for any tuple element, the method returns `-1`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < -10.0 );
+}
+
+var idx = tuple.findLastIndex( predicate );
+// returns -1
+```
+
+A `predicate` function is provided four arguments:
+
+-   `value`: tuple element.
+-   `index`: tuple index.
+-   `field`: tuple field name.
+-   `tuple`: tuple on which the method is invoked.
+
+To set the callback execution context, provide a `thisArg`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    this.count += 1;
+    return ( v < 0.0 );
+}
+
+var ctx = {
+    'count': 0
+};
+
+var idx = tuple.findLastIndex( predicate, ctx );
+// returns 2
+
+var n = ctx.count;
+// returns 1
+```
+
+<a name="method-find-last-field"></a>
+
+#### tuple.findLastField( predicate\[, thisArg] )
+
+Returns the field of the last tuple element for which a provided `predicate` function returns a truthy value.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < 1.0 );
+}
+
+var field = tuple.findLastField( predicate );
+// returns 'z'
+```
+
+If a `predicate` function does not return a truthy value for any tuple element, the method returns `undefined`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    return ( v < -10.0 );
+}
+
+var field = tuple.findLastField( predicate );
+// returns undefined
+```
+
+A `predicate` function is provided four arguments:
+
+-   `value`: tuple element.
+-   `index`: tuple index.
+-   `field`: tuple field name.
+-   `tuple`: tuple on which the method is invoked.
+
+To set the callback execution context, provide a `thisArg`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+
+function predicate( v ) {
+    this.count += 1;
+    return ( v < 0.0 );
+}
+
+var ctx = {
+    'count': 0
+};
+
+var field = tuple.findLastField( predicate, ctx );
+// returns 'z'
+
+var n = ctx.count;
+// returns 1
+```
+
 <a name="method-for-each"></a>
 
 #### tuple.forEach( fcn\[, thisArg] )
@@ -1644,6 +1836,39 @@ x = tuple.x;
 
 Invoking this method does **not** affect tuple field assignments.
 
+<a name="method-to-reversed"></a>
+
+#### tuple.toReversed()
+
+Returns a new tuple with elements in reversed order.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 2.0, 0.0, -3.0 ] );
+
+var x = tuple[ 0 ];
+// returns 2.0
+
+x = tuple.x;
+// returns 2.0
+
+// Reverse the tuple:
+var out = tuple.toReversed();
+
+var fields = out.orderedFields;
+// returns [ 'z', 'y', 'x' ]
+
+var z = out[ 0 ];
+// returns -3.0
+
+// Tuple field assignments do NOT change:
+x = out.x;
+// returns 2.0
+```
+
+Unlike [`reverse`](#method-reverse), this method does **not** mutate the host tuple.
+
 <a name="method-set"></a>
 
 #### tuple.set( arr\[, offset] )
@@ -1930,6 +2155,76 @@ The comparison function is provided two tuple elements, `a` and `b`, per invocat
 
 Invoking this method does **not** affect tuple field assignments.
 
+<a name="method-to-sorted"></a>
+
+#### tuple.toSorted( \[compareFunction] )
+
+Returns a new tuple with elements sorted in ascending order.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 2.0, -3.0, 0.0 ] );
+
+var x = tuple[ 0 ];
+// returns 2.0
+
+x = tuple.x;
+// returns 2.0
+
+// Sort the tuple (in ascending order):
+var out = tuple.toSorted();
+
+var fields = out.orderedFields;
+// returns [ 'y', 'z', 'x' ]
+
+var y = out[ 0 ];
+// returns -3.0
+
+// Tuple field assignments do NOT change:
+x = out.x;
+// returns 2.0
+```
+
+By default, the method sorts tuple elements in ascending order. To impose a custom order, provide a `compareFunction`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 2.0, -3.0, 0.0 ] );
+
+var x = tuple[ 0 ];
+// returns 2.0
+
+x = tuple.x;
+// returns 2.0
+
+function descending( a, b ) {
+    return b - a;
+}
+
+// Sort the tuple (in descending order):
+var out = tuple.toSorted( descending );
+
+var fields = out.orderedFields;
+// returns [ 'x', 'z', 'y' ]
+
+var z = out[ 1 ];
+// returns 0.0
+
+// Tuple field assignments do NOT change:
+var y = out.y;
+// returns -3.0
+```
+
+The comparison function is provided two tuple elements, `a` and `b`, per invocation, and its return value determines the sort order as follows:
+
+-   If the comparison function returns a value **less** than zero, then the method sorts `a` to an index lower than `b` (i.e., `a` should come **before** `b`).
+-   If the comparison function returns a value **greater** than zero, then the method sorts `a` to an index higher than `b` (i.e., `b` should come **before** `a`).
+-   If the comparison function returns **zero**, then the relative order of `a` and `b` _should_ remain unchanged.
+
+Unlike [`sort`](#method-sort), this method does **not** mutate the host tuple.
+
 <a name="method-subarray"></a>
 
 #### tuple.subarray( \[begin\[, end]] )
@@ -2185,6 +2480,46 @@ var bool = it.next().done;
 // returns true
 ```
 
+<a name="method-with"></a>
+
+#### tuple.with( index, value )
+
+Returns a new tuple with the element at the specified `index` replaced with a provided `value`.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 2.0, 3.0 ] );
+
+var out = tuple.with( 1, 99.0 );
+
+var v = out[ 0 ];
+// returns 1.0
+
+v = out[ 1 ];
+// returns 99.0
+
+v = out[ 2 ];
+// returns 3.0
+
+// The original tuple is not mutated:
+v = tuple[ 1 ];
+// returns 2.0
+```
+
+When an `index` is negative, the index is resolved relative to the last tuple element.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 2.0, 3.0 ] );
+
+var out = tuple.with( -1, 99.0 );
+
+var v = out[ 2 ];
+// returns 99.0
+```
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/dstructs/named-typed-tuple/benchmark/benchmark.copy_within.js

@@ -21,13 +21,14 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var namedtypedtuple = require( './../lib' );
 
 
 // MAIN //
 
-bench( pkg+':copyWithin', function benchmark( b ) {
+bench( format( '%s:copyWithin', pkg ), function benchmark( b ) {
 	var Point;
 	var p;
 	var i;

lib/node_modules/@stdlib/dstructs/named-typed-tuple/benchmark/benchmark.copy_within.length.js

@@ -22,6 +22,7 @@
 
 var bench = require( '@stdlib/bench' );
 var pow = require( '@stdlib/math/base/special/pow' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var namedtypedtuple = require( './../lib' );
 
@@ -97,7 +98,7 @@ function main() {
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
 		f = createBenchmark( len );
-		bench( pkg+':copyWithin:len='+len, f );
+		bench( format( '%s:copyWithin:len=%d', pkg, len ), f );
 	}
 }