diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/README.md b/lib/node_modules/@stdlib/string/base/truncate-code-point/README.md
new file mode 100644
index 000000000000..e29e045a5f5a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/README.md
@@ -0,0 +1,104 @@
+
+
+# truncate
+
+> Truncate a string to a specified length in code points.
+
+
+
+## Usage
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate-code-point' );
+```
+
+#### truncate( str, len, ending )
+
+Truncates a string to a specified length in code points.
+
+```javascript
+var out = truncate( 'beep boop', 7, '...' );
+// returns 'beep...'
+
+out = truncate( 'beep boop', 5, '>>>' );
+// returns 'be>>>'
+```
+
+
+
+
+
+
+
+## Notes
+
+- This function assumes that the input arguments are valid. For input validation, use the top-level [`@stdlib/string/truncate`][@stdlib/string/truncate].
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate-code-point' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 Wo...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[@stdlib/string/truncate]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/truncate
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/base/truncate-code-point/benchmark/benchmark.js
new file mode 100644
index 000000000000..1ff3214ecc3a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/benchmark/benchmark.js
@@ -0,0 +1,57 @@
+/**
+* @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 bench = require( '@stdlib/bench' );
+var randu = require( '@stdlib/random/base/randu' );
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var strings;
+ var out;
+ var i;
+
+ strings = [
+ 'beep boop',
+ 'foo bar',
+ 'hello world',
+ '🐺 Wolf Brothers 🐺',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( strings[ i % strings.length ], (randu() * 10)|0, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/repl.txt b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/repl.txt
new file mode 100644
index 000000000000..b404e52e4e6d
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/repl.txt
@@ -0,0 +1,32 @@
+{{alias}}( str, len, ending )
+ Truncates a string to a specified length in code points (i.e.,
+ user-perceived characters).
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: NonNegativeInteger
+ Output string length (including ending).
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var out = {{alias}}( 'beep boop', 7, '...' )
+ 'beep...'
+ > out = {{alias}}( 'beep boop', 5, '>>>' )
+ 'be>>>'
+ > out = {{alias}}( 'foo bar', 10, '...' )
+ 'foo bar'
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/index.d.ts
new file mode 100644
index 000000000000..6c057e524e51
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/index.d.ts
@@ -0,0 +1,42 @@
+/**
+* @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.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* Truncates a string to a specified length in code points.
+*
+* @param str - input string
+* @param len - output string length
+* @param ending - custom ending
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+declare function truncate( str: string, len: number, ending: string ): string;
+
+
+// EXPORTS //
+
+export = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/test.ts
new file mode 100644
index 000000000000..02a9ffaf41ba
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/docs/types/test.ts
@@ -0,0 +1,71 @@
+/*
+* @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.
+*/
+
+import truncate = require( './index' );
+
+
+// TESTS //
+
+// The function returns a string...
+{
+ truncate( 'beep boop', 5, '...' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a string...
+{
+ truncate( 5, 5, '...' ); // $ExpectError
+ truncate( false, 5, '...' ); // $ExpectError
+ truncate( true, 5, '...' ); // $ExpectError
+ truncate( null, 5, '...' ); // $ExpectError
+ truncate( undefined, 5, '...' ); // $ExpectError
+ truncate( [], 5, '...' ); // $ExpectError
+ truncate( {}, 5, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 5, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a number...
+{
+ truncate( 'beep boop', '5', '...' ); // $ExpectError
+ truncate( 'beep boop', false, '...' ); // $ExpectError
+ truncate( 'beep boop', true, '...' ); // $ExpectError
+ truncate( 'beep boop', null, '...' ); // $ExpectError
+ truncate( 'beep boop', undefined, '...' ); // $ExpectError
+ truncate( 'beep boop', [], '...' ); // $ExpectError
+ truncate( 'beep boop', {}, '...' ); // $ExpectError
+ truncate( 'beep boop', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not a string...
+{
+ truncate( 'beep boop', 5, 5 ); // $ExpectError
+ truncate( 'beep boop', 5, false ); // $ExpectError
+ truncate( 'beep boop', 5, true ); // $ExpectError
+ truncate( 'beep boop', 5, null ); // $ExpectError
+ truncate( 'beep boop', 5, undefined ); // $ExpectError
+ truncate( 'beep boop', 5, [] ); // $ExpectError
+ truncate( 'beep boop', 5, {} ); // $ExpectError
+ truncate( 'beep boop', 5, ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'beep boop' ); // $ExpectError
+ truncate( 'beep boop', 5 ); // $ExpectError
+ truncate( 'beep boop', 5, '...', 10 ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/examples/index.js b/lib/node_modules/@stdlib/string/base/truncate-code-point/examples/index.js
new file mode 100644
index 000000000000..85b737360fdd
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/examples/index.js
@@ -0,0 +1,36 @@
+/**
+* @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';
+
+var truncate = require( './../lib' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 Wo...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/index.js b/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/index.js
new file mode 100644
index 000000000000..f6e4618c5dc3
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @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';
+
+/**
+* Truncate a string to a specified length in code points.
+*
+* @module @stdlib/string/base/truncate-code-point
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate-code-point' );
+*
+* var str = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* str = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/main.js b/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/main.js
new file mode 100644
index 000000000000..17d55d782bf8
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/lib/main.js
@@ -0,0 +1,99 @@
+/**
+* @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 numCodePoints = require( '@stdlib/string/num-code-points' );
+var nextCodePointIndex = require( '@stdlib/string/next-code-point-index' );
+
+
+// MAIN //
+
+/**
+* Truncates a string to a specified length in code points.
+*
+* @param {string} str - input string
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} ending - custom ending
+* @returns {string} truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var out = truncate( 'beep boop', 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var out = truncate( 'beep boop', 0, '...' );
+* // returns ''
+*
+* @example
+* var out = truncate( 'beep boop', 2, '...' );
+* // returns '..'
+*
+* @example
+* var out = truncate( '🐺 Wolf Brothers 🐺', 7, '...' );
+* // returns '🐺 Wo...'
+*/
+function truncate( str, len, ending ) {
+ var endingLength;
+ var nVisual;
+ var idx;
+
+ endingLength = numCodePoints( ending );
+ if ( len >= numCodePoints( str ) ) {
+ return str;
+ }
+ if ( len - endingLength <= 0 ) {
+ idx = 0;
+ nVisual = 0;
+ while ( nVisual < len ) {
+ idx = nextCodePointIndex( ending, idx );
+ if ( idx === -1 ) {
+ idx = ending.length;
+ break;
+ }
+ nVisual += 1;
+ }
+ return ending.substring( 0, idx );
+ }
+ idx = 0;
+ nVisual = 0;
+ while ( nVisual < len - endingLength ) {
+ idx = nextCodePointIndex( str, idx );
+ if ( idx === -1 ) {
+ idx = str.length;
+ break;
+ }
+ nVisual += 1;
+ }
+ return str.substring( 0, idx ) + ending;
+}
+
+
+// EXPORTS //
+
+module.exports = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/package.json b/lib/node_modules/@stdlib/string/base/truncate-code-point/package.json
new file mode 100644
index 000000000000..b55f7dc75f81
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/package.json
@@ -0,0 +1,70 @@
+{
+ "name": "@stdlib/string/base/truncate-code-point",
+ "version": "0.0.0",
+ "description": "Truncate a string to a specified length in code points.",
+ "license": "Apache-2.0",
+ "author": {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ },
+ "contributors": [
+ {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ }
+ ],
+ "main": "./lib",
+ "directories": {
+ "benchmark": "./benchmark",
+ "doc": "./docs",
+ "example": "./examples",
+ "lib": "./lib",
+ "test": "./test"
+ },
+ "types": "./docs/types",
+ "scripts": {},
+ "homepage": "https://github.com/stdlib-js/stdlib",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/stdlib-js/stdlib.git"
+ },
+ "bugs": {
+ "url": "https://github.com/stdlib-js/stdlib/issues"
+ },
+ "dependencies": {
+ "@stdlib/string/next-code-point-index": "^0.2.1",
+ "@stdlib/string/num-code-points": "^0.2.1"
+ },
+ "devDependencies": {},
+ "engines": {
+ "node": ">=0.10.0",
+ "npm": ">2.7.0"
+ },
+ "os": [
+ "aix",
+ "darwin",
+ "freebsd",
+ "linux",
+ "macos",
+ "openbsd",
+ "sunos",
+ "win32",
+ "windows"
+ ],
+ "keywords": [
+ "stdlib",
+ "stdstring",
+ "utilities",
+ "utility",
+ "utils",
+ "util",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short",
+ "code",
+ "point"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-point/test/test.js b/lib/node_modules/@stdlib/string/base/truncate-code-point/test/test.js
new file mode 100644
index 000000000000..dc9eb5c82473
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-point/test/test.js
@@ -0,0 +1,143 @@
+/**
+* @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 tape = require( 'tape' );
+var truncate = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+ t.ok( true, __filename );
+ t.strictEqual( typeof truncate, 'function', 'main export is a function' );
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified ' +
+ 'length', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = '...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 9;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 6;
+ expected = '🐺 W...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸';
+ len = 2;
+ expected = '..';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸';
+ len = 10;
+ expected = '🐶🐮🐷🐰🐸';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ' +
+ 'ending)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep😃';
+ actual = truncate( str, len, '😃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop foo bar';
+ len = 10;
+ expected = 'beep 🙃 🙃 🙃';
+ actual = truncate( str, len, ' 🙃 🙃 🙃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 8;
+ expected = '🐺 Wolf 🐺';
+ actual = truncate( str, len, '🐺' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/README.md b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/README.md
new file mode 100644
index 000000000000..9d1eda4759fb
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/README.md
@@ -0,0 +1,104 @@
+
+
+# truncate
+
+> Truncate a string to a specified length in grapheme clusters.
+
+
+
+## Usage
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate-grapheme-cluster' );
+```
+
+#### truncate( str, len, ending )
+
+Truncates a string to a specified length in grapheme clusters.
+
+```javascript
+var out = truncate( 'beep boop', 7, '...' );
+// returns 'beep...'
+
+out = truncate( 'beep boop', 5, '>>>' );
+// returns 'be>>>'
+```
+
+
+
+
+
+
+
+## Notes
+
+- This function assumes that the input arguments are valid. For input validation, use the top-level [`@stdlib/string/truncate`][@stdlib/string/truncate].
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate-grapheme-cluster' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 Wo...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[@stdlib/string/truncate]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/truncate
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/benchmark/benchmark.js
new file mode 100644
index 000000000000..1ff3214ecc3a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/benchmark/benchmark.js
@@ -0,0 +1,57 @@
+/**
+* @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 bench = require( '@stdlib/bench' );
+var randu = require( '@stdlib/random/base/randu' );
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var strings;
+ var out;
+ var i;
+
+ strings = [
+ 'beep boop',
+ 'foo bar',
+ 'hello world',
+ '🐺 Wolf Brothers 🐺',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( strings[ i % strings.length ], (randu() * 10)|0, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/repl.txt b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/repl.txt
new file mode 100644
index 000000000000..94e83c280140
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/repl.txt
@@ -0,0 +1,32 @@
+{{alias}}( str, len, ending )
+ Truncates a string to a specified length in grapheme clusters (i.e.,
+ user-perceived characters).
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: NonNegativeInteger
+ Output string length (including ending).
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var out = {{alias}}( 'beep boop', 7, '...' )
+ 'beep...'
+ > out = {{alias}}( 'beep boop', 5, '>>>' )
+ 'be>>>'
+ > out = {{alias}}( 'foo bar', 10, '...' )
+ 'foo bar'
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/index.d.ts
new file mode 100644
index 000000000000..4d4da8793f0b
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/index.d.ts
@@ -0,0 +1,42 @@
+/**
+* @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.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* Truncates a string to a specified length in grapheme clusters.
+*
+* @param str - input string
+* @param len - output string length
+* @param ending - custom ending
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+declare function truncate( str: string, len: number, ending: string ): string;
+
+
+// EXPORTS //
+
+export = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/test.ts
new file mode 100644
index 000000000000..02a9ffaf41ba
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/docs/types/test.ts
@@ -0,0 +1,71 @@
+/*
+* @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.
+*/
+
+import truncate = require( './index' );
+
+
+// TESTS //
+
+// The function returns a string...
+{
+ truncate( 'beep boop', 5, '...' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a string...
+{
+ truncate( 5, 5, '...' ); // $ExpectError
+ truncate( false, 5, '...' ); // $ExpectError
+ truncate( true, 5, '...' ); // $ExpectError
+ truncate( null, 5, '...' ); // $ExpectError
+ truncate( undefined, 5, '...' ); // $ExpectError
+ truncate( [], 5, '...' ); // $ExpectError
+ truncate( {}, 5, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 5, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a number...
+{
+ truncate( 'beep boop', '5', '...' ); // $ExpectError
+ truncate( 'beep boop', false, '...' ); // $ExpectError
+ truncate( 'beep boop', true, '...' ); // $ExpectError
+ truncate( 'beep boop', null, '...' ); // $ExpectError
+ truncate( 'beep boop', undefined, '...' ); // $ExpectError
+ truncate( 'beep boop', [], '...' ); // $ExpectError
+ truncate( 'beep boop', {}, '...' ); // $ExpectError
+ truncate( 'beep boop', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not a string...
+{
+ truncate( 'beep boop', 5, 5 ); // $ExpectError
+ truncate( 'beep boop', 5, false ); // $ExpectError
+ truncate( 'beep boop', 5, true ); // $ExpectError
+ truncate( 'beep boop', 5, null ); // $ExpectError
+ truncate( 'beep boop', 5, undefined ); // $ExpectError
+ truncate( 'beep boop', 5, [] ); // $ExpectError
+ truncate( 'beep boop', 5, {} ); // $ExpectError
+ truncate( 'beep boop', 5, ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'beep boop' ); // $ExpectError
+ truncate( 'beep boop', 5 ); // $ExpectError
+ truncate( 'beep boop', 5, '...', 10 ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/examples/index.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/examples/index.js
new file mode 100644
index 000000000000..85b737360fdd
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/examples/index.js
@@ -0,0 +1,36 @@
+/**
+* @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';
+
+var truncate = require( './../lib' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 Wo...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/index.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/index.js
new file mode 100644
index 000000000000..658fb9fe22f0
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @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';
+
+/**
+* Truncate a string to a specified length in grapheme clusters.
+*
+* @module @stdlib/string/base/truncate-grapheme-cluster
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate-grapheme-cluster' );
+*
+* var str = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* str = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/main.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/main.js
new file mode 100644
index 000000000000..b72f4e109a16
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/lib/main.js
@@ -0,0 +1,90 @@
+/**
+* @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 numGraphemeClusters = require( '@stdlib/string/num-grapheme-clusters' );
+var nextGraphemeClusterBreak = require( '@stdlib/string/next-grapheme-cluster-break' );
+
+
+// MAIN //
+
+/**
+* Truncates a string to a specified length in grapheme clusters.
+*
+* @param {string} str - input string
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} ending - custom ending
+* @returns {string} truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var out = truncate( 'beep boop', 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var out = truncate( 'beep boop', 0, '...' );
+* // returns ''
+*
+* @example
+* var out = truncate( 'beep boop', 2, '...' );
+* // returns '..'
+*
+* @example
+* var out = truncate( '🐺 Wolf Brothers 🐺', 7, '...' );
+* // returns '🐺 Wo...'
+*/
+function truncate( str, len, ending ) {
+ var endingLength;
+ var fromIndex;
+ var nVisual;
+ var idx;
+
+ endingLength = numGraphemeClusters( ending );
+ fromIndex = 0;
+ if ( len >= numGraphemeClusters( str ) ) {
+ return str;
+ }
+ if ( len - endingLength <= 0 ) {
+ // Note: when slicing the ending, we use UTF-16 code units since `slice` operates on them.
+ // If `ending` contains multi-code-unit graphemes, it will slice in the middle of a grapheme.
+ // This mimics the original truncate behavior.
+ return ending.slice( 0, len );
+ }
+ nVisual = 0;
+ while ( nVisual < len - endingLength ) {
+ idx = nextGraphemeClusterBreak( str, fromIndex );
+ fromIndex = idx;
+ nVisual += 1;
+ }
+ return str.substring( 0, idx ) + ending;
+}
+
+
+// EXPORTS //
+
+module.exports = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/package.json b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/package.json
new file mode 100644
index 000000000000..b881fd5c78bf
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/package.json
@@ -0,0 +1,70 @@
+{
+ "name": "@stdlib/string/base/truncate-grapheme-cluster",
+ "version": "0.0.0",
+ "description": "Truncate a string to a specified length in grapheme clusters.",
+ "license": "Apache-2.0",
+ "author": {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ },
+ "contributors": [
+ {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ }
+ ],
+ "main": "./lib",
+ "directories": {
+ "benchmark": "./benchmark",
+ "doc": "./docs",
+ "example": "./examples",
+ "lib": "./lib",
+ "test": "./test"
+ },
+ "types": "./docs/types",
+ "scripts": {},
+ "homepage": "https://github.com/stdlib-js/stdlib",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/stdlib-js/stdlib.git"
+ },
+ "bugs": {
+ "url": "https://github.com/stdlib-js/stdlib/issues"
+ },
+ "dependencies": {
+ "@stdlib/string/next-grapheme-cluster-break": "^0.2.1",
+ "@stdlib/string/num-grapheme-clusters": "^0.2.1"
+ },
+ "devDependencies": {},
+ "engines": {
+ "node": ">=0.10.0",
+ "npm": ">2.7.0"
+ },
+ "os": [
+ "aix",
+ "darwin",
+ "freebsd",
+ "linux",
+ "macos",
+ "openbsd",
+ "sunos",
+ "win32",
+ "windows"
+ ],
+ "keywords": [
+ "stdlib",
+ "stdstring",
+ "utilities",
+ "utility",
+ "utils",
+ "util",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short",
+ "grapheme",
+ "cluster"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/test/test.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/test/test.js
new file mode 100644
index 000000000000..9a68e931da62
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-cluster/test/test.js
@@ -0,0 +1,131 @@
+/**
+* @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 tape = require( 'tape' );
+var truncate = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+ t.ok( true, __filename );
+ t.strictEqual( typeof truncate, 'function', 'main export is a function' );
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified ' +
+ 'length', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = '...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 9;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 6;
+ expected = '🐺 W...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ' +
+ 'ending)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep😃';
+ actual = truncate( str, len, '😃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop foo bar';
+ len = 10;
+ expected = 'beep 🙃 🙃 🙃';
+ actual = truncate( str, len, ' 🙃 🙃 🙃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 8;
+ expected = '🐺 Wolf 🐺';
+ actual = truncate( str, len, '🐺' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate/README.md b/lib/node_modules/@stdlib/string/base/truncate/README.md
new file mode 100644
index 000000000000..e4369fff4fea
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/README.md
@@ -0,0 +1,104 @@
+
+
+# truncate
+
+> Truncate a string to a specified length in UTF-16 code units.
+
+
+
+## Usage
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate' );
+```
+
+#### truncate( str, len, ending )
+
+Truncates a string to a specified length in UTF-16 code units.
+
+```javascript
+var out = truncate( 'beep boop', 7, '...' );
+// returns 'beep...'
+
+out = truncate( 'beep boop', 5, '>>>' );
+// returns 'be>>>'
+```
+
+
+
+
+
+
+
+## Notes
+
+- This function assumes that the input arguments are valid. For input validation, use the top-level [`@stdlib/string/truncate`][@stdlib/string/truncate].
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 W...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[@stdlib/string/truncate]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/truncate
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/base/truncate/benchmark/benchmark.js
new file mode 100644
index 000000000000..1ff3214ecc3a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/benchmark/benchmark.js
@@ -0,0 +1,57 @@
+/**
+* @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 bench = require( '@stdlib/bench' );
+var randu = require( '@stdlib/random/base/randu' );
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var strings;
+ var out;
+ var i;
+
+ strings = [
+ 'beep boop',
+ 'foo bar',
+ 'hello world',
+ '🐺 Wolf Brothers 🐺',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( strings[ i % strings.length ], (randu() * 10)|0, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate/docs/repl.txt b/lib/node_modules/@stdlib/string/base/truncate/docs/repl.txt
new file mode 100644
index 000000000000..830be76a7f25
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/docs/repl.txt
@@ -0,0 +1,31 @@
+{{alias}}( str, len, ending )
+ Truncates a string to a specified length in UTF-16 code units.
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: NonNegativeInteger
+ Output string length (including ending).
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var out = {{alias}}( 'beep boop', 7, '...' )
+ 'beep...'
+ > out = {{alias}}( 'beep boop', 5, '>>>' )
+ 'be>>>'
+ > out = {{alias}}( 'foo bar', 10, '...' )
+ 'foo bar'
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/truncate/docs/types/index.d.ts
new file mode 100644
index 000000000000..2d9aa29d6f0a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/docs/types/index.d.ts
@@ -0,0 +1,42 @@
+/**
+* @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.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* Truncates a string to a specified length in UTF-16 code units.
+*
+* @param str - input string
+* @param len - output string length
+* @param ending - custom ending
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+declare function truncate( str: string, len: number, ending: string ): string;
+
+
+// EXPORTS //
+
+export = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/truncate/docs/types/test.ts
new file mode 100644
index 000000000000..02a9ffaf41ba
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/docs/types/test.ts
@@ -0,0 +1,71 @@
+/*
+* @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.
+*/
+
+import truncate = require( './index' );
+
+
+// TESTS //
+
+// The function returns a string...
+{
+ truncate( 'beep boop', 5, '...' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a string...
+{
+ truncate( 5, 5, '...' ); // $ExpectError
+ truncate( false, 5, '...' ); // $ExpectError
+ truncate( true, 5, '...' ); // $ExpectError
+ truncate( null, 5, '...' ); // $ExpectError
+ truncate( undefined, 5, '...' ); // $ExpectError
+ truncate( [], 5, '...' ); // $ExpectError
+ truncate( {}, 5, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 5, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a number...
+{
+ truncate( 'beep boop', '5', '...' ); // $ExpectError
+ truncate( 'beep boop', false, '...' ); // $ExpectError
+ truncate( 'beep boop', true, '...' ); // $ExpectError
+ truncate( 'beep boop', null, '...' ); // $ExpectError
+ truncate( 'beep boop', undefined, '...' ); // $ExpectError
+ truncate( 'beep boop', [], '...' ); // $ExpectError
+ truncate( 'beep boop', {}, '...' ); // $ExpectError
+ truncate( 'beep boop', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not a string...
+{
+ truncate( 'beep boop', 5, 5 ); // $ExpectError
+ truncate( 'beep boop', 5, false ); // $ExpectError
+ truncate( 'beep boop', 5, true ); // $ExpectError
+ truncate( 'beep boop', 5, null ); // $ExpectError
+ truncate( 'beep boop', 5, undefined ); // $ExpectError
+ truncate( 'beep boop', 5, [] ); // $ExpectError
+ truncate( 'beep boop', 5, {} ); // $ExpectError
+ truncate( 'beep boop', 5, ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'beep boop' ); // $ExpectError
+ truncate( 'beep boop', 5 ); // $ExpectError
+ truncate( 'beep boop', 5, '...', 10 ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate/examples/index.js b/lib/node_modules/@stdlib/string/base/truncate/examples/index.js
new file mode 100644
index 000000000000..87c286335772
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/examples/index.js
@@ -0,0 +1,36 @@
+/**
+* @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';
+
+var truncate = require( './../lib' );
+
+console.log( truncate( 'beep boop', 7, '...' ) );
+// => 'beep...'
+
+console.log( truncate( 'beep boop', 5, '>>>' ) );
+// => 'be>>>'
+
+console.log( truncate( '🐺 Wolf Brothers 🐺', 7, '...' ) );
+// => '🐺 W...'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 2, '...' ) );
+// => '..'
+
+console.log( truncate( '🐶🐮🐷🐰🐸', 10, '...' ) );
+// => '🐶🐮🐷🐰🐸'
diff --git a/lib/node_modules/@stdlib/string/base/truncate/lib/index.js b/lib/node_modules/@stdlib/string/base/truncate/lib/index.js
new file mode 100644
index 000000000000..b9ae3f98f641
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @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';
+
+/**
+* Truncate a string to a specified length in UTF-16 code units.
+*
+* @module @stdlib/string/base/truncate
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate' );
+*
+* var str = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* str = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/truncate/lib/main.js b/lib/node_modules/@stdlib/string/base/truncate/lib/main.js
new file mode 100644
index 000000000000..7073ef016ec5
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/lib/main.js
@@ -0,0 +1,76 @@
+/**
+* @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';
+
+// VARIABLES //
+
+var slice = String.prototype.slice;
+
+
+// MAIN //
+
+/**
+* Truncates a string to a specified length in UTF-16 code units.
+*
+* @param {string} str - input string
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} ending - custom ending
+* @returns {string} truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( '🐺 Wolf Brothers 🐺', 7, '...' );
+* // returns '🐺 W...'
+*
+* @example
+* var out = truncate( 'beep boop', 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var out = truncate( 'beep boop', 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var out = truncate( 'beep boop', 0, '...' );
+* // returns ''
+*
+* @example
+* var out = truncate( 'beep boop', 2, '...' );
+* // returns '..'
+*/
+function truncate( str, len, ending ) {
+ var endingLength;
+
+ endingLength = ending.length;
+ if ( len >= str.length ) {
+ return str;
+ }
+ if ( len - endingLength <= 0 ) {
+ return slice.call( ending, 0, len );
+ }
+ return slice.call( str, 0, len - endingLength ) + ending;
+}
+
+
+// EXPORTS //
+
+module.exports = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate/package.json b/lib/node_modules/@stdlib/string/base/truncate/package.json
new file mode 100644
index 000000000000..4c24bd078150
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/package.json
@@ -0,0 +1,68 @@
+{
+ "name": "@stdlib/string/base/truncate",
+ "version": "0.0.0",
+ "description": "Truncate a string to a specified length in UTF-16 code units.",
+ "license": "Apache-2.0",
+ "author": {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ },
+ "contributors": [
+ {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ }
+ ],
+ "main": "./lib",
+ "directories": {
+ "benchmark": "./benchmark",
+ "doc": "./docs",
+ "example": "./examples",
+ "lib": "./lib",
+ "test": "./test"
+ },
+ "types": "./docs/types",
+ "scripts": {},
+ "homepage": "https://github.com/stdlib-js/stdlib",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/stdlib-js/stdlib.git"
+ },
+ "bugs": {
+ "url": "https://github.com/stdlib-js/stdlib/issues"
+ },
+ "dependencies": {},
+ "devDependencies": {},
+ "engines": {
+ "node": ">=0.10.0",
+ "npm": ">2.7.0"
+ },
+ "os": [
+ "aix",
+ "darwin",
+ "freebsd",
+ "linux",
+ "macos",
+ "openbsd",
+ "sunos",
+ "win32",
+ "windows"
+ ],
+ "keywords": [
+ "stdlib",
+ "stdstring",
+ "utilities",
+ "utility",
+ "utils",
+ "util",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short",
+ "utf-16",
+ "code",
+ "unit"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate/test/test.js b/lib/node_modules/@stdlib/string/base/truncate/test/test.js
new file mode 100644
index 000000000000..c47ba418edbf
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/test/test.js
@@ -0,0 +1,143 @@
+/**
+* @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 tape = require( 'tape' );
+var truncate = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+ t.ok( true, __filename );
+ t.strictEqual( typeof truncate, 'function', 'main export is a function' );
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified ' +
+ 'length', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = '...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 9;
+ expected = 'beep boop';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 6;
+ expected = '🐺 ...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸';
+ len = 2;
+ expected = '..';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸';
+ len = 10;
+ expected = '🐶🐮🐷🐰🐸';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ' +
+ 'ending)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'bee😃';
+ actual = truncate( str, len, '😃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop foo bar';
+ len = 10;
+ expected = 'b 🙃 🙃 🙃';
+ actual = truncate( str, len, ' 🙃 🙃 🙃' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 8;
+ expected = '🐺 Wol🐺';
+ actual = truncate( str, len, '🐺' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
diff --git a/lib/node_modules/@stdlib/string/truncate/README.md b/lib/node_modules/@stdlib/string/truncate/README.md
index bf43e8eaff72..2802daa2a589 100644
--- a/lib/node_modules/@stdlib/string/truncate/README.md
+++ b/lib/node_modules/@stdlib/string/truncate/README.md
@@ -1,5 +1,4 @@
# truncate
@@ -40,23 +38,51 @@ limitations under the License.
var truncate = require( '@stdlib/string/truncate' );
```
-#### truncate( str, len\[, ending] )
+#### truncate( str, len\[, ending, options] )
Truncates a string to a specified length.
```javascript
-var out = truncate( 'beep boop', 7 );
+var str = 'beep boop';
+var out = truncate( str, 7 );
// returns 'beep...'
```
-By default, the truncated string is appended with `'...'`. To customize the truncated string, provide an `ending` argument:
+By default, the function truncates a string with `'...'`. To customize the `ending`, provide a third argument.
+
+```javascript
+var str = 'beep boop';
+var out = truncate( str, 5, '>>>' );
+// returns 'be>>>'
+```
+
+The function supports an `options` object with the following properties:
+
+- **mode**: type of "character" to truncate. Must be one of the following:
+ - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji).
+ - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics).
+ - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets).
+ - Default: `'grapheme'`.
+
+By default, the function truncates a string by its grapheme clusters. To truncate by code points or code units, set the `mode` option.
```javascript
-var out = truncate( 'beep boop', 7, '!' );
-// returns 'beep b!'
+var str = '🐺 Wolf Brothers 🐺';
-out = truncate( 'beep boop', 7, '!!!' );
-// returns 'beep!!!'
+var out = truncate( str, 7, {
+ 'mode': 'grapheme'
+});
+// returns '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_point'
+});
+// returns '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_unit'
+});
+// returns '🐺 W...'
```
@@ -79,26 +105,46 @@ out = truncate( 'beep boop', 7, '!!!' );
-
-
```javascript
var truncate = require( '@stdlib/string/truncate' );
+/* eslint-disable @cspell/spellchecker */
+
var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
var out = truncate( str, 14 );
-// returns 'Lorem ipsum...'
+console.log( out );
+// => 'Lorem ipsum...'
+
+/* eslint-enable @cspell/spellchecker */
str = 'To be or not to be, that is the question';
out = truncate( str, 19, '!' );
-// returns 'To be or not to be!'
+console.log( out );
+// => 'To be or not to be!'
str = 'The quick fox jumps over the lazy dog.';
out = truncate( str, 16, '...' );
-// returns 'The quick fox...'
+console.log( out );
+// => 'The quick fox...'
str = '🐺 Wolf Brothers 🐺';
-out = truncate( str, 6 );
-// returns '🐺 W...'
+out = truncate( str, 7, {
+ 'mode': 'grapheme'
+});
+console.log( out );
+// => '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_point'
+});
+console.log( out );
+// => '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_unit'
+});
+console.log( out );
+// => '🐺 W...'
```
diff --git a/lib/node_modules/@stdlib/string/truncate/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/truncate/docs/types/index.d.ts
index ad332539b54d..a53f7a6237fe 100644
--- a/lib/node_modules/@stdlib/string/truncate/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/truncate/docs/types/index.d.ts
@@ -18,7 +18,66 @@
// TypeScript Version: 4.1
-///
+/* eslint-disable @typescript-eslint/unified-signatures */
+
+/**
+* Interface describing function options.
+*/
+interface Options {
+ /**
+ * Specifies the type of characters to truncate (default: 'grapheme').
+ *
+ * ## Notes
+ *
+ * - The following option values are supported:
+ *
+ * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji).
+ * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics).
+ * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets).
+ */
+ mode?: 'grapheme' | 'code_point' | 'code_unit';
+}
+
+/**
+* Truncates a string to a specified length.
+*
+* @param str - input string
+* @param len - output string length (including ending)
+* @param ending - custom ending (default: `...`)
+* @param options - options
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7 );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*
+* @example
+* var out = truncate( '🐺 Wolf Brothers 🐺', 7, {
+* 'mode': 'grapheme'
+* } );
+* // returns '🐺 Wo...'
+*/
+declare function truncate( str: string, len: number, ending: string, options?: Options ): string;
+
+/**
+* Truncates a string to a specified length.
+*
+* @param str - input string
+* @param len - output string length (including ending)
+* @param options - options
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, {
+* 'mode': 'code_unit'
+* } );
+* // returns 'beep...'
+*/
+declare function truncate( str: string, len: number, options?: Options ): string;
/**
* Truncates a string to a specified length.
diff --git a/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts b/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts
index d97d791827c5..4ee66d463fc0 100644
--- a/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts
@@ -24,7 +24,9 @@ import truncate = require( './index' );
// The function returns a string...
{
truncate( 'abcdefghi', 3 ); // $ExpectType string
+ truncate( 'abcdefghi', 3, { 'mode': 'code_point' } ); // $ExpectType string
truncate( 'abcdefghi', 10, '|' ); // $ExpectType string
+ truncate( 'abcdefghi', 10, '|', { 'mode': 'grapheme' } ); // $ExpectType string
}
// The compiler throws an error if the function is not provided a string as its first argument...
@@ -42,23 +44,39 @@ import truncate = require( './index' );
truncate( 'abd', true ); // $ExpectError
truncate( 'abd', false ); // $ExpectError
truncate( 'abd', 'abc' ); // $ExpectError
- truncate( 'abd', [], 0 ); // $ExpectError
- truncate( 'abd', {}, 0 ); // $ExpectError
- truncate( 'abd', ( x: number ): number => x, 0 ); // $ExpectError
+ truncate( 'abd', [] ); // $ExpectError
+ truncate( 'abd', {} ); // $ExpectError
+ truncate( 'abd', ( x: number ): number => x ); // $ExpectError
}
-// The compiler throws an error if the function is not provided a string as its third argument...
+// The compiler throws an error if the function is not provided a string or options object as its third argument...
{
truncate( 'beep boop', 4, true ); // $ExpectError
truncate( 'beep boop', 4, false ); // $ExpectError
truncate( 'beep boop', 4, 123 ); // $ExpectError
- truncate( 'beep boop', 4, [], 0 ); // $ExpectError
- truncate( 'beep boop', 4, {}, 0 ); // $ExpectError
- truncate( 'beep boop', 4, ( x: number ): number => x, 0 ); // $ExpectError
+ truncate( 'beep boop', 4, [] ); // $ExpectError
+ truncate( 'beep boop', 4, ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an options argument which is not an object...
+{
+ truncate( 'beep boop', 4, '...', true ); // $ExpectError
+ truncate( 'beep boop', 4, '...', false ); // $ExpectError
+ truncate( 'beep boop', 4, '...', 123 ); // $ExpectError
+ truncate( 'beep boop', 4, '...', [] ); // $ExpectError
+ truncate( 'beep boop', 4, '...', 'abc' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a `mode` option which is not a recognized mode...
+{
+ truncate( 'beep boop', 4, { 'mode': 'abc' } ); // $ExpectError
+ truncate( 'beep boop', 4, { 'mode': 123 } ); // $ExpectError
+ truncate( 'beep boop', 4, '...', { 'mode': 'abc' } ); // $ExpectError
+ truncate( 'beep boop', 4, '...', { 'mode': 123 } ); // $ExpectError
}
// The compiler throws an error if the function is provided an unsupported number of arguments...
{
truncate(); // $ExpectError
- truncate( 'abc', 4, '|', true ); // $ExpectError
+ truncate( 'abc', 4, '|', {}, true ); // $ExpectError
}
diff --git a/lib/node_modules/@stdlib/string/truncate/examples/index.js b/lib/node_modules/@stdlib/string/truncate/examples/index.js
index fc548e10c49f..d80afbd29b62 100644
--- a/lib/node_modules/@stdlib/string/truncate/examples/index.js
+++ b/lib/node_modules/@stdlib/string/truncate/examples/index.js
@@ -20,11 +20,15 @@
var truncate = require( './../lib' );
+/* eslint-disable @cspell/spellchecker */
+
var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
var out = truncate( str, 14 );
console.log( out );
// => 'Lorem ipsum...'
+/* eslint-enable @cspell/spellchecker */
+
str = 'To be or not to be, that is the question';
out = truncate( str, 19, '!' );
console.log( out );
@@ -36,6 +40,20 @@ console.log( out );
// => 'The quick fox...'
str = '🐺 Wolf Brothers 🐺';
-out = truncate( str, 6 );
+out = truncate( str, 7, {
+ 'mode': 'grapheme'
+});
+console.log( out );
+// => '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_point'
+});
+console.log( out );
+// => '🐺 Wo...'
+
+out = truncate( str, 7, {
+ 'mode': 'code_unit'
+});
console.log( out );
// => '🐺 W...'
diff --git a/lib/node_modules/@stdlib/string/truncate/lib/main.js b/lib/node_modules/@stdlib/string/truncate/lib/main.js
index 353dff40685d..133025764831 100644
--- a/lib/node_modules/@stdlib/string/truncate/lib/main.js
+++ b/lib/node_modules/@stdlib/string/truncate/lib/main.js
@@ -22,9 +22,24 @@
var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
-var numGraphemeClusters = require( '@stdlib/string/num-grapheme-clusters' );
-var nextGraphemeClusterBreak = require( '@stdlib/string/next-grapheme-cluster-break' );
+var isPlainObject = require( '@stdlib/assert/is-plain-object' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var contains = require( '@stdlib/array/base/assert/contains' ).factory;
var format = require( '@stdlib/string/format' );
+var truncateCodeUnit = require( '@stdlib/string/base/truncate' );
+var truncateCodePoint = require( '@stdlib/string/base/truncate-code-point' );
+var truncateGraphemeCluster = require( '@stdlib/string/base/truncate-grapheme-cluster' );
+
+
+// VARIABLES //
+
+var MODES = [ 'grapheme', 'code_point', 'code_unit' ];
+var FCNS = {
+ 'grapheme': truncateGraphemeCluster,
+ 'code_point': truncateCodePoint,
+ 'code_unit': truncateCodeUnit
+};
+var isMode = contains( MODES );
// MAIN //
@@ -33,11 +48,15 @@ var format = require( '@stdlib/string/format' );
* Truncates a string to a specified length.
*
* @param {string} str - input string
-* @param {integer} len - output string length (including ending)
-* @param {string} [ending='...'] - custom ending
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} [ending="..."] - custom ending
+* @param {Options} [options] - options
+* @param {string} [options.mode="grapheme"] - type of "character" to truncate (must be either `grapheme`, `code_point`, or `code_unit`)
* @throws {TypeError} first argument must be a string
* @throws {TypeError} second argument must be a nonnegative integer
-* @throws {TypeError} third argument must be a string
+* @throws {TypeError} third argument must be a string (if provided before options)
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
* @returns {string} truncated string
*
* @example
@@ -67,41 +86,55 @@ var format = require( '@stdlib/string/format' );
*
* @example
* var str = '🐺 Wolf Brothers 🐺';
-* var out = truncate( str, 6 );
-* // returns '🐺 W...'
+* var out = truncate( str, 7, {
+* 'mode': 'grapheme'
+* });
+* // returns '🐺 Wo...'
*/
-function truncate( str, len, ending ) {
- var endingLength;
- var fromIndex;
- var nVisual;
- var idx;
+function truncate( str, len ) {
+ var options;
+ var ending;
+ var nargs;
+ var opts;
+
if ( !isString( str ) ) {
throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );
}
if ( !isNonNegativeInteger( len ) ) {
throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', len ) );
}
- if ( arguments.length > 2 ) {
+ opts = {
+ 'mode': 'grapheme'
+ };
+ ending = '...';
+ nargs = arguments.length;
+ if ( nargs === 3 ) {
+ if ( isPlainObject( arguments[ 2 ] ) ) {
+ options = arguments[ 2 ];
+ } else if ( isString( arguments[ 2 ] ) ) {
+ ending = arguments[ 2 ];
+ } else {
+ throw new TypeError( format( 'invalid argument. Third argument must be either a string or an options object. Value: `%s`.', arguments[ 2 ] ) );
+ }
+ } else if ( nargs > 3 ) {
+ ending = arguments[ 2 ];
if ( !isString( ending ) ) {
throw new TypeError( format( 'invalid argument. Third argument must be a string. Value: `%s`.', ending ) );
}
+ options = arguments[ 3 ];
+ if ( !isPlainObject( options ) ) {
+ throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+ }
}
- ending = ending || '...';
- endingLength = numGraphemeClusters( ending );
- fromIndex = 0;
- if ( len >= numGraphemeClusters( str ) ) {
- return str;
- }
- if ( len - endingLength <= 0 ) {
- return ending.slice( 0, len );
- }
- nVisual = 0;
- while ( nVisual < len - endingLength ) {
- idx = nextGraphemeClusterBreak( str, fromIndex );
- fromIndex = idx;
- nVisual += 1;
+ if ( options ) {
+ if ( hasOwnProp( options, 'mode' ) ) {
+ opts.mode = options.mode;
+ if ( !isMode( opts.mode ) ) {
+ throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) );
+ }
+ }
}
- return str.substring( 0, idx ) + ending;
+ return FCNS[ opts.mode ]( str, len, ending );
}
diff --git a/lib/node_modules/@stdlib/string/truncate/test/test.js b/lib/node_modules/@stdlib/string/truncate/test/test.js
index 02a6531ffec4..0cd845f0bfee 100644
--- a/lib/node_modules/@stdlib/string/truncate/test/test.js
+++ b/lib/node_modules/@stdlib/string/truncate/test/test.js
@@ -54,7 +54,7 @@ tape( 'the function throws an error if not provided a string primitive', functio
function badValue( value ) {
return function badValue() {
- truncate( value );
+ truncate( value, 5 );
};
}
});
@@ -88,7 +88,7 @@ tape( 'the function throws an error if not provided a nonnegative integer as its
}
});
-tape( 'the function throws an error if provided a non-string as a third argument', function test( t ) {
+tape( 'the function throws an error if provided a non-string or non-options object as a third argument', function test( t ) {
var values;
var i;
@@ -99,7 +99,6 @@ tape( 'the function throws an error if provided a non-string as a third argument
void 0,
true,
[],
- {},
function noop() {}
];
@@ -115,7 +114,66 @@ tape( 'the function throws an error if provided a non-string as a third argument
}
});
-tape( 'the function truncates a string to the specified length', function test( t ) {
+tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ '5',
+ 5,
+ NaN,
+ null,
+ void 0,
+ true,
+ [],
+ function noop() {}
+ ];
+
+ 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() {
+ truncate( 'beep boop', 5, '...', value );
+ };
+ }
+});
+
+tape( 'the function throws an error if provided a `mode` option which is not a recognized mode', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ '5',
+ 'abc',
+ 'graphemes',
+ 5,
+ NaN,
+ null,
+ void 0,
+ true,
+ [],
+ {},
+ function noop() {}
+ ];
+
+ 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() {
+ truncate( 'beep boop', 5, {
+ 'mode': value
+ });
+ };
+ }
+});
+
+tape( 'the function truncates a string to the specified length (default mode)', function test( t ) {
var expected;
var actual;
var str;
@@ -133,34 +191,61 @@ tape( 'the function truncates a string to the specified length', function test(
actual = truncate( str, len );
t.strictEqual( actual, expected, 'returns expected value' );
- str = 'beep boop';
- len = 0;
- expected = '';
+ str = '🐺 Wolf Brothers 🐺';
+ len = 7;
+ expected = '🐺 Wo...';
actual = truncate( str, len );
t.strictEqual( actual, expected, 'returns expected value' );
- str = 'beep boop';
- len = 1;
- expected = '.';
- actual = truncate( str, len );
- t.strictEqual( actual, expected, 'returns expected value' );
+ t.end();
+});
- str = 'beep boop';
- len = 3;
- expected = '...';
- actual = truncate( str, len );
+tape( 'the function truncates a string to the specified length (grapheme mode)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 7;
+ expected = '🐺 Wo...';
+ actual = truncate( str, len, {
+ 'mode': 'grapheme'
+ });
t.strictEqual( actual, expected, 'returns expected value' );
- str = 'beep boop';
- len = 9;
- expected = 'beep boop';
- actual = truncate( str, len );
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (code_point mode)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 7;
+ expected = '🐺 Wo...';
+ actual = truncate( str, len, {
+ 'mode': 'code_point'
+ });
t.strictEqual( actual, expected, 'returns expected value' );
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (code_unit mode)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
str = '🐺 Wolf Brothers 🐺';
- len = 6;
+ len = 7;
expected = '🐺 W...';
- actual = truncate( str, len );
+ actual = truncate( str, len, {
+ 'mode': 'code_unit'
+ });
t.strictEqual( actual, expected, 'returns expected value' );
t.end();
@@ -178,34 +263,12 @@ tape( 'the function truncates a string to the specified length (custom ending)',
actual = truncate( str, len, '|' );
t.strictEqual( actual, expected, 'returns expected value' );
- str = 'beep boop';
- len = 10;
- expected = 'beep boop';
- actual = truncate( str, len, '!' );
- t.strictEqual( actual, expected, 'returns expected value' );
-
- str = 'beep boop';
- len = 3;
- expected = 'be!';
- actual = truncate( str, len, '!' );
- t.strictEqual( actual, expected, 'returns expected value' );
-
- str = 'beep boop';
- len = 5;
- expected = 'beep😃';
- actual = truncate( str, len, '😃' );
- t.strictEqual( actual, expected, 'returns expected value' );
-
- str = 'beep boop foo bar';
- len = 10;
- expected = 'beep 🙃 🙃 🙃';
- actual = truncate( str, len, ' 🙃 🙃 🙃' );
- t.strictEqual( actual, expected, 'returns expected value' );
-
str = '🐺 Wolf Brothers 🐺';
len = 8;
expected = '🐺 Wolf 🐺';
- actual = truncate( str, len, '🐺' );
+ actual = truncate( str, len, '🐺', {
+ 'mode': 'grapheme'
+ });
t.strictEqual( actual, expected, 'returns expected value' );
t.end();