@stdlib/dstructs-named-typed-tuple 0.1.0

package/docs/types/index.d.ts

@@ -0,0 +1,1529 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2021 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.
+*/
+
+// TypeScript Version: 4.1
+
+/* eslint-disable max-lines */
+
+/// <reference types="@stdlib/types"/>
+
+import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter';
+import { TypedArray } from '@stdlib/types/array';
+
+// Define a union type representing both iterable and non-iterable iterators:
+type Iterator = Iter | IterableIterator;
+
+type DType = 'float64' | 'float32' | 'int32' | 'uint32' | 'int16' | 'uint16' | 'int8' | 'uint8' | 'uint8c';
+
+/**
+* Interface defining options.
+*/
+interface Options {
+	/**
+	* Default data type (default: 'float64').
+	*/
+	dtype?: DType;
+
+	/**
+	* Tuple name (default: 'tuple').
+	*/
+	name?: string;
+}
+
+/**
+* Function invoked for each tuple element.
+*/
+type Nullary = () => void;
+
+/**
+* Function invoked for each tuple element.
+*
+* @param value - tuple element
+*/
+type Unary = ( value: number ) => void;
+
+/**
+* Function invoked for each tuple element.
+*
+* @param value - tuple element
+* @param index - tuple index
+*/
+type Binary = ( value: number, index: number ) => void;
+
+/**
+* Function invoked for each tuple element.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+*/
+type Ternary = ( value: number, index: number, field: string ) => void;
+
+/**
+* Function invoked for each tuple element.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+*/
+type Quaternary = ( value: any, index: number, field: string, tuple: Tuple ) => void;
+
+/**
+* Function invoked for each tuple element.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+*/
+type Callback = Nullary | Unary | Binary | Ternary | Quaternary;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @returns boolean indicating whether tuple element passes a test
+*/
+type NullaryPredicate = () => boolean;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @param value - tuple element
+* @returns boolean indicating whether tuple element passes a test
+*/
+type UnaryPredicate = ( value: number ) => boolean;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @returns boolean indicating whether tuple element passes a test
+*/
+type BinaryPredicate = ( value: number, index: number ) => boolean;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @returns boolean indicating whether tuple element passes a test
+*/
+type TernaryPredicate = ( value: number, index: number, field: string ) => boolean;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+* @returns boolean indicating whether tuple element passes a test
+*/
+type QuaternaryPredicate = ( value: any, index: number, field: string, tuple: Tuple ) => boolean;
+
+/**
+* Predicate function which tests tuple elements.
+*
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+* @returns boolean indicating whether tuple element passes a test
+*/
+type PredicateFunction = NullaryPredicate | UnaryPredicate | BinaryPredicate | TernaryPredicate | QuaternaryPredicate;
+
+/**
+* Function applied against an accumulator.
+*
+* @returns value assigned to the accumulator
+*/
+type NullaryReducer = () => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @returns value assigned to the accumulator
+*/
+type UnaryReducer = ( acc: any ) => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @param value - tuple element
+* @returns value assigned to the accumulator
+*/
+type BinaryReducer = ( acc: any, value: number ) => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @param value - tuple element
+* @param index - tuple index
+* @returns value assigned to the accumulator
+*/
+type TernaryReducer = ( acc: any, value: number, index: number ) => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @returns value assigned to the accumulator
+*/
+type QuaternaryReducer = ( acc: any, value: number, index: number, field: string ) => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+* @returns value assigned to the accumulator
+*/
+type QuinaryReducer = ( acc: any, value: number, index: number, field: string, tuple: Tuple ) => any;
+
+/**
+* Function applied against an accumulator.
+*
+* @param acc - accumulated result
+* @param value - tuple element
+* @param index - tuple index
+* @param field - tuple field name
+* @param tuple - tuple on which the method is invoked
+* @returns value assigned to the accumulator
+*/
+type Reducer = NullaryReducer | UnaryReducer | BinaryReducer | TernaryReducer | QuaternaryReducer | QuinaryReducer;
+
+/**
+* Function which specifies the sort order.
+*
+* ## Notes
+*
+* -   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.
+*
+*
+* @param a - first tuple value
+* @param b - second tuple value
+* @returns value determining the sort order
+*/
+type CompareFunction = ( a: number, b: number ) => number;
+
+/**
+* Callback invoked for each source element.
+*
+* @returns transformed value
+*/
+type FactoryNullary = () => number;
+
+/**
+* Callback invoked for each source element.
+*
+* @param value - source value
+* @returns transformed value
+*/
+type FactoryUnary = ( value: number ) => number;
+
+/**
+* Callback invoked for each source element.
+*
+* @param value - source value
+* @param index - source index
+* @returns transformed value
+*/
+type FactoryBinary = ( value: number, index: number ) => number;
+
+/**
+* Callback invoked for each source element.
+*
+* @param value - source value
+* @param index - source index
+* @param field - tuple field
+* @returns transformed value
+*/
+type FactoryTernary = ( value: number, index: number, field: string ) => number;
+
+/**
+* Callback invoked for each source element.
+*
+* @param value - source value
+* @param index - source index
+* @param field - tuple field
+* @returns transformed value
+*/
+type FactoryCallback = FactoryNullary | FactoryUnary | FactoryBinary | FactoryTernary;
+
+/**
+* Callback invoked for each field.
+*
+* @returns transformed value
+*/
+type FactoryObjectNullary = () => number;
+
+/**
+* Callback invoked for each field.
+*
+* @param value - source object tuple field value
+* @returns transformed value
+*/
+type FactoryObjectUnary = ( value: number ) => number;
+
+/**
+* Callback invoked for each field.
+*
+* @param value - source object tuple field value
+* @param field - source object tuple field name
+* @returns transformed value
+*/
+type FactoryObjectBinary = ( value: number, field: string ) => number;
+
+/**
+* Callback invoked for each field.
+*
+* @param value - source object tuple field value
+* @param field - source object tuple field name
+* @returns transformed value
+*/
+type FactoryObjectCallback = FactoryObjectNullary | FactoryObjectUnary | FactoryObjectBinary;
+
+/**
+* Named typed tuple.
+*/
+interface Tuple {
+	/**
+	* Size (in bytes) of each tuple element.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var nbytes = tuple.BYTES_PER_ELEMENT;
+	* // returns 8
+	*/
+	readonly BYTES_PER_ELEMENT: number;
+
+	/**
+	* Pointer to the underlying data buffer.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var buf = tuple.buffer;
+	* // returns <ArrayBuffer>
+	*/
+	readonly buffer: ArrayBuffer;
+
+	/**
+	* Length (in bytes) of the tuple.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var nbytes = tuple.byteLength;
+	* // returns 16
+	*/
+	readonly byteLength: number;
+
+	/**
+	* Offset (in bytes) of a tuple from the start of its underlying `ArrayBuffer`.
+	*
+	* @example
+	* var ArrayBuffer = require( '@stdlib/array-buffer' );
+	*
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var offset = tuple.byteOffset;
+	* // returns 0
+	*
+	* var buf = new ArrayBuffer( 64 );
+	* tuple = factory( buf, 32 );
+	*
+	* offset = tuple.byteOffset;
+	* // returns 32
+	*/
+	readonly byteOffset: number;
+
+	/**
+	* Number of tuple elements.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var len = tuple.length;
+	* // returns 2
+	*/
+	readonly length: number;
+
+	/**
+	* Tuple name.
+	*
+	* @example
+	* // Create a tuple factory which generates tuples having the default tuple name:
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var n = tuple.name;
+	* // returns 'tuple'
+	*
+	* // Create a tuple factory which generates tuples having a custom tuple name:
+	* var opts = {
+	*     'name': 'Point'
+	* };
+	* factory = namedtypedtuple( [ 'x', 'y' ], opts );
+	*
+	* tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* n = tuple.name;
+	* // returns 'Point'
+	*/
+	readonly name: string;
+
+	/**
+	* Returns the list of tuple fields.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var fields = tuple.fields;
+	* // returns [ 'x', 'y' ]
+	*/
+	readonly fields: Array<string>;
+
+	/**
+	* Returns the list of tuple fields in index order.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* // Sort tuple elements in ascending order:
+	* tuple.sort();
+	*
+	* // Get the list of tuple fields:
+	* var fields = tuple.fields;
+	* // returns [ 'x', 'y' ]
+	*
+	* // Get the list of tuple fields in index order:
+	* fields = tuple.orderedFields;
+	* // returns [ 'y', 'x' ]
+	*/
+	readonly orderedFields: Array<string>;
+
+	/**
+	* Copies a sequence of elements within the tuple starting at `start` and ending at `end` (non-inclusive) to the position starting at `target`.
+	*
+	* @param target - target start index position
+	* @param start - source start index position
+	* @param end - source end index position (default: tuple.length)
+	* @returns modified tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z', 'w', 'v' ] );
+	*
+	* var tuple = factory( [ 2.0, -2.0, 1.0, -1.0, 1.0 ] );
+	*
+	* var x = tuple.x;
+	* // returns 2.0
+	*
+	* var y = tuple.y;
+	* // returns -2.0
+	*
+	* // Copy the last two elements to the first two elements:
+	* tuple.copyWithin( 0, 3 );
+	*
+	* x = tuple.x;
+	* // returns -1.0
+	*
+	* y = tuple.y;
+	* // returns 1.0
+	*/
+	copyWithin( target: number, start: number, end?: number ): Tuple;
+
+	/**
+	* Returns an iterator for iterating over tuple key-value pairs.
+	*
+	* @returns iterator for iterating over tuple key-value pairs
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* // Create an iterator:
+	* var it = tuple.entries();
+	*
+	* // Iterate over key-value pairs...
+	* var v = it.next().value;
+	* // returns [ 0, 'x', 1.0 ]
+	*
+	* v = it.next().value;
+	* // returns [ 1, 'y', -1.0 ]
+	*
+	* var bool = it.next().done;
+	* // returns true
+	*/
+	entries(): Iterator;
+
+	/**
+	* Tests whether all tuple elements pass a test implemented by a `predicate` function.
+	*
+	* @param predicate - predicate function which tests tuple elements
+	* @param thisArg - callback execution context
+	* @returns boolean indicating whether all tuple elements pass.
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v >= 0.0 );
+	* }
+	*
+	* var bool = tuple.every( predicate );
+	* // returns false
+	*/
+	every( predicate: PredicateFunction, thisArg?: any ): boolean;
+
+	/**
+	* Returns the field of the first tuple element strictly equal to a search element.
+	*
+	* @param searchElement - search element
+	* @param fromIndex - tuple index from which to begin searching; if provided a negative value, the method resolves the start index relative to the last tuple element (default: 0)
+	* @returns tuple field
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var field = tuple.fieldOf( -1.0 );
+	* // returns 'z'
+	*
+	* field = tuple.fieldOf( 2.0 );
+	* // returns undefined
+	*/
+	fieldOf( searchElement: number, fromIndex?: number ): string | undefined;
+
+	/**
+	* Fills a tuple from a `start` index to an `end` index (non-inclusive) with a provided `value`.
+	*
+	* @param value - fill value
+	* @param start - start index; if less than zero, the start index is resolved relative to the last tuple element
+	* @param end - end index (non-inclusive); if less than zero, the end index is resolved relative to the last tuple element
+	* @returns modified tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory();
+	*
+	* // Set all tuple elements to the same value:
+	* tuple.fill( 2.0 );
+	*
+	* var x = tuple.x;
+	* // returns 2.0
+	*
+	* var y = tuple.y;
+	* // returns 2.0
+	*
+	* // Set all tuple elements starting from the first index to the same value:
+	* tuple.fill( 3.0, 1 );
+	*
+	* x = tuple.x;
+	* // returns 2.0
+	*
+	* y = tuple.y;
+	* // returns 3.0
+	*
+	* // Set all tuple elements, except the last element, to the same value:
+	* tuple.fill( 4.0, 0, tuple.length-1 );
+	*
+	* x = tuple.x;
+	* // returns 4.0
+	*
+	* y = tuple.y;
+	* // returns 3.0
+	*/
+	fill( value: number, start?: number, end?: number ): Tuple;
+
+	/**
+	* Creates a new tuple (of the same data type as the host tuple) which includes those elements for which a `predicate` function returns a truthy value.
+	*
+	* @param predicate - predicate function which filters tuple elements
+	* @param thisArg - callback execution context
+	* @returns a new named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var p1 = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v >= 0.0 );
+	* }
+	*
+	* var p2 = p1.filter( predicate );
+	*
+	* var f = p2.fields;
+	* // returns [ 'x', 'y' ]
+	 */
+	filter( predicate: PredicateFunction, thisArg?: any ): Tuple;
+
+	/**
+	* Returns the first tuple element for which a provided `predicate` function returns a truthy value.
+	*
+	* @param predicate - predicate function which tests tuple elements
+	* @param thisArg - callback execution context
+	* @returns tuple element
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v < 0.0 );
+	* }
+	*
+	* var v = tuple.find( predicate );
+	* // returns -1.0
+	*/
+	find( predicate: PredicateFunction, thisArg?: any ): number | undefined;
+
+	/**
+	* Returns the field of the first tuple element for which a provided `predicate` function returns a truthy value.
+	*
+	* @param predicate - predicate function which tests tuple elements
+	* @param thisArg - callback execution context
+	* @returns tuple field
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v < 0.0 );
+	* }
+	*
+	* var field = tuple.findField( predicate );
+	* // returns 'z'
+	*/
+	findField( predicate: PredicateFunction, thisArg?: any ): string | undefined;
+
+	/**
+	* Returns the index of the first tuple element for which a provided `predicate` function returns a truthy value.
+	*
+	* @param predicate - predicate function which tests tuple elements
+	* @param thisArg - callback execution context
+	* @returns tuple index
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v < 0.0 );
+	* }
+	*
+	* var idx = tuple.findIndex( predicate );
+	* // returns 2
+	*/
+	findIndex( predicate: PredicateFunction, thisArg?: any ): number | undefined;
+
+	/**
+	* Invokes a callback for each tuple element.
+	*
+	* @param fcn - function to invoke for each tuple element
+	* @param thisArg - callback execution context
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = '';
+	*
+	* function fcn( v, i, f ) {
+	*     str += f + '=' + v;
+	*     if ( i < tuple.length-1 ) {
+	*     	str += ' ';
+	*     }
+	* }
+	*
+	* tuple.forEach( fcn );
+	*
+	* console.log( str );
+	* // => 'x=1 y=0 z=-1'
+	*/
+	forEach( fcn: Callback, thisArg?: any ): void;
+
+	/**
+	* Returns a `boolean` indicating whether a tuple includes a search element.
+	*
+	* @param searchElement - search element
+	* @param fromIndex - tuple index from which to begin searching; if provided a negative value, the method resolves the start index relative to the last tuple element (default: 0)
+	* @returns boolean indicating whether a tuple includes a search element
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var bool = tuple.includes( -1.0 );
+	* // returns true
+	*
+	* bool = tuple.includes( 2.0 );
+	* // returns false
+	*/
+	includes( searchElement: number, fromIndex?: number ): boolean;
+
+	/**
+	* Returns the index of the first tuple element strictly equal to a search element.
+	*
+	* @param searchElement - search element
+	* @param fromIndex - tuple index from which to begin searching; if provided a negative value, the method resolves the start index relative to the last tuple element (default: 0)
+	* @returns tuple index
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var idx = tuple.indexOf( -1.0 );
+	* // returns 2
+	*
+	* idx = tuple.indexOf( 2.0 );
+	* // returns -1
+	*/
+	indexOf( searchElement: number, fromIndex?: number ): number;
+
+	/**
+	* Converts a tuple index to a field name.
+	*
+	* @param ind - tuple index; if less than zero, the method resolves the index relative to the last tuple element
+	* @returns field name
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var field = tuple.ind2key( 1 );
+	* // returns 'y'
+	*
+	* field = tuple.ind2key( 100 );
+	* // returns undefined
+	*/
+	ind2key( ind: number ): string | undefined;
+
+	/**
+	* Serializes a tuple by joining all tuple elements as a string.
+	*
+	* @param separator - string delineating tuple elements (default: ',')
+	* @returns tuple serialized as a string
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = tuple.join();
+	* // returns '1,0,-1'
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = tuple.join( '|' );
+	* // returns '1|0|-1'
+	*/
+	join( separator?: string ): string;
+
+	/**
+	* Returns an iterator for iterating over tuple keys.
+	*
+	* @returns iterator for iterating over tuple keys
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* // Create an iterator:
+	* var it = tuple.keys();
+	*
+	* // Iterate over keys...
+	* var v = it.next().value;
+	* // returns [ 0, 'x' ]
+	*
+	* v = it.next().value;
+	* // returns [ 1, 'y' ]
+	*
+	* var bool = it.next().done;
+	* // returns true
+	*/
+	keys(): Iterator;
+
+	/**
+	* Converts a field name to a tuple index.
+	*
+	* @param field - tuple field name
+	* @returns tuple index
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var idx = tuple.key2ind( 'y' );
+	* // returns 1
+	*
+	* idx = tuple.key2ind( 'foo' );
+	* // returns -1
+	*/
+	key2ind( field: string ): number;
+
+	/**
+	* Returns the field of the last tuple element strictly equal to a search element, iterating from right to left.
+	*
+	* @param searchElement - search element
+	* @param fromIndex - tuple index from which to begin searching; if provided a negative value, the method resolves the start index relative to the last tuple element (default: -1)
+	* @returns tuple field
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z', 'w', 'v' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0, 0.0, 1.0 ] );
+	*
+	* var field = tuple.lastFieldOf( 0.0 );
+	* // returns 'w'
+	*
+	* field = tuple.lastFieldOf( 2.0 );
+	* // returns undefined
+	*/
+	lastFieldOf( searchElement: number, fromIndex?: number ): string | undefined;
+
+	/**
+	* Returns the index of the last tuple element strictly equal to a search element, iterating from right to left.
+	*
+	* @param searchElement - search element
+	* @param fromIndex - tuple index from which to begin searching; if provided a negative value, the method resolves the start index relative to the last tuple element (default: -1)
+	* @returns tuple index
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z', 'w', 'v' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0, 0.0, 1.0 ] );
+	*
+	* var idx = tuple.lastIndexOf( 0.0 );
+	* // returns 3
+	*
+	* idx = tuple.lastIndexOf( 2.0 );
+	* // returns -1
+	*/
+	lastIndexOf( searchElement: number, fromIndex?: number ): number | undefined;
+
+	/**
+	* Maps each tuple element to an element in a new tuple having the same data type as the host tuple.
+	*
+	* @param fcn - function which maps tuple elements to elements in the new tuple
+	* @param thisArg - callback execution context
+	* @returns a new named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var p1 = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* function fcn( v ) {
+	*     return v * 2.0;
+	* }
+	*
+	* var p2 = p1.map( fcn );
+	*
+	* var x = p2.x;
+	* // returns 2.0
+	*
+	* var y = p2.y;
+	* // returns 0.0
+	*
+	* var z = p2.z;
+	* // returns -2.0
+	*/
+	map( fcn: Callback, thisArg?: any ): Tuple;
+
+	/**
+	* Applies a function against an accumulator and each element in a tuple and returns the accumulated result.
+	*
+	* ## Notes
+	*
+	* -   If provided an initial value, the method invokes a provided function with the initial value as the first argument and the first tuple element as the second argument.
+	* -   If not provided an initial value, the method invokes a provided function with the first tuple element as the first argument and the second tuple element as the second argument.
+	*
+	* @param fcn - function to apply
+	* @param initialValue - initial accumulation value
+	* @returns accumulated result
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 2.0, 0.0, -3.0 ] );
+	*
+	* function fcn( acc, v ) {
+	*     return acc + ( v*v );
+	* }
+	*
+	* var v = tuple.reduce( fcn );
+	* // returns 11.0
+	*/
+	reduce( fcn: Reducer, initialValue?: any ): any;
+
+	/**
+	* Applies a function against an accumulator and each element in a tuple and returns the accumulated result, iterating from right to left.
+	*
+	* ## Notes
+	*
+	* -   If provided an initial value, the method invokes a provided function with the initial value as the first argument and the last tuple element as the second argument.
+	* -   If not provided an initial value, the method invokes a provided function with the last tuple element as the first argument and the second-to-last tuple element as the second argument.
+	*
+	* @param fcn - function to apply
+	* @param initialValue - initial accumulation value
+	* @returns accumulated result
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 2.0, 0.0, -3.0 ] );
+	*
+	* function fcn( acc, v ) {
+	*     return acc + ( v*v );
+	* }
+	*
+	* var v = tuple.reduceRight( fcn );
+	* // returns 1.0
+	*/
+	reduceRight( fcn: Reducer, initialValue?: any ): any;
+
+	/**
+	* Reverses a tuple **in-place** (thus mutating the tuple on which the method is invoked).
+	*
+	* @returns modified tuple
+	*
+	* @example
+	* 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:
+	* tuple.reverse();
+	*
+	* var fields = tuple.orderedFields;
+	* // returns [ 'z', 'y', 'x' ]
+	*
+	* var z = tuple[ 0 ];
+	* // returns -3.0
+	*
+	* // Tuple field assignments do NOT change:
+	* x = tuple.x;
+	* // returns 2.0
+	*/
+	reverse(): Tuple;
+
+	/**
+	* Sets tuple elements.
+	*
+	* @param arr - source array containing tuple values to set
+	* @param offset - tuple index at which to start writing values (default: 0)
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var y = tuple[ 1 ];
+	* // returns 0.0
+	*
+	* y = tuple.y;
+	* // returns 0.0
+	*
+	* // Set the first two tuple elements:
+	* tuple.set( [ -2.0, 2.0 ] );
+	*
+	* var x = tuple[ 0 ];
+	* // returns -2.0
+	*
+	* x = tuple.x;
+	* // returns -2.0
+	*
+	* y = tuple[ 1 ];
+	* // returns 2.0
+	*
+	* y = tuple.y;
+	* // returns 2.0
+	*/
+	set( arr: ArrayLike<number>, offset?: number ): void;
+
+	/**
+	* Copies tuple elements to a new tuple with the same underlying data type as the host tuple.
+	*
+	* @param begin - start element index (inclusive); if less than zero, the start index is resolved relative to the last tuple element (default: 0)
+	* @param end - end element index (exclusive); if less than zero, the end index is resolved relative to the last tuple element (default: tuple.length)
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var p1 = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var p2 = p1.slice();
+	*
+	* var bool = ( p1 === p2 );
+	* // returns false
+	*
+	* bool = ( p1.buffer === p2.buffer );
+	* // returns false
+	*
+	* var x = p2.x;
+	* // returns 1.0
+	*
+	* var y = p2.y;
+	* // returns 0.0
+	*
+	* var z = p2.z;
+	* // returns -1.0
+	*/
+	slice( begin?: number, end?: number ): Tuple;
+
+	/**
+	* Tests whether at least one tuple element passes a test implemented by a `predicate` function.
+	*
+	* @param predicate - predicate function which tests tuple elements
+	* @param thisArg - callback execution context
+	* @returns boolean indicating whether at least one tuple element passes
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* function predicate( v ) {
+	*     return ( v < 0.0 );
+	* }
+	*
+	* var bool = tuple.some( predicate );
+	* // returns true
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, 1.0 ] );
+	*
+	* function predicate( v ) {
+	*     this.count += 1;
+	*     return ( v < 0.0 );
+	* }
+	*
+	* var ctx = {
+	*     'count': 0
+	* };
+	*
+	* var bool = tuple.some( predicate, ctx );
+	* // returns false
+	*
+	* var n = ctx.count;
+	* // returns 2
+	*/
+	some( predicate: PredicateFunction, thisArg?: any ): boolean;
+
+	/**
+	* Sorts a tuple **in-place** (thus mutating the tuple on which the method is invoked).
+	*
+	* ## Notes
+	*
+	* -   By default, the method sorts tuple elements in ascending order. To impose a custom order, provide a `compareFunction`.
+	*
+	* @param compareFunction - function which specifies the sort order; the default sort order is ascending order
+	* @returns modified tuple
+	*
+	* @example
+	* 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):
+	* tuple.sort();
+	*
+	* var fields = tuple.orderedFields;
+	* // returns [ 'y', 'z', 'x' ]
+	*
+	* var y = tuple[ 0 ];
+	* // returns -3.0
+	*
+	* // Tuple field assignments do NOT change:
+	* x = tuple.x;
+	* // returns 2.0
+	*
+	* @example
+	* 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):
+	* tuple.sort( descending );
+	*
+	* var fields = tuple.orderedFields;
+	* // returns [ 'x', 'z', 'y' ]
+	*
+	* var z = tuple[ 1 ];
+	* // returns 0.0
+	*
+	* // Tuple field assignments do NOT change:
+	* y = tuple.y;
+	* // returns -3.0
+	*/
+	sort( compareFunction?: CompareFunction ): Tuple;
+
+	/**
+	* Creates a new typed array over the same underlying ArrayBuffer and with the same underlying data type as the host tuple.
+	*
+	* @param begin - start element index (inclusive); if less than zero, the start index is resolved relative to the last tuple element (default: 0)
+	* @param end - end element index (exclusive); if less than zero, the end index is resolved relative to the last tuple element (default: tuple.length)
+	* @returns a new typed array view
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var arr = tuple.subarray();
+	* // returns <Float64Array>[ 1.0, 0.0, -1.0 ]
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var arr = tuple.subarray( 1 );
+	* // returns <Float64Array>[ 0.0, -1.0 ]
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var arr = tuple.subarray( 0, 2 );
+	* // returns <Float64Array>[ 1.0, 0.0 ]
+	*/
+	subarray( begin?: number, end?: number ): TypedArray;
+
+	/**
+	* Creates a new named typed tuple over the same underlying ArrayBuffer and with the same underlying data type as the host tuple.
+	*
+	* @param begin - start element index (inclusive); if less than zero, the start index is resolved relative to the last tuple element (default: 0)
+	* @param end - end element index (exclusive); if less than zero, the end index is resolved relative to the last tuple element (default: tuple.length)
+	* @returns a new named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var p1 = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var p2 = p1.subtuple();
+	*
+	* var bool = ( p1 === p2 );
+	* // returns false
+	*
+	* bool = ( p1.buffer === p2.buffer );
+	* // returns true
+	*
+	* var len = p2.length;
+	* // returns 3
+	*
+	* var x = p2.x;
+	* // returns 1.0
+	*
+	* var y = p2.y;
+	* // returns 0.0
+	*
+	* var z = p2.z;
+	* // returns -1.0
+	*/
+	subtuple( begin?: number, end?: number ): Tuple;
+
+	/**
+	* Serializes a tuple as JSON.
+	*
+	* @returns a tuple JSON representation
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ] );
+	*
+	* var obj = tuple.toJSON();
+	* // returns { 'x': 1.0, 'y': 0.0, 'z': -1.0 }
+	 */
+	toJSON(): any;
+
+	/**
+	* Serializes a tuple as a locale-specific `string`.
+	*
+	* @param locales - a BCP 47 language tag, or an array of such tags
+	* @param options - options
+	* @returns a typed array string representation
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = tuple.toLocaleString();
+	* // returns 'tuple(x=1, y=0, z=-1)'
+	*/
+	toLocaleString( locales: string | Array<string>, options?: any ): string;
+
+	/**
+	* Serializes a tuple as a `string`.
+	*
+	* ## Notes
+	*
+	* -   The returned `string` uses the tuple `name` as specified when creating a tuple factory.
+	*
+	* @returns a tuple string representation
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = tuple.toString();
+	* // returns 'tuple(x=1, y=0, z=-1)'
+	*
+	* @example
+	* var opts = {
+	*     'name': 'Point'
+	* };
+	*
+	* var factory = namedtypedtuple( [ 'x', 'y', 'z' ], opts );
+	*
+	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
+	*
+	* var str = tuple.toString();
+	* // returns 'Point(x=1, y=0, z=-1)'
+	*/
+	toString(): string;
+
+	/**
+	* Returns an iterator for iterating over tuple elements.
+	*
+	* @returns iterator for iterating over tuple elements
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* // Create an iterator:
+	* var it = tuple.values();
+	*
+	* // Iterate over tuple elements...
+	* var v = it.next().value;
+	* // returns 1.0
+	*
+	* v = it.next().value;
+	* // returns -1.0
+	*
+	* var bool = it.next().done;
+	* // returns true
+	*/
+	values(): Iterator;
+}
+
+/**
+* Interface defining a typed tuple factory.
+*/
+interface Factory {
+	/**
+	* Returns a named typed tuple of the specified data type.
+	*
+	* @param dtype - tuple data type (default data type if not supplied)
+	* @returns named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( 'int32' );
+	*
+	* var x = tuple.x;
+	* // returns 0
+	*
+	* x = tuple[ 0 ];
+	* // returns 0
+	*
+	* var y = tuple.y;
+	* // returns 0
+	*
+	* y = tuple[ 1 ];
+	* // returns 0
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory();
+	*
+	* var x = tuple.x;
+	* // returns 0.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 0.0
+	*
+	* var y = tuple.y;
+	* // returns 0.0
+	*
+	* y = tuple[ 1 ];
+	* // returns 0.0
+	*/
+	( dtype?: DType ): Tuple;
+
+	/**
+	* Creates a named typed tuple from a typed array, array-like object, or iterable.
+	*
+	* @param obj - typed array, array-like object, or iterable from which to generate a named typed tuple
+	* @param dtype - tuple data type
+	* @returns named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( [ 1.0, -1.0 ] );
+	*
+	* var x = tuple.x;
+	* // returns 1.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 1.0
+	*
+	* var y = tuple.y;
+	* // returns -1.0
+	*
+	* y = tuple[ 1 ];
+	* // returns -1.0
+	*
+	* @example
+	* var Float64Array = require( '@stdlib/array-float64' );
+	*
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory( new Float64Array( [ 1.0, -1.0 ] ) );
+	*
+	* var x = tuple.x;
+	* // returns 1.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 1.0
+	*
+	* var y = tuple.y;
+	* // returns -1.0
+	*
+	* y = tuple[ 1 ];
+	* // returns -1.0
+	*/
+	( obj: TypedArray | ArrayLike<number> | Iterable<number>, dtype?: DType ): Tuple;
+
+	/**
+	* Returns a named typed tuple view of an ArrayBuffer.
+	*
+	* @param buffer - underlying ArrayBuffer
+	* @param byteOffset - integer byte offset specifying the location of the first tuple element (default: 0)
+	* @param dtype - tuple data type
+	* @returns named typed tuple
+	*/
+	( buffer: ArrayBuffer, byteOffset?: number, dtype?: DType ): Tuple;
+
+	/**
+	* Creates a new named typed tuple from an array-like object or an iterable.
+	*
+	* @param src - source of tuple elements
+	* @param map - callback to invoke for each source element
+	* @param thisArg - callback execution context
+	* @returns named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory.from( [ 1.0, -1.0 ] );
+	*
+	* var x = tuple.x;
+	* // returns 1.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 1.0
+	*
+	* var y = tuple.y;
+	* // returns -1.0
+	*
+	* y = tuple[ 1 ];
+	* // returns -1.0
+	*/
+	from( src: ArrayLike<number> | Iterable<number>, map?: FactoryCallback, thisArg?: any ): Tuple;
+
+	/**
+	* Creates a new named typed tuple from an object containing tuple fields.
+	*
+	* @param obj - source object
+	* @param map - callback to invoke for each source object tuple field
+	* @param thisArg - callback execution context
+	* @returns named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var obj = {
+	*     'x': 1.0,
+	*     'y': -1.0
+	* };
+	*
+	* var tuple = factory.fromObject( obj );
+	*
+	* var x = tuple.x;
+	* // returns 1.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 1.0
+	*
+	* var y = tuple.y;
+	* // returns -1.0
+	*
+	* y = tuple[ 1 ];
+	* // returns -1.0
+	*/
+	fromObject( obj: any, map?: FactoryObjectCallback, thisArg?: any ): Tuple;
+
+	/**
+	* Creates a new named typed tuple from a variable number of arguments.
+	*
+	* @param elements - tuple elements
+	* @returns named typed tuple
+	*
+	* @example
+	* var factory = namedtypedtuple( [ 'x', 'y' ] );
+	*
+	* var tuple = factory.of( 1.0, -1.0 );
+	*
+	* var x = tuple.x;
+	* // returns 1.0
+	*
+	* x = tuple[ 0 ];
+	* // returns 1.0
+	*
+	* var y = tuple.y;
+	* // returns -1.0
+	*
+	* y = tuple[ 1 ];
+	* // returns -1.0
+	*/
+	of( ...elements: Array<number> ): Tuple;
+}
+
+/**
+* Returns a named typed tuple factory.
+*
+* @param names - field (property) names
+* @param options - options
+* @param options.dtype - default data type (default: 'float64')
+* @param options.name - tuple name (default: 'tuple')
+* @throws must provide distinct field names
+* @throws cannot provide a reserved field (property) name
+* @throws must provide valid options
+* @throws must provide a recognized data type
+* @returns factory function
+*
+* @example
+* var point = namedtypedtuple( [ 'x', 'y' ] );
+*
+* var p = point( [ 1.0, -1.0 ] );
+*
+* var x = p[ 0 ];
+* // returns 1.0
+*
+* x = p.x;
+* // returns 1.0
+*
+* var y = p[ 1 ];
+* // returns -1.0
+*
+* y = p.y;
+* // returns -1.0
+*/
+declare function namedtypedtuple( names: Array<string>, options?: Options ): Factory;
+
+
+// EXPORTS //
+
+export = namedtypedtuple;