<commit_before><!--

@license Apache-2.0

Copyright (c) 2018 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.

-->

# Named Typed Tuple

> Create a factory for generating named typed tuples.

<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->

<section class="intro">

Named tuples assign a property name, and thus a meaning, to each position in a tuple and allow for more readable, self-documenting code.

Named typed tuples can be used wherever [typed arrays][@stdlib/array/typed] are used, with the added benefit that they allow accessing fields by both field name and position index.

</section>

<!-- /.intro -->

<!-- Package usage documentation. -->

<section class="usage">

## Usage

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

<a name="main"></a>

#### namedtypedtuple( fields\[, options] )

Returns a named typed tuple factory.

```javascript
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

<a name="factory"></a>

#### factory()

Returns a named typed tuple of the default data type.

```javascript
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.

```javascript
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][@stdlib/array/typed].

```javascript
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][@stdlib/array/typed] values to another data type), provide a `dtype`.

```javascript
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.

```javascript
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`.

```javascript
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`][@stdlib/array/buffer] where the view length equals the number of tuple fields.

```javascript
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`.

```javascript
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
```

<a name="static-method-from"></a>

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

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

```javascript
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.

```javascript
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`.

```javascript
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
```

<a name="static-method-from-object"></a>

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

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

```javascript
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.

```javascript
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`.

```javascript
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
```

<a name="static-method-of"></a>

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

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

```javascript
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

<a name="prop-bytes-per-element"></a>
<commit_msg>Add horizontal rule<commit_after><!--

@license Apache-2.0

Copyright (c) 2018 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.

-->

# Named Typed Tuple

> Create a factory for generating named typed tuples.

<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->

<section class="intro">

Named tuples assign a property name, and thus a meaning, to each position in a tuple and allow for more readable, self-documenting code.

Named typed tuples can be used wherever [typed arrays][@stdlib/array/typed] are used, with the added benefit that they allow accessing fields by both field name and position index.

</section>

<!-- /.intro -->

<!-- Package usage documentation. -->

<section class="usage">

## Usage

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

<a name="main"></a>

#### namedtypedtuple( fields\[, options] )

Returns a named typed tuple factory.

```javascript
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

<a name="factory"></a>

#### factory()

Returns a named typed tuple of the default data type.

```javascript
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.

```javascript
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][@stdlib/array/typed].

```javascript
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][@stdlib/array/typed] values to another data type), provide a `dtype`.

```javascript
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.

```javascript
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`.

```javascript
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`][@stdlib/array/buffer] where the view length equals the number of tuple fields.

```javascript
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`.

```javascript
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
```

<a name="static-method-from"></a>

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

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

```javascript
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.

```javascript
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`.

```javascript
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
```

<a name="static-method-from-object"></a>

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

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

```javascript
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.

```javascript
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`.

```javascript
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
```

<a name="static-method-of"></a>

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

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

```javascript
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

<a name="prop-bytes-per-element"></a>

{'fraction_non_alphanumeric': 0.16270764569016827, 'fraction_numerical': 0.03235755640928521, 'mean_word_length': 2.91983032873807, 'pattern_counts': {'":': 0, '<': 41, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6269491', 'n_tokens_mistral': 6862, 'n_tokens_neox': 6375, 'n_words': 2386}