feat: add toLocaleString method to ndarray/base/ctor

lib/node_modules/@stdlib/ndarray/base/ctor/README.md

@@ -534,6 +534,39 @@ var str = arr.toString();
 
 The method does **not** serialize data outside of the buffer region defined by the array configuration.
 
+<a name="method-to-locale-string"></a>
+
+#### ndarray.prototype.toLocaleString( \[locales\[, options]] )
+
+Serializes an `ndarray` as a locale-specific `string`.
+
+```javascript
+// Specify the array configuration:
+var buffer = [ 1234.567, 9876.543, 1111.222, 3333.444 ];
+var shape = [ 2, 2 ];
+var order = 'row-major';
+var strides = [ 2, 1 ];
+var offset = 0;
+
+// Create a new ndarray:
+var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
+
+// Serialize to a locale-specific string:
+var str = arr.toLocaleString( 'en-US' );
+// returns "ndarray( 'generic', [ 1,234.567, 9,876.543, 1,111.222, 3,333.444 ], [ 2, 2 ], [ 2, 1 ], 0, 'row-major' )"
+
+// Use German locale:
+str = arr.toLocaleString( 'de-DE' );
+// returns "ndarray( 'generic', [ 1.234,567, 9.876,543, 1.111,222, 3.333,444 ], [ 2, 2 ], [ 2, 1 ], 0, 'row-major' )"
+```
+
+The method accepts the following arguments:
+
+-   **locales**: a string with a BCP 47 language tag or an array of such strings.
+-   **options**: configuration properties.
+
+The method does **not** serialize data outside of the buffer region defined by the array configuration.
+
 <a name="method-to-json"></a>
 
 #### ndarray.prototype.toJSON()

lib/node_modules/@stdlib/ndarray/base/ctor/lib/main.js

@@ -41,6 +41,7 @@
 var valueOf = require( './valueof.js' ); // eslint-disable-line stdlib/no-redeclare
 var toJSON = require( './tojson.js' );
 var toString = require( './tostring.js' ); // eslint-disable-line stdlib/no-redeclare
+var toLocaleString = require( './tolocalestring.js' ); // eslint-disable-line stdlib/no-redeclare
 var meta2dataview = require( './meta2dataview.js' );
 var meta2dataviewPolyfill = require( './meta2dataview.polyfill.js' );
 
@@ -92,7 +93,7 @@
 	// Compute the number of elements...
 	len = 1;
 	for ( i = 0; i < shape.length; i++ ) {
 		len *= shape[ i ]; // TODO: consider supporting accessor arrays here
 	}
 	// Compute the number of bytes...
 	if ( buffer.BYTES_PER_ELEMENT ) {
@@ -544,6 +545,35 @@
 */
 setReadOnly( ndarray.prototype, 'toString', toString );
 
+/**
+* Serializes an ndarray as a locale-aware string.
+*
+* ## Notes
+*
+* -   The method does **not** serialize data outside of the buffer region defined by the array configuration.
+*
+* @name toLocaleString
+* @memberof ndarray.prototype
+* @type {Function}
+* @param {(string|Array<string>)} [locales] - locale identifier(s)
+* @param {Object} [options] - configuration options
+* @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
+*
+* @example
+* var buffer = [ 1234.567, 9876.543, 1111.222, 3333.444 ];
+* var shape = [ 2, 2 ];
+* var strides = [ 2, 1 ];
+* var offset = 0;
+*
+* var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
+*
+* var str = x.toLocaleString( 'en-US' );
+* // returns "ndarray( 'generic', [ 1,234.567, 9,876.543, 1,111.222, 3,333.444 ], [ 2, 2 ], [ 2, 1 ], 0, 'row-major' )"
+*/
+setReadOnly( ndarray.prototype, 'toLocaleString', toLocaleString );
+
 /**
 * Serializes an ndarray as a JSON object.
 *

lib/node_modules/@stdlib/ndarray/base/ctor/lib/tolocalestring.js

@@ -0,0 +1,206 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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 isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var isStringArray = require( '@stdlib/assert/is-string-array' ).primitives;
+var isObject = require( '@stdlib/assert/is-plain-object' );
+var format = require( '@stdlib/string/format' );
+var replace = require( '@stdlib/string/replace' );
+var real = require( '@stdlib/complex/float64/real' );
+var imag = require( '@stdlib/complex/float64/imag' );
+
+
+// VARIABLES //
+
+var CTORS = {
+	'int8': 'new Int8Array( [ {{data}} ] )',
+	'uint8': 'new Uint8Array( [ {{data}} ] )',
+	'uint8c': 'new Uint8ClampedArray( [ {{data}} ] )',
+	'int16': 'new Int16Array( [ {{data}} ] )',
+	'uint16': 'new Uint16Array( [ {{data}} ] )',
+	'int32': 'new Int32Array( [ {{data}} ] )',
+	'uint32': 'new Uint32Array( [ {{data}} ] )',
+	'float32': 'new Float32Array( [ {{data}} ] )',
+	'float64': 'new Float64Array( [ {{data}} ] )',
+	'generic': '[ {{data}} ]',
+	'binary': 'new Buffer( [ {{data}} ] )',
+	'complex64': 'new Complex64Array( [ {{data}} ] )',
+	'complex128': 'new Complex128Array( [ {{data}} ] )',
+	'bool': 'new BooleanArray( [ {{data}} ] )'
+};
+
+
+// MAIN //
+
+/**
+* Serializes an ndarray as a locale-aware string.
+*
+* ## Notes
+*
+* -   The method does **not** serialize data outside of the buffer region defined by the array configuration.
+*
+* @private
+* @param {(string|Array<string>)} [locales] - locale identifier(s)
+* @param {Object} [options] - configuration options
+* @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 ) { // eslint-disable-line stdlib/no-redeclare
+	/* eslint-disable no-invalid-this */
+	var buffer;
+	var ndims;
+	var ctor;
+	var opts;
+	var loc;
+	var str;
+	var dt;
+	var v;
+	var i;
+
+	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 ) {
+		opts = {};
+	} else if ( isObject( options ) ) {
+		opts = options;
+	} else {
+		throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+	}
+
+	ndims = this._shape.length;
+	dt = this._dtype;
+
+	// Function to invoke to create an ndarray:
+	str = 'ndarray( \''+dt+'\', ';
+
+	// Data buffer parameter...
+	buffer = '';
+	if ( this._length <= 100 ) {
+		if ( dt === 'complex64' || dt === 'complex128' ) {
+			for ( i = 0; i < this._length; i++ ) {
+				v = this.iget( i );
+				buffer += real( v ).toLocaleString( loc, opts ) + ', ' + imag( v ).toLocaleString( loc, opts );
+				if ( i < this._length-1 ) {
+					buffer += ', ';
+				}
+			}
+		} else {
+			for ( i = 0; i < this._length; i++ ) {
+				buffer += this.iget( i ).toLocaleString( loc, opts );
+				if ( i < this._length-1 ) {
+					buffer += ', ';
+				}
+			}
+		}
+	} else {
+		// First three values...
+		if ( dt === 'complex64' || dt === 'complex128' ) {
+			for ( i = 0; i < 3; i++ ) {
+				v = this.iget( i );
+				buffer += real( v ).toLocaleString( loc, opts ) + ', ' + imag( v ).toLocaleString( loc, opts );
+				if ( i < 2 ) {
+					buffer += ', ';
+				}
+			}
+		} else {
+			for ( i = 0; i < 3; i++ ) {
+				buffer += this.iget( i ).toLocaleString( loc, opts );
+				if ( i < 2 ) {
+					buffer += ', ';
+				}
+			}
+		}
+		buffer += ', ..., ';
+
+		// Last three values...
+		if ( dt === 'complex64' || dt === 'complex128' ) {
+			for ( i = 2; i >= 0; i-- ) {
+				v = this.iget( this._length-1-i );
+				buffer += real( v ).toLocaleString( loc, opts ) + ', ' + imag( v ).toLocaleString( loc, opts );
+				if ( i > 0 ) {
+					buffer += ', ';
+				}
+			}
+		} else {
+			for ( i = 2; i >= 0; i-- ) {
+				buffer += this.iget( this._length-1-i ).toLocaleString( loc, opts ); // eslint-disable-line max-len
+				if ( i > 0 ) {
+					buffer += ', ';
+				}
+			}
+		}
+	}
+	ctor = CTORS[ this.dtype ];
+	str += replace( ctor, '{{data}}', buffer );
+	str += ', ';
+
+	// Array shape...
+	if ( ndims === 0 ) {
+		str += '[]';
+	} else {
+		str += '[ ' + this._shape.join( ', ' ) + ' ]';
+	}
+	str += ', ';
+
+	// Stride array...
+	str += '[ ';
+	if ( ndims === 0 ) {
+		str += '0';
+	} else {
+		for ( i = 0; i < ndims; i++ ) {
+			if ( this._strides[ i ] < 0 ) {
+				str += -this._strides[ i ];
+			} else {
+				str += this._strides[ i ];
+			}
+			if ( i < ndims-1 ) {
+				str += ', ';
+			}
+		}
+	}
+	str += ' ]';
+	str += ', ';
+
+	// Buffer offset:
+	str += '0';
+	str += ', ';
+
+	// Order:
+	str += '\'' + this._order + '\'';
+
+	// Close the function call:
+	str += ' )';
+	return str;
+
+	/* eslint-enable no-invalid-this */
+}
+
+
+// EXPORTS //
+
+module.exports = toLocaleString;