feat: implement toLocaleString method in dstructs/named-typed-tuple

PR-URL: #8009
Closes: #6976
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]> 
Co-authored-by: stdlib-bot <[email protected]>

Author: 3 people

lib/node_modules/@stdlib/dstructs/named-typed-tuple/docs/repl.txt

@@ -1378,10 +1378,11 @@ tuple.toLocaleString( [locales[, options]] )
 
     Examples
     --------
-    > var factory = {{alias}}( [ 'x', 'y', 'z' ] );
+    > var opts = { 'name': 'Point' };
+    > var factory = {{alias}}( [ 'x', 'y', 'z' ], opts );
     > var p = factory( [ 1.0, -1.0, 0.0 ], 'int32' );
     > p.toLocaleString()
-    '1,-1,0'
+    'Point(x=1, y=-1, z=0)'
 
 
 tuple.toString()
@@ -1394,7 +1395,7 @@ tuple.toString()
 
     Examples
     --------
-    > opts = { 'name': 'Point' };
+    > var opts = { 'name': 'Point' };
     > var factory = {{alias}}( [ 'x', 'y', 'z' ], opts );
     > var p = factory( [ 1.0, -1.0, 0.0 ] );
     > p.toString()

lib/node_modules/@stdlib/dstructs/named-typed-tuple/docs/types/index.d.ts

@@ -1244,7 +1244,7 @@ interface Tuple {
 	* var tuple = factory( [ 1.0, 0.0, -1.0 ], 'int32' );
 	*
 	* var str = tuple.toLocaleString();
-	* // returns '1,0,-1'
+	* // returns 'tuple(x=1, y=0, z=-1)'
 	*/
 	toLocaleString( locales: string | Array<string>, options?: any ): string;
 

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

@@ -204,6 +204,7 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 		setNonEnumerableProperty( tuple, 'sort', sort );
 		setNonEnumerableProperty( tuple, 'subtuple', subtuple );
 		setNonEnumerableProperty( tuple, 'toJSON', toJSON );
+		setNonEnumerableProperty( tuple, 'toLocaleString', toLocaleString );
 		setNonEnumerableProperty( tuple, 'toString', toString );
 
 		return tuple;
@@ -1198,7 +1199,53 @@ function factory( names, options ) { // eslint-disable-line max-lines-per-functi
 			return out;
 		}
 
-		// TODO: consider adding `toLocaleString()` in a manner similar to `toString()` below
+		/**
+		* Serializes a tuple as a locale-specific string.
+		*
+		* @private
+		* @memberof tuple
+		* @param {(string|Array<string>)} [locales] - locale identifier(s)
+		* @param {Object} [options] - configuration options
+		* @throws {TypeError} `this` must be the host tuple
+		* @throws {TypeError} first argument must be a string or an array of strings
+		* @throws {TypeError} options argument must be an object
+		* @returns {string} string representation
+		*/
+		function toLocaleString( locales, options ) {
+			var loc;
+			var out;
+			var o;
+			var i;
+
+			if ( this !== tuple ) { // eslint-disable-line no-invalid-this
+				throw new TypeError( 'invalid invocation. `this` is not host tuple.' );
+			}
+			if ( arguments.length === 0 ) {
+				loc = [];
+			} else if ( isString( locales ) || isStringArray( locales ) ) {
+				loc = locales;
+			} else {
+				throw new TypeError( format( 'invalid argument. First argument must be a string or an array of strings. Value: `%s`.', locales ) );
+			}
+			if ( arguments.length < 2 ) {
+				o = {};
+			} else if ( isObject( options ) ) {
+				o = options;
+			} else {
+				throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+			}
+			out = opts.name.toLocaleString( loc, o ) + '(';
+			for ( i = 0; i < nfields; i++ ) {
+				out += fields[ i ].toLocaleString( loc, o );
+				out += '=';
+				out += tuple[ indices[ i ] ].toLocaleString( loc, o );
+				if ( i < nfields-1 ) {
+					out += ', ';
+				}
+			}
+			out += ')';
+			return out;
+		}
 
 		/**
 		* Serializes a tuple as a string.

lib/node_modules/@stdlib/dstructs/named-typed-tuple/test/test.to_locale_string.js

@@ -0,0 +1,148 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var tape = require( 'tape' );
+var hasProp = require( '@stdlib/assert/has-property' );
+var isFunction = require( '@stdlib/assert/is-function' );
+var namedtypedtuple = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+	t.ok( true, __filename );
+	t.strictEqual( typeof namedtypedtuple, 'function', 'main export is a function' );
+	t.end();
+});
+
+tape( 'a tuple has a `toLocaleString` method', function test( t ) {
+	var Point;
+	var p;
+
+	Point = namedtypedtuple( [ 'x', 'y' ] );
+	p = new Point();
+
+	t.strictEqual( hasProp( p, 'toLocaleString' ), true, 'returns expected value' );
+	t.strictEqual( isFunction( p.toLocaleString ), true, 'returns expected value' );
+	t.end();
+});
+
+tape( 'the method throws an error if invoked with a `this` context which is not a tuple instance', function test( t ) {
+	var values;
+	var Point;
+	var p;
+	var i;
+
+	Point = namedtypedtuple( [ 'x', 'y' ] );
+	p = new Point();
+
+	values = [
+		'5',
+		5,
+		NaN,
+		true,
+		false,
+		null,
+		void 0,
+		{},
+		[]
+	];
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] );
+	}
+	t.end();
+
+	function badValue( value ) {
+		return function badValue() {
+			return p.toLocaleString.call( value );
+		};
+	}
+});
+
+tape( 'the method serializes a tuple as a locale-specific string (default locale)', function test( t ) {
+	var expected;
+	var actual;
+	var Point;
+	var p;
+
+	Point = namedtypedtuple( [ 'price', 'quantity' ] );
+	p = new Point( [ 123456.789, 9876 ] );
+
+	expected = 'tuple(price=' + (123456.789).toLocaleString() + ', quantity=' + (9876).toLocaleString() + ')';
+	actual = p.toLocaleString();
+
+	t.strictEqual( actual, expected, 'returns expected value' );
+	t.end();
+});
+
+tape( 'the method serializes a tuple as a locale-specific string (specified locale)', function test( t ) {
+	var expected;
+	var actual;
+	var Point;
+	var p;
+
+	Point = namedtypedtuple( [ 'price', 'quantity' ] );
+	p = new Point( [ 123456.789, 9876 ] );
+
+	expected = 'tuple(price=123.456,789, quantity=9.876)';
+	actual = p.toLocaleString( 'de-DE' );
+
+	t.strictEqual( actual, expected, 'returns expected value' );
+	t.end();
+});
+
+tape( 'the method serializes a tuple as a locale-specific string (locale and options)', function test( t ) {
+	var expected;
+	var actual;
+	var Point;
+	var opts;
+	var p;
+
+	Point = namedtypedtuple( [ 'price', 'quantity' ] );
+	p = new Point( [ 1234.56, 50 ] );
+	opts = {
+		'style': 'currency',
+		'currency': 'USD'
+	};
+
+	expected = 'tuple(price=' + (1234.56).toLocaleString( 'en-US', opts ) + ', quantity=' + (50).toLocaleString( 'en-US', opts ) + ')';
+	actual = p.toLocaleString( 'en-US', opts );
+
+	t.strictEqual( actual, expected, 'returns expected value' );
+	t.end();
+});
+
+tape( 'the method handles NaN values', function test( t ) {
+	var expected;
+	var Record;
+	var actual;
+	var r;
+
+	Record = namedtypedtuple( [ 'isValid', 'value' ] );
+	r = new Record( [ 1, NaN ] );
+
+	expected = 'tuple(isValid=1, value=NaN)';
+	actual = r.toLocaleString();
+
+	t.strictEqual( actual, expected, 'returns expected value' );
+	t.end();
+});