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

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

@@ -645,6 +645,29 @@ fields = tuple.orderedFields;
 // returns [ 'y', 'x' ]
 ```
 
+<a name="method-at"></a>
+
+#### tuple.at( index )
+
+Returns the tuple element at the specified index.
+
+```javascript
+var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+
+var tuple = factory( [ 1.0, 2.0, 3.0 ] );
+
+var v = tuple.at( 0 );
+// returns 1.0
+
+v = tuple.at( -1 );
+// returns 3.0
+
+v = tuple.at( 100 );
+// returns undefined
+```
+
+If provided an out-of-bounds index, the method returns `undefined`. When `index` is negative, the method resolves the element relative to the last tuple element.
+
 <a name="method-copy-within"></a>
 
 #### tuple.copyWithin( target, start\[, end] )
@@ -1147,6 +1170,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-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-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-for-each"></a>
 
 #### tuple.forEach( fcn\[, thisArg] )
@@ -2130,6 +2345,109 @@ var str = tuple.toLocaleString();
 // returns 'tuple(x=1, y=0, z=-1)'
 ```
 
+<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-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-to-string"></a>
 
 #### tuple.toString()
@@ -2185,6 +2503,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 -->