Named Typed Tuple

Usage

var namedtypedtuple = require( '@stdlib/utils/named-typed-tuple' );

namedtypedtuple( fields[, options] )

Returns a named typed tuple factory.

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

The function accepts the following options:

• dtype: default tuple data type. If a data type is not provided to a named typed tuple factory, this option specifies the underlying tuple data type. The following data types are supported:

  • float64: double-precision floating-point numbers (IEEE 754).
  • float32: single-precision floating-point numbers (IEEE 754).
  • int32: 32-bit two's complement signed integers.
  • uint32: 32-bit unsigned integers.
  • int16: 16-bit two's complement signed integers.
  • uint16: 16-bit unsigned integers.
  • int8: 8-bit two's complement signed integers.
  • uint8: 8-bit unsigned integers.
  • uint8c: 8-bit unsigned integers clamped to 0-255.

  Default: 'float64'.

• name: tuple name. Default: 'tuple'.

Tuple Factory

factory()

Returns a named typed tuple of the default data type.

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

factory( dtype )

Returns a named typed tuple of the specified data type.

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

factory( typedarray[, dtype] )

Returns a named typed tuple from a typed array.

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

To override the default tuple data type (and potentially cast typed array values to another data type), provide a dtype.

var Float64Array = require( '@stdlib/array/float64' );

var factory = namedtypedtuple( [ 'x', 'y' ] );

// Cast double-precision floating-point numbers to signed 32-bit integers:
var tuple = factory( new Float64Array( [ 1.0, -1.0 ] ), 'int32' );

var x = tuple.x;
// returns 1

x = tuple[ 0 ];
// returns 1

var y = tuple.y;
// returns -1

y = tuple[ 1 ];
// returns -1

factory( obj[, dtype] )

Returns a named typed tuple from an array-like object or iterable.

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

To override the default tuple data type, provide a dtype.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ], 'int32' );

var x = tuple.x;
// returns 1

x = tuple[ 0 ];
// returns 1

var y = tuple.y;
// returns -1

y = tuple[ 1 ];
// returns -1

factory( buffer[, byteOffset][, dtype] )

Returns a named typed tuple view of an ArrayBuffer where the view length equals the number of tuple fields.

var ArrayBuffer = require( '@stdlib/array/buffer' );

var factory = namedtypedtuple( [ 'x', 'y' ] );

var buf = new ArrayBuffer( 32 );

// Create a tuple view of the first 16 bytes (8 bytes per double):
var tuple = factory( buf );

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

// Create a tuple view of the last 16 bytes:
tuple = factory( buf, 16 );

x = tuple.x;
// returns 0.0

x = tuple[ 0 ];
// returns 0.0

y = tuple.y;
// returns 0.0

y = tuple[ 1 ];
// returns 0.0

To override the default tuple data type, provide a dtype.

var ArrayBuffer = require( '@stdlib/array/buffer' );

var factory = namedtypedtuple( [ 'x', 'y' ] );

var buf = new ArrayBuffer( 16 );

// Create a tuple view of the first 8 bytes (4 bytes per float):
var tuple = factory( buf, 'float32' );

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

// Create a tuple view of the last 8 bytes:
tuple = factory( buf, 8, 'float32' );

x = tuple.x;
// returns 0.0

x = tuple[ 0 ];
// returns 0.0

y = tuple.y;
// returns 0.0

y = tuple[ 1 ];
// returns 0.0

factory.from( src[, map[, thisArg]] )

Creates a new named typed tuple from an array-like object or an iterable.

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

To invoke a function for each src value, provide a callback function.

var factory = namedtypedtuple( [ 'x', 'y' ] );

function mapFcn( v ) {
    return v * 2.0;
}

var tuple = factory.from( [ 1.0, -1.0 ], mapFcn );

var x = tuple.x;
// returns 2.0

x = tuple[ 0 ];
// returns 2.0

var y = tuple.y;
// returns -2.0

y = tuple[ 1 ];
// returns -2.0

A callback function is provided three arguments:

• value: source value
• index: source index
• field: tuple field

To set the callback execution context, provide a thisArg.

var factory = namedtypedtuple( [ 'x', 'y' ] );

function mapFcn( v ) {
    this.count += 1;
    return v * 2.0;
}

var ctx = {
    'count': 0
};

var tuple = factory.from( [ 1.0, -1.0 ], mapFcn, ctx );

var n = ctx.count;
// returns 2

factory.fromObject( obj[, map[, thisArg]] )

Creates a new named typed tuple from an object containing tuple fields.

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

To invoke a function for each src object tuple field, provide a callback function.

var factory = namedtypedtuple( [ 'x', 'y' ] );

function mapFcn( v ) {
    return v * 2.0;
}

var obj = {
    'x': 1.0,
    'y': -1.0
};

var tuple = factory.fromObject( obj, mapFcn );

var x = tuple.x;
// returns 2.0

x = tuple[ 0 ];
// returns 2.0

var y = tuple.y;
// returns -2.0

y = tuple[ 1 ];
// returns -2.0

A callback function is provided two arguments:

• value: source object tuple field value
• field: source object tuple field name

To set the callback execution context, provide a thisArg.

var factory = namedtypedtuple( [ 'x', 'y' ] );

function mapFcn( v ) {
    this.count += 1;
    return v * 2.0;
}

var obj = {
    'x': 1.0,
    'y': -1.0
};

var ctx = {
    'count': 0
};

var tuple = factory.fromObject( obj, mapFcn, ctx );

var n = ctx.count;
// returns 2

factory.of( element0[, element1[, ...elementN]] )

Creates a new named typed tuple from a variable number of arguments.

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

Tuple

tuple.BYTES_PER_ELEMENT

Size (in bytes) of each tuple element.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ] );

var nbytes = tuple.BYTES_PER_ELEMENT;
// returns 8

tuple.buffer

Pointer to the underlying data buffer.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ] );

var buf = tuple.buffer;
// returns <ArrayBuffer>

tuple.byteLength

Length (in bytes) of the tuple.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ] );

var nbytes = tuple.byteLength;
// returns 16

tuple.byteOffset

Offset (in bytes) of a tuple from the start of its underlying ArrayBuffer.

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

tuple.length

Number of tuple elements.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ] );

var len = tuple.length;
// returns 2

tuple.name

Tuple name.

// 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'

tuple.fields

Returns the list of tuple fields.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory( [ 1.0, -1.0 ] );

var fields = tuple.fields;
// returns [ 'x', 'y' ]

tuple.orderedFields

Returns the list of tuple fields in index order.

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' ]

tuple.copyWithin( target, start[, end] )

Copies a sequence of elements within the tuple starting at start and ending at end (non-inclusive) to the position starting at target.

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

By default, end equals the number of tuple elements (i.e., one more than the last tuple index). To limit the sequence length, provide an end argument.

var factory = namedtypedtuple( [ 'x', 'y', 'z', 'w', 'v' ] );

var tuple = factory( [ 2.0, -2.0, 1.0, -1.0, 1.0 ] );

var w = tuple.w;
// returns -1.0

var v = tuple.v;
// returns 1.0

// Copy the first two elements to the last two elements:
tuple.copyWithin( 3, 0, 2 );

w = tuple.w;
// returns 2.0

v = tuple.v;
// returns -2.0

When a target, start, and/or end index is negative, the respective index is determined relative to the last tuple element. The following example achieves the same behavior as the previous example:

var factory = namedtypedtuple( [ 'x', 'y', 'z', 'w', 'v' ] );

var tuple = factory( [ 2.0, -2.0, 1.0, -1.0, 1.0 ] );

var w = tuple.w;
// returns -1.0

var v = tuple.v;
// returns 1.0

// Copy the first two elements to the last two elements:
tuple.copyWithin( -2, -5, -3 );

w = tuple.w;
// returns 2.0

v = tuple.v;
// returns -2.0

tuple.entries()

Returns an iterator for iterating over tuple key-value pairs.

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

tuple.every( predicate[, thisArg] )

Tests whether all tuple elements pass a test implemented by a predicate function.

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

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.

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.every( predicate, ctx );
// returns true

var n = ctx.count;
// returns 2

tuple.fieldOf( searchElement[, fromIndex] )

Returns the field of the first tuple element strictly equal to a search element.

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

By default, the method searches the entire tuple (fromIndex = 0). To begin searching from a specific tuple index, provide a fromIndex.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var field = tuple.fieldOf( 1.0, 1 );
// returns undefined

When a fromIndex is negative, the starting index is resolved relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var field = tuple.fieldOf( 1.0, -2 );
// returns undefined

The method does not distinguish between signed and unsigned zero.

tuple.fill( value[, start[, end]] )

Fills a tuple from a start index to an end index (non-inclusive) with a provided value.

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

When a start and/or end index is negative, the respective index is determined relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y' ] );

var tuple = factory();

// Set all tuple elements, except the last element, to the same value:
tuple.fill( 2.0, -tuple.length, -1 );

var x = tuple.x;
// returns 2.0

var y = tuple.y;
// returns 0.0

tuple.filter( predicate[, thisArg] )

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.

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' ]

If a predicate function does not return a truthy value for any tuple element, the method returns null.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

function predicate( v ) {
    return ( v >= 10.0 );
}

var p2 = p1.filter( predicate );
// returns null

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.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

function predicate( v ) {
    this.count += 1;
    return ( v >= 0.0 );
}

var ctx = {
    'count': 0
};

var p2 = p1.filter( predicate, ctx );

var n = ctx.count;
// returns 3

tuple.find( predicate[, thisArg] )

Returns the first tuple element for which a provided predicate function returns a truthy value.

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

If a predicate function does not return a truthy value for any tuple element, the method returns undefined.

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.find( 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.

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.find( predicate, ctx );
// returns -1.0

var n = ctx.count;
// returns 3

tuple.findField( predicate[, thisArg] )

Returns the field of the first tuple element for which a provided predicate function returns a truthy value.

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'

If a predicate function does not return a truthy value for any tuple element, the method returns undefined.

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.findField( 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.

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.findField( predicate, ctx );
// returns 'z'

var n = ctx.count;
// returns 3

tuple.findIndex( predicate[, thisArg] )

Returns the index of the first tuple element for which a provided predicate function returns a truthy value.

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

If a predicate function does not return a truthy value for any tuple element, the method returns -1.

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.findIndex( 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.

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.findIndex( predicate, ctx );
// returns 2

var n = ctx.count;
// returns 3

tuple.forEach( fcn[, thisArg] )

Invokes a callback for each tuple element.

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'

The callback 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.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );

function fcn() {
    this.count += 1;
}

var ctx = {
    'count': 0
};

tuple.forEach( fcn, ctx );

var n = ctx.count;
// returns 3

tuple.includes( searchElement[, fromIndex] )

Returns a boolean indicating whether a tuple includes a search element.

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

By default, the method searches the entire tuple (fromIndex = 0). To begin searching from a specific tuple index, provide a fromIndex.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var bool = tuple.includes( 1.0, 1 );
// returns false

When a fromIndex is negative, the starting index is resolved relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var bool = tuple.includes( 1.0, -2 );
// returns false

The method does not distinguish between signed and unsigned zero.

tuple.indexOf( searchElement[, fromIndex] )

Returns the index of the first tuple element strictly equal to a search element.

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

By default, the method searches the entire tuple (fromIndex = 0). To begin searching from a specific tuple index, provide a fromIndex.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var idx = tuple.indexOf( 1.0, 1 );
// returns -1

When a fromIndex is negative, the starting index is resolved relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var idx = tuple.indexOf( 1.0, -2 );
// returns -1

The method does not distinguish between signed and unsigned zero.

tuple.ind2key( ind )

Converts a tuple index to a field name.

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

If provided a negative index, the method resolves the index relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var field = tuple.ind2key( -2 );
// returns 'y'

tuple.join( [separator] )

Serializes a tuple by joining all tuple elements as a string.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );

var str = tuple.join();
// returns '1,0,-1'

By default, the method delineates tuple elements using a comma ,. To specify a custom separator, provide a separator string.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );

var str = tuple.join( '|' );
// returns '1|0|-1'

tuple.keys()

Returns an iterator for iterating over tuple keys.

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

tuple.key2ind( field )

Converts a field name to a tuple index.

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

tuple.lastFieldOf( searchElement[, fromIndex] )

Returns the field of the last tuple element strictly equal to a search element, iterating from right to left.

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

By default, the method searches the entire tuple (fromIndex = -1). To begin searching from a specific tuple index, provide a fromIndex.

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, 2 );
// returns 'y'

When a fromIndex is negative, the starting index is resolved relative to the last tuple element.

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, -3 );
// returns 'y'

The method does not distinguish between signed and unsigned zero.

tuple.lastIndexOf( searchElement[, fromIndex] )

Returns the index of the last tuple element strictly equal to a search element, iterating from right to left.

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

By default, the method searches the entire tuple (fromIndex = -1). To begin searching from a specific tuple index, provide a fromIndex.

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, 2 );
// returns 1

When a fromIndex is negative, the starting index is resolved relative to the last tuple element.

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, -3 );
// returns 1

The method does not distinguish between signed and unsigned zero.

tuple.map( fcn[, thisArg] )

Maps each tuple element to an element in a new tuple having the same data type as the host tuple.

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

A callback 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.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

function fcn( v ) {
    this.count += 1;
    return v * 2.0;
}

var ctx = {
    'count': 0
};

var p2 = p1.map( fcn, ctx );

var n = ctx.count;
// returns 3

tuple.reduce( fcn[, initialValue] )

Applies a function against an accumulator and each element in a tuple and returns the accumulated result.

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

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.

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.

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, 0.0 );
// returns 13.0

A callback is provided five arguments:

• acc: accumulated result
• value: tuple element
• index: tuple index
• field: tuple field name
• tuple: tuple on which the method is invoked

tuple.reduceRight( fcn[, initialValue] )

Applies a function against an accumulator and each element in a tuple and returns the accumulated result, iterating from right to left.

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

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.

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.

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, 0.0 );
// returns 13.0

A callback is provided five arguments:

• acc: accumulated result
• value: tuple element
• index: tuple index
• field: tuple field name
• tuple: tuple on which the method is invoked

tuple.reverse()

Reverses a tuple in-place (thus mutating the tuple on which the method is invoked).

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

Invoking this method does not affect tuple field assignments.

tuple.set( arr[, offset] )

Sets tuple elements.

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

By default, the method starts writing values at the first tuple index. To specify an alternative index, provide an index offset.

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 last two tuple elements:
tuple.set( [ -2.0, 2.0 ], 1 );

var x = tuple[ 0 ];
// returns 1.0

x = tuple.x;
// returns 1.0

y = tuple[ 1 ];
// returns -2.0

y = tuple.y;
// returns -2.0

var z = tuple[ 2 ];
// returns 2.0

z = tuple.z;
// returns 2.0

tuple.slice( [begin[, end]] )

Copies tuple elements to a new tuple with the same underlying data type as the host tuple.

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

By default, the method copies elements beginning with the first tuple element. To specify an alternative tuple index at which to begin copying, provide a begin index (inclusive).

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.slice( 1 );

var fields = p2.fields;
// returns [ 'y', 'z' ]

var y = p2.y;
// returns 0.0

var z = p2.z;
// returns -1.0

By default, the method copies all tuple elements after begin. To specify an alternative tuple index at which to end copying, provide an end index (exclusive).

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.slice( 0, 2 );

var fields = p2.fields;
// returns [ 'x', 'y' ]

var x = p2.x;
// returns 1.0

var y = p2.y;
// returns 0.0

When a begin and/or end index is negative, the respective index is determined relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.slice( -p1.length, -1 );

var fields = p2.fields;
// returns [ 'x', 'y' ]

var x = p2.x;
// returns 1.0

var y = p2.y;
// returns 0.0

tuple.some( predicate[, thisArg] )

Tests whether at least one tuple element passes a test implemented by a predicate function.

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

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.

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

tuple.sort( [compareFunction] )

Sorts a tuple in-place (thus mutating the tuple on which the method is invoked).

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 0.0

By default, the method sorts tuple elements in ascending order. To impose a custom order, provide a compareFunction.

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:
var y = tuple.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.

Invoking this method does not affect tuple field assignments.

tuple.subarray( [begin[, end]] )

Creates a new typed array over the same underlying ArrayBuffer and with the same underlying data type as the host tuple.

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 ]

By default, the method creates a typed array view beginning with the first tuple element. To specify an alternative tuple index at which to begin, provide a begin index (inclusive).

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 ]

By default, the method creates a typed array view which includes all tuple elements after begin. To limit the number of tuple elements after begin, provide an end index (exclusive).

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 ]

When a begin and/or end index is negative, the respective index is determined relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var arr = tuple.subarray( -tuple.length, -1 );
// returns <Float64Array>[ 1.0, 0.0 ]

If the method is unable to resolve indices to a non-empty tuple subsequence, the method returns an empty typed array.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ] );

var arr = tuple.subarray( 10, -1 );
// returns <Float64Array>[]

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.

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

By default, the method creates a new tuple beginning with the first tuple element. To specify an alternative tuple index at which to begin, provide a begin index (inclusive).

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.subtuple( 1 );

var len = p2.length;
// returns 2

var fields = p2.fields;
// returns [ 'y', 'z' ]

var y = p2.y;
// returns 0.0

var z = p2.z;
// returns -1.0

By default, the method creates a new tuple which includes all tuple elements after begin. To limit the number of tuple elements after begin, provide an end index (exclusive).

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.subtuple( 0, 2 );

var len = p2.length;
// returns 2

var fields = p2.fields;
// returns [ 'x', 'y' ]

var x = p2.x;
// returns 1.0

var y = p2.y;
// returns 0.0

When a begin and/or end index is negative, the respective index is determined relative to the last tuple element.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.subtuple( -p1.length, -1 );

var len = p2.length;
// returns 2

var fields = p2.fields;
// returns [ 'x', 'y' ]

var x = p2.x;
// returns 1.0

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.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var p1 = factory( [ 1.0, 0.0, -1.0 ] );

var p2 = p1.subtuple( 10, -1 );
// returns null

tuple.toJSON()

Serializes a tuple as JSON.

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 }

tuple.toLocaleString( [locales[, options]] )

Serializes a tuple as a locale-specific string.

var factory = namedtypedtuple( [ 'x', 'y', 'z' ] );

var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );

var str = tuple.toLocaleString();
// returns '1,0,-1'

tuple.toString()

Serializes a tuple as a string.

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)'

The returned string uses the tuple name as specified when creating a tuple factory.

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)'

tuple.values()

Returns an iterator for iterating over tuple elements.

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