diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/README.md b/lib/node_modules/@stdlib/string/base/truncate-code-points/README.md
new file mode 100644
index 000000000000..9b363560f035
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/README.md
@@ -0,0 +1,95 @@
+
+
+# truncateCodePoints
+
+> Truncate the Unicode code points of a provided string in order to return a string having a specified number of Unicode code points.
+
+
+
+## Usage
+
+```javascript
+var truncateCodePoints = require( '@stdlib/string/base/truncate-code-points' );
+```
+
+#### truncateCodePoints( str, len, ending )
+
+Truncates the Unicode code points of a provided string in order to return a string having a specified number of Unicode code points.
+
+```javascript
+var out = truncateCodePoints( 'beep boop', 7, '...' );
+// returns 'beep...'
+
+out = truncateCodePoints( 'beep boop', 7, '!' );
+// returns 'beep b!'
+
+out = truncateCodePoints( 'beep boop', 7, '!!!' );
+// returns 'beep!!!'
+```
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncateCodePoints = require( '@stdlib/string/base/truncate-code-points' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncateCodePoints( str, 14, '...' );
+// returns 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncateCodePoints( str, 19, '!' );
+// returns 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncateCodePoints( str, 16, '...' );
+// returns 'The quick fox...'
+
+out = truncateCodePoints( 'अनुच्छेद', 7, '...' );
+// returns 'अनुच...'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/base/truncate-code-points/benchmark/benchmark.js
new file mode 100644
index 000000000000..3cc63bb9f4aa
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/benchmark/benchmark.js
@@ -0,0 +1,56 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var values;
+ var out;
+ var i;
+
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 7, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/repl.txt b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/repl.txt
new file mode 100644
index 000000000000..d80ed1ce5cff
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/repl.txt
@@ -0,0 +1,32 @@
+
+{{alias}}( str, len, ending )
+ Truncate the Unicode code points of a provided string in order to return a
+ string having a specified number of Unicode code points.
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: integer
+ Output string length.
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var str = 'beep boop';
+ > var out = {{alias}}( str, 5, '...' )
+ 'be...'
+ > out = {{alias}}( str, 5, '|' )
+ 'beep|'
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/index.d.ts
new file mode 100644
index 000000000000..b806e98ca475
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/index.d.ts
@@ -0,0 +1,42 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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: 2.0
+
+/**
+* Truncates the Unicode code points of a provided string in order to return a string having a specified number of Unicode code points.
+*
+* @param str - input string
+* @param len - output string length (including ending)
+* @param ending - custom ending
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+declare function truncate( str: string, len: number, ending: string ): string;
+
+
+// EXPORTS //
+
+export = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/test.ts
new file mode 100644
index 000000000000..9028fe5e9e6f
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/docs/types/test.ts
@@ -0,0 +1,68 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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( 'abcdefghi', 10, '|' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a value other than a string as its first argument...
+{
+ truncate( true, 1, '...' ); // $ExpectError
+ truncate( false, 1, '...' ); // $ExpectError
+ truncate( null, 1, '...' ); // $ExpectError
+ truncate( undefined, 1, '...' ); // $ExpectError
+ truncate( 5, 1, '...' ); // $ExpectError
+ truncate( [], 1, '...' ); // $ExpectError
+ truncate( {}, 1, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 1, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument that is not a number...
+{
+ truncate( 'abc', true, '...' ); // $ExpectError
+ truncate( 'abc', false, '...' ); // $ExpectError
+ truncate( 'abc', null, '...' ); // $ExpectError
+ truncate( 'abc', 'abc', '...' ); // $ExpectError
+ truncate( 'abc', [], '...' ); // $ExpectError
+ truncate( 'abc', {}, '...' ); // $ExpectError
+ truncate( 'abc', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument that is not a string...
+{
+ truncate( 'beep boop', 4, true ); // $ExpectError
+ truncate( 'beep boop', 4, false ); // $ExpectError
+ truncate( 'beep boop', 4, null ); // $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
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'abc' ); // $ExpectError
+ truncate( 'abc', 1, '.', true ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/examples/index.js b/lib/node_modules/@stdlib/string/base/truncate-code-points/examples/index.js
new file mode 100644
index 000000000000..50076dc4a4fd
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/examples/index.js
@@ -0,0 +1,41 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncate( str, 14, '...' );
+console.log( out );
+// => 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncate( str, 19, '!' );
+console.log( out );
+// => 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncate( str, 16, '...' );
+console.log( out );
+// => 'The quick fox...'
+
+str = 'अनुच्छेद';
+out = truncate( str, 7, '...' );
+console.log( out );
+// => 'अनुच...'
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/index.js b/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/index.js
new file mode 100644
index 000000000000..9e30c6f20ff4
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 the Unicode code points of a provided string in order to return a string having a specified number of Unicode code points.
+*
+* @module @stdlib/string/base/truncate-code-points
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate-code-points' );
+*
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/main.js b/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/main.js
new file mode 100644
index 000000000000..88dca150c5e4
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/lib/main.js
@@ -0,0 +1,118 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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' );
+
+
+// VARIABLES //
+
+var RE_UTF16_LOW_SURROGATE = /[\uDC00-\uDFFF]/; // TODO: replace with stdlib pkg
+var RE_UTF16_HIGH_SURROGATE = /[\uD800-\uDBFF]/; // TODO: replace with stdlib pkg
+
+
+// MAIN //
+
+/**
+* Truncates the Unicode code points of a provided string in order to return a string having a specified number of Unicode 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 str = 'beep boop';
+* var out = truncate( str, 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 0, '...' );
+* // returns ''
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 2, '...' );
+* // returns '..'
+*/
+function truncate( str, len, ending ) {
+ var endingLength;
+ var strLength;
+ var ch1;
+ var ch2;
+ var out;
+ var i;
+
+ if ( len <= 0 ) {
+ return '';
+ }
+ strLength = numCodePoints( str );
+ if ( len >= strLength ) {
+ return str;
+ }
+ endingLength = numCodePoints( ending );
+ if ( endingLength >= len ) {
+ str = ending;
+ ending = '';
+ endingLength = 0;
+ }
+ out = '';
+
+ // Process the string one code unit at a time and count UTF-16 surrogate pairs as a single Unicode code point...
+ for ( i = 0; i < len - endingLength; i++ ) {
+ ch1 = str[ i ];
+
+ // Check for a high UTF-16 surrogate...
+ if ( RE_UTF16_HIGH_SURROGATE.test( ch1 ) ) {
+ // Check for an unpaired surrogate at the end of the input string...
+ if ( i === len - endingLength - 1 ) {
+ // We found an unpaired surrogate...
+ break;
+ }
+ // Check whether the high surrogate is paired with a low surrogate...
+ ch2 = str[ i+1 ];
+ if ( RE_UTF16_LOW_SURROGATE.test( ch2 ) ) {
+ // We found a surrogate pair:
+ i += 1; // bump the index to process the next code unit
+ out += ch1 + ch2;
+ }
+ } else {
+ out += ch1;
+ }
+ }
+ return out + ending;
+}
+
+
+// EXPORTS //
+
+module.exports = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/package.json b/lib/node_modules/@stdlib/string/base/truncate-code-points/package.json
new file mode 100644
index 000000000000..322b60b63998
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/package.json
@@ -0,0 +1,66 @@
+{
+ "name": "@stdlib/string/base/truncate-code-points",
+ "version": "0.0.0",
+ "description": "Truncate the Unicode code points of a provided string in order to return a string having a specified number of Unicode 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": {},
+ "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",
+ "pad",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-code-points/test/test.js b/lib/node_modules/@stdlib/string/base/truncate-code-points/test/test.js
new file mode 100644
index 000000000000..eeb9bd58abb4
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-code-points/test/test.js
@@ -0,0 +1,174 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 = 'अनुच्छेद';
+ len = 7;
+ expected = 'अनुच...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六書';
+ len = 4;
+ expected = '六...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '𐒻𐓟𐒻𐓟𐒻𐓟𐒻𐓟𐒻𐓟';
+ len = 5;
+ expected = '𐒻...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '\uD800𐓟𐒻𐓟𐒻𐓟𐒻𐓟𐒻𐓟';
+ len = 4;
+ 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 = 'अनुच्छेद';
+ len = 7;
+ expected = 'अनुच् &';
+ actual = truncate( str, len, ' &' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六書';
+ len = 4;
+ expected = '六书/&';
+ actual = truncate( str, len, '&' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 4;
+ expected = '六书/六';
+ actual = truncate( str, len, '書' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 4;
+ expected = '六书/六';
+ actual = truncate( str, len, '' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (truncate ending)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ 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 = 'aaa ';
+ len = 2;
+ expected = 'अन';
+ actual = truncate( str, len, 'अनुच्छेद' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 3;
+ expected = '六书書';
+ actual = truncate( str, len, '書' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/README.md b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/README.md
new file mode 100644
index 000000000000..27b9164fda75
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/README.md
@@ -0,0 +1,102 @@
+
+
+# truncateGraphemeClusters
+
+> Truncate grapheme clusters of a string to a specified length.
+
+
+
+## Usage
+
+```javascript
+var truncateGraphemeClusters = require( '@stdlib/string/base/truncate-grapheme-clusters' );
+```
+
+#### truncateGraphemeClusters( str, len, ending )
+
+Truncates grapheme clusters of a string to a specified length.
+
+```javascript
+var out = truncateGraphemeClusters( 'beep boop', 7, '...' );
+// returns 'beep...'
+```
+
+By default, the truncated string is appended with `'...'`. To customize the truncated string, provide an `ending` argument:
+
+```javascript
+var out = truncateGraphemeClusters( 'beep boop', 7, '!' );
+// returns 'beep b!'
+
+out = truncateGraphemeClusters( 'beep boop', 7, '!!!' );
+// returns 'beep!!!'
+```
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncateGraphemeClusters = require( '@stdlib/string/base/truncate-grapheme-clusters' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncateGraphemeClusters( str, 14, '...' );
+// returns 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncateGraphemeClusters( str, 19, '!' );
+// returns 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncateGraphemeClusters( str, 16, '...' );
+// returns 'The quick fox...'
+
+out = truncateGraphemeClusters( 'अनुच्छेद', 4, '...' );
+// returns 'अ...'
+
+out = truncateGraphemeClusters( '🌷🌷🌷🌷🌷', 4, '...' );
+// returns '🌷...'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/benchmark/benchmark.js
new file mode 100644
index 000000000000..153966ae4f62
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/benchmark/benchmark.js
@@ -0,0 +1,56 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var values;
+ var out;
+ var i;
+
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 1, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/repl.txt b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/repl.txt
new file mode 100644
index 000000000000..c10fc96a4bf2
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/repl.txt
@@ -0,0 +1,32 @@
+
+{{alias}}( str, len, ending )
+ Truncate grapheme clusters of a string to a specified length.
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: integer
+ Output string length.
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var str = 'beep boop';
+ > var out = {{alias}}( str, 5, '...' )
+ 'be...'
+
+ > out = {{alias}}( str, 5, '|' )
+ 'beep|'
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/index.d.ts
new file mode 100644
index 000000000000..06475d8df82b
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/index.d.ts
@@ -0,0 +1,42 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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: 2.0
+
+/**
+* Truncate grapheme clusters of a string to a specified length.
+*
+* @param str - input string
+* @param len - output string length (including ending)
+* @param ending - ending
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+declare function truncate( str: string, len: number, ending: string ): string;
+
+
+// EXPORTS //
+
+export = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/test.ts
new file mode 100644
index 000000000000..9028fe5e9e6f
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/docs/types/test.ts
@@ -0,0 +1,68 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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( 'abcdefghi', 10, '|' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a value other than a string as its first argument...
+{
+ truncate( true, 1, '...' ); // $ExpectError
+ truncate( false, 1, '...' ); // $ExpectError
+ truncate( null, 1, '...' ); // $ExpectError
+ truncate( undefined, 1, '...' ); // $ExpectError
+ truncate( 5, 1, '...' ); // $ExpectError
+ truncate( [], 1, '...' ); // $ExpectError
+ truncate( {}, 1, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 1, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument that is not a number...
+{
+ truncate( 'abc', true, '...' ); // $ExpectError
+ truncate( 'abc', false, '...' ); // $ExpectError
+ truncate( 'abc', null, '...' ); // $ExpectError
+ truncate( 'abc', 'abc', '...' ); // $ExpectError
+ truncate( 'abc', [], '...' ); // $ExpectError
+ truncate( 'abc', {}, '...' ); // $ExpectError
+ truncate( 'abc', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument that is not a string...
+{
+ truncate( 'beep boop', 4, true ); // $ExpectError
+ truncate( 'beep boop', 4, false ); // $ExpectError
+ truncate( 'beep boop', 4, null ); // $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
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'abc' ); // $ExpectError
+ truncate( 'abc', 1, '.', true ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/examples/index.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/examples/index.js
new file mode 100644
index 000000000000..dfd803b7ca1f
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/examples/index.js
@@ -0,0 +1,46 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncate( str, 14, '...' );
+console.log( out );
+// => 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncate( str, 19, '!' );
+console.log( out );
+// => 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncate( str, 16, '...' );
+console.log( out );
+// => 'The quick fox...'
+
+str = 'अनुच्छेद';
+out = truncate( str, 4, '...' );
+console.log( out );
+// => 'अ...'
+
+str = '🌷🌷🌷🌷🌷';
+out = truncate( str, 4, '...' );
+console.log( out );
+// => '🌷...'
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/index.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/index.js
new file mode 100644
index 000000000000..f1f00dbf1980
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 grapheme clusters of a string to a specified length.
+*
+* @module @stdlib/string/base/truncate-grapheme-clusters
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate-grapheme-clusters' );
+*
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/main.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/main.js
new file mode 100644
index 000000000000..ec4643796cc7
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/lib/main.js
@@ -0,0 +1,96 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 grapheme clusters of a string to a specified length.
+*
+* @param {string} str - input string
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} ending - ending string
+* @returns {string} truncated string
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 0, '...' );
+* // returns ''
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 2, '...' );
+* // returns '..'
+*/
+function truncate( str, len, ending ) {
+ var endingLength;
+ var strLength;
+ var n;
+ var i;
+
+ if ( len <= 0 ) {
+ return '';
+ }
+ strLength = numGraphemeClusters( str );
+ if ( len >= strLength ) {
+ return str;
+ }
+ endingLength = numGraphemeClusters( ending );
+ if ( endingLength >= len ) {
+ str = ending;
+ ending = '';
+ endingLength = 0;
+ }
+ i = 0;
+ n = len - endingLength;
+ while ( n > 0 ) {
+ i = nextGraphemeClusterBreak( str, i );
+ n -= 1;
+ }
+ if ( i === -1 ) {
+ return str;
+ }
+ return str.substring( 0, i ) + ending;
+}
+
+
+// EXPORTS //
+
+module.exports = truncate;
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/package.json b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/package.json
new file mode 100644
index 000000000000..528c42f65e79
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/package.json
@@ -0,0 +1,66 @@
+{
+ "name": "@stdlib/string/base/truncate-grapheme-clusters",
+ "version": "0.0.0",
+ "description": "Truncate grapheme clusters of a string to a specified length.",
+ "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",
+ "pad",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/test/test.js b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/test/test.js
new file mode 100644
index 000000000000..59a84a6cb110
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate-grapheme-clusters/test/test.js
@@ -0,0 +1,186 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 = 'अनुच्छेद';
+ len = 4;
+ expected = 'अ...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六書';
+ len = 4;
+ expected = '六...';
+ actual = truncate( str, len, '...' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸🐸';
+ len = 5;
+ 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 = 'अनुच्छेद';
+ len = 4;
+ expected = 'अनु &';
+ actual = truncate( str, len, ' &' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六書';
+ len = 4;
+ expected = '六书/&';
+ actual = truncate( str, len, '&' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 4;
+ expected = '六书/六';
+ actual = truncate( str, len, '書' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 4;
+ expected = '六书/六';
+ actual = truncate( str, len, '' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶🐮🐷🐰🐸';
+ len = 3;
+ 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' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (truncate ending)', function test( t ) {
+ var expected;
+ var actual;
+ var str;
+ var len;
+
+ str = 'beep boop';
+ len = 5;
+ 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 = 'aaa ';
+ len = 2;
+ expected = 'अनु';
+ actual = truncate( str, len, 'अनुच्छेद' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '六书/六';
+ len = 3;
+ expected = '六书書';
+ actual = truncate( str, len, '書' );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐶a🐮🐷🐰🐸';
+ len = 4;
+ expected = '🐶a🌷🌷';
+ 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..e333022a31a4
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/README.md
@@ -0,0 +1,96 @@
+
+
+# truncate
+
+> Truncate UTF-16 code units of a string to a specified length.
+
+
+
+## Usage
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate' );
+```
+
+#### truncate( str, len, ending )
+
+Truncates UTF-16 code units of a string to a specified length.
+
+```javascript
+var out = truncate( 'beep boop', 7, '...' );
+// returns 'beep...'
+```
+
+By default, the truncated string is appended with `'...'`. To customize the truncated string, provide an `ending` argument:
+
+```javascript
+var out = truncate( 'beep boop', 7, '!' );
+// returns 'beep b!'
+
+out = truncate( 'beep boop', 7, '!!!' );
+// returns 'beep!!!'
+```
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var truncate = require( '@stdlib/string/base/truncate' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncate( str, 14, '...' );
+// returns 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncate( str, 19, '!' );
+// returns 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncate( str, 16, '...' );
+// returns 'The quick fox...'
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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..153966ae4f62
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/benchmark/benchmark.js
@@ -0,0 +1,56 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var truncate = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var values;
+ var out;
+ var i;
+
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc',
+ '🐶🐮🐷🐰🐸'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 1, '...' );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ 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..b72a44d800e3
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/docs/repl.txt
@@ -0,0 +1,32 @@
+
+{{alias}}( str, len, ending )
+ Truncate UTF-16 code units of a string to a specified length.
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ len: integer
+ Output string length.
+
+ ending: string
+ Custom ending.
+
+ Returns
+ -------
+ out: string
+ Output string.
+
+ Examples
+ --------
+ > var str = 'beep boop';
+ > var out = {{alias}}( str, 5, '...' )
+ 'be...'
+
+ > out = {{alias}}( str, 5, '|' )
+ 'beep|'
+
+ 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..5eb9072643dd
--- /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) 2023 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: 2.0
+
+/**
+* Truncate UTF-16 code units of a string to a specified length.
+*
+* @param str - input string
+* @param len - output string length (including ending)
+* @param ending - ending string
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+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..f86bd37ddaf8
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/docs/types/test.ts
@@ -0,0 +1,69 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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( 'abc', 1, '...' ); // $ExpectType string
+ truncate( 'abcdefghi', 10, '|' ); // $ExpectType string
+}
+
+// The compiler throws an error if the function is provided a value other than a string as its first argument...
+{
+ truncate( true, 1, '...' ); // $ExpectError
+ truncate( false, 1, '...' ); // $ExpectError
+ truncate( null, 1, '...' ); // $ExpectError
+ truncate( undefined, 1, '...' ); // $ExpectError
+ truncate( 5, 1, '...' ); // $ExpectError
+ truncate( [], 1, '...' ); // $ExpectError
+ truncate( {}, 1, '...' ); // $ExpectError
+ truncate( ( x: number ): number => x, 1, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument that is not a number...
+{
+ truncate( 'abc', true, '...' ); // $ExpectError
+ truncate( 'abc', false, '...' ); // $ExpectError
+ truncate( 'abc', null, '...' ); // $ExpectError
+ truncate( 'abc', 'abc', '...' ); // $ExpectError
+ truncate( 'abc', [], '...' ); // $ExpectError
+ truncate( 'abc', {}, '...' ); // $ExpectError
+ truncate( 'abc', ( x: number ): number => x, '...' ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument that is not a string...
+{
+ truncate( 'beep boop', 4, true ); // $ExpectError
+ truncate( 'beep boop', 4, false ); // $ExpectError
+ truncate( 'beep boop', 4, null ); // $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
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+ truncate(); // $ExpectError
+ truncate( 'abc' ); // $ExpectError
+ truncate( 'abc', 1, '.', true ); // $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..323f68cd813e
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/examples/index.js
@@ -0,0 +1,36 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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' );
+
+var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';
+var out = truncate( str, 14, '...' );
+console.log( out );
+// => 'Lorem ipsum...'
+
+str = 'To be or not to be, that is the question';
+out = truncate( str, 19, '!' );
+console.log( out );
+// => 'To be or not to be!'
+
+str = 'The quick fox jumps over the lazy dog.';
+out = truncate( str, 16, '...' );
+console.log( out );
+// => 'The quick fox...'
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..a590f0f08e30
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 UTF-16 code units of a string to a specified length.
+*
+* @module @stdlib/string/base/truncate
+*
+* @example
+* var truncate = require( '@stdlib/string/base/truncate' );
+*
+* var out = truncate( 'beep boop', 7, '...' );
+* // returns 'beep...'
+*
+* out = truncate( 'beep boop', 7, '|' );
+* // returns 'beep b|'
+*/
+
+// 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..36b960101976
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/lib/main.js
@@ -0,0 +1,69 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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';
+
+// MAIN //
+
+/**
+* Truncates UTF-16 code units of a string to a specified length.
+*
+* @param {string} str - input string
+* @param {NonNegativeInteger} len - output string length (including ending)
+* @param {string} ending - custom ending
+* @returns {string} truncated string
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 7, '...' );
+* // returns 'beep...'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 5, '>>>' );
+* // returns 'be>>>'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 10, '...' );
+* // returns 'beep boop'
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 0, '...' );
+* // returns ''
+*
+* @example
+* var str = 'beep boop';
+* var out = truncate( str, 2, '...' );
+* // returns '..'
+*/
+function truncate( str, len, ending ) {
+ if ( len >= str.length ) {
+ return str;
+ }
+ if ( len - ending.length < 0 ) {
+ return ending.slice( 0, len );
+ }
+ return str.substring( 0, len - ending.length ) + 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..60596d188b0f
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/package.json
@@ -0,0 +1,66 @@
+{
+ "name": "@stdlib/string/base/truncate",
+ "version": "0.0.0",
+ "description": "Truncate UTF-16 code units of a string to a specified length.",
+ "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",
+ "pad",
+ "string",
+ "str",
+ "truncate",
+ "trunc",
+ "shorten",
+ "short"
+ ]
+}
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..b089ed55a325
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/base/truncate/test/test.js
@@ -0,0 +1,93 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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' );
+
+ 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' );
+
+ t.end();
+});
diff --git a/lib/node_modules/@stdlib/string/num-code-points/README.md b/lib/node_modules/@stdlib/string/num-code-points/README.md
new file mode 100644
index 000000000000..33f4c9441b53
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/README.md
@@ -0,0 +1,152 @@
+
+
+# numCodePoints
+
+> Return the number of Unicode code points in a string.
+
+
+
+## Usage
+
+```javascript
+var numCodePoints = require( '@stdlib/string/num-code-points' );
+```
+
+#### numCodePoints( str )
+
+Returns the number of code points in a string.
+
+```javascript
+var out = numCodePoints( 'last man standing' );
+// returns 17
+
+out = numCodePoints( 'Hidden Treasures' );
+// returns 16
+
+out = numCodePoints( '𐒻𐓟𐒻𐓟' );
+// returns 4
+```
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var numCodePoints = require( '@stdlib/string/num-code-points' );
+
+var out = numCodePoints( 'last man standing' );
+// returns 17
+
+out = numCodePoints( '六书/六書' );
+// returns 5
+
+out = numCodePoints( 'अनुच्छेद' );
+// returns 8
+
+out = numCodePoints( '𐒻𐓟𐒻𐓟' );
+// returns 4
+```
+
+
+
+
+
+* * *
+
+
+
+## CLI
+
+
+
+### Usage
+
+```text
+Usage: num-code-points [options] []
+
+Options:
+
+ -h, --help Print this message.
+ -V, --version Print the package version.
+ -l, --lines Analyze individual lines.
+```
+
+
+
+
+
+
+
+### Examples
+
+```bash
+$ num-code-points beep
+4
+```
+
+To use as a [standard stream][standard-streams],
+
+```bash
+$ echo -n 'beep\nboop書' | num-code-points
+10
+```
+
+```bash
+$ echo -n 'beep\nboop書' | num-code-points -l
+4
+5
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[standard-streams]: https://en.wikipedia.org/wiki/Standard_streams
+
+
+
+
+
+
+
+
diff --git a/lib/node_modules/@stdlib/string/num-code-points/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/num-code-points/benchmark/benchmark.js
new file mode 100644
index 000000000000..8b0553116202
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/benchmark/benchmark.js
@@ -0,0 +1,62 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isInteger = require( '@stdlib/assert/is-integer' );
+var pkg = require( './../package.json' ).name;
+var numCodePoints = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+ var strings;
+ var out;
+ var i;
+
+ strings = [
+ 'last man standing',
+ 'presidential election',
+ 'अनुच्छेद',
+ '🌷',
+ '书/六書',
+ 'เ❄︎நி',
+ 'กิิก้้ก็็ก็็กิิก้้ก็็กิิก้้กิิก้้ก็็ก็็กิิก้้ก็็กิิก้้',
+ '書六/书六',
+ 'ܶƔλʃݖͱšɕ҆ʧѸؐҜҦɳΏ',
+ 'âݝΝҳӌݾҀƳ۵ۧǁǸΓ'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = numCodePoints( strings[ i%strings.length ] );
+ if ( out < 0 ) {
+ b.fail( 'should never be a negative integer' );
+ }
+ }
+ b.toc();
+ if ( !isInteger( out ) ) {
+ b.fail( 'should return an integer' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/num-code-points/bin/cli b/lib/node_modules/@stdlib/string/num-code-points/bin/cli
new file mode 100644
index 000000000000..a26c5c908def
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/bin/cli
@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 resolve = require( 'path' ).resolve;
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var CLI = require( '@stdlib/cli/ctor' );
+var stdin = require( '@stdlib/process/read-stdin' );
+var stdinStream = require( '@stdlib/streams/node/stdin' );
+var RE_EOL = require( '@stdlib/regexp/eol' ).REGEXP;
+var isRegExpString = require( '@stdlib/assert/is-regexp-string' );
+var reFromString = require( '@stdlib/utils/regexp-from-string' );
+var numCodePoints = require( './../lib' );
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+* @returns {void}
+*/
+function main() {
+ var flags;
+ var split;
+ var args;
+ var cli;
+
+ // Create a command-line interface:
+ cli = new CLI({
+ 'pkg': require( './../package.json' ),
+ 'options': require( './../etc/cli_opts.json' ),
+ 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
+ 'encoding': 'utf8'
+ })
+ });
+
+ // Get any provided command-line options:
+ flags = cli.flags();
+ if ( flags.help || flags.version ) {
+ return;
+ }
+
+ // Get any provided command-line arguments:
+ args = cli.args();
+
+ // Check if we are receiving data from `stdin`...
+ if ( !stdinStream.isTTY ) {
+ if ( flags.split ) {
+ if ( !isRegExpString( flags.split ) ) {
+ flags.split = '/'+flags.split+'/';
+ }
+ split = reFromString( flags.split );
+ } else {
+ split = RE_EOL;
+ }
+ return stdin( onRead );
+ }
+ console.log( numCodePoints( args[ 0 ] ) ); // eslint-disable-line no-console
+
+ /**
+ * Callback invoked upon reading from `stdin`.
+ *
+ * @private
+ * @param {(Error|null)} error - error object
+ * @param {Buffer} data - data
+ * @returns {void}
+ */
+ function onRead( error, data ) {
+ var lines;
+ var i;
+ if ( error ) {
+ return cli.error( error );
+ }
+ lines = data.toString().split( split );
+
+ // Remove any trailing separators (e.g., trailing newline)...
+ if ( lines[ lines.length-1 ] === '' ) {
+ lines.pop();
+ }
+ for ( i = 0; i < lines.length; i++ ) {
+ console.log( numCodePoints( lines[ i ] ) ); // eslint-disable-line no-console
+ }
+ }
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/string/num-code-points/docs/repl.txt b/lib/node_modules/@stdlib/string/num-code-points/docs/repl.txt
new file mode 100644
index 000000000000..ad4e0ac06058
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/docs/repl.txt
@@ -0,0 +1,24 @@
+
+{{alias}}( str )
+ Returns the number of code points in a string.
+
+ Parameters
+ ----------
+ str: string
+ Input string.
+
+ Returns
+ -------
+ out: string
+ Number of code points.
+
+ Examples
+ --------
+ > var out = {{alias}}( 'beep' )
+ 4
+ > out = {{alias}}( '六' )
+ 1
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/string/num-code-points/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/num-code-points/docs/types/index.d.ts
new file mode 100644
index 000000000000..cf3ec894ea60
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/docs/types/index.d.ts
@@ -0,0 +1,48 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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: 2.0
+
+/**
+* Returns the number of code points in a string.
+*
+* @param str - input string
+* @returns number of code points
+*
+* @example
+* var out = numCodePoints( 'last man standing' );
+* // returns 17
+*
+* @example
+* var out = numCodePoints( 'presidential election' );
+* // returns 21
+*
+* @example
+* var out = numCodePoints( '六' );
+* // returns 1
+*
+* @example
+* var out = numCodePoints( 'अनुच्छेद' );
+* // returns 5
+*/
+declare function numCodePoints( str: string ): number;
+
+
+// EXPORTS //
+
+export = numCodePoints;
diff --git a/lib/node_modules/@stdlib/string/num-code-points/docs/types/test.ts b/lib/node_modules/@stdlib/string/num-code-points/docs/types/test.ts
new file mode 100644
index 000000000000..f08f9c4993f3
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/docs/types/test.ts
@@ -0,0 +1,44 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 numCodePoints = require( './index' );
+
+
+// TESTS //
+
+// The function returns a number...
+{
+ numCodePoints( 'abc' ); // $ExpectType number
+}
+
+// The compiler throws an error if the function is provided a value other than a string...
+{
+ numCodePoints( true ); // $ExpectError
+ numCodePoints( false ); // $ExpectError
+ numCodePoints( null ); // $ExpectError
+ numCodePoints( undefined ); // $ExpectError
+ numCodePoints( 5 ); // $ExpectError
+ numCodePoints( [] ); // $ExpectError
+ numCodePoints( {} ); // $ExpectError
+ numCodePoints( ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided insufficient arguments...
+{
+ numCodePoints(); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/string/num-code-points/docs/usage.txt b/lib/node_modules/@stdlib/string/num-code-points/docs/usage.txt
new file mode 100644
index 000000000000..7ecfdfa2eeb0
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/docs/usage.txt
@@ -0,0 +1,9 @@
+
+Usage: num-code-points [options] []
+
+Options:
+
+ -h, --help Print this message.
+ -V, --version Print the package version.
+ -l, --lines Analyze individual lines.
+
diff --git a/lib/node_modules/@stdlib/string/num-code-points/etc/cli_opts.json b/lib/node_modules/@stdlib/string/num-code-points/etc/cli_opts.json
new file mode 100644
index 000000000000..d5d5629e9e27
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/etc/cli_opts.json
@@ -0,0 +1,18 @@
+{
+ "boolean": [
+ "help",
+ "version",
+ "lines"
+ ],
+ "alias": {
+ "help": [
+ "h"
+ ],
+ "version": [
+ "V"
+ ],
+ "lines": [
+ "l"
+ ]
+ }
+}
diff --git a/lib/node_modules/@stdlib/string/num-code-points/examples/index.js b/lib/node_modules/@stdlib/string/num-code-points/examples/index.js
new file mode 100644
index 000000000000..ec2c98168b18
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/examples/index.js
@@ -0,0 +1,33 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 numCodePoints = require( './../lib' );
+
+console.log( numCodePoints( 'last man standing' ) );
+// => 17
+
+console.log( numCodePoints( '六书/六書' ) );
+// => 5
+
+console.log( numCodePoints( 'अनुच्छेद' ) );
+// => 8
+
+console.log( numCodePoints( '𐒻𐓟𐒻𐓟' ) );
+// => 4
diff --git a/lib/node_modules/@stdlib/string/num-code-points/lib/index.js b/lib/node_modules/@stdlib/string/num-code-points/lib/index.js
new file mode 100644
index 000000000000..6adf273d4d87
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/lib/index.js
@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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';
+
+/**
+* Return the number of code points in a string.
+*
+* @module @stdlib/string/num-code-points
+*
+* @example
+* var numCodePoints = require( '@stdlib/string/num-code-points' );
+*
+* var out = numCodePoints( 'last man standing' );
+* // returns 17
+*
+* out = numCodePoints( '六' );
+* // returns 1
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/string/num-code-points/lib/main.js b/lib/node_modules/@stdlib/string/num-code-points/lib/main.js
new file mode 100644
index 000000000000..deb9e52ec083
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/lib/main.js
@@ -0,0 +1,89 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 format = require( '@stdlib/string/format' );
+
+
+// VARIABLES //
+
+var RE_UTF16_LOW_SURROGATE = /[\uDC00-\uDFFF]/; // TODO: replace with stdlib pkg
+var RE_UTF16_HIGH_SURROGATE = /[\uD800-\uDBFF]/; // TODO: replace with stdlib pkg
+
+
+// MAIN //
+
+/**
+* Returns the number of code points in a string.
+*
+* @param {string} str - input string
+* @throws {TypeError} must provide a string
+* @returns {NonNegativeInteger} number of code points
+*
+* @example
+* var out = numCodePoints( 'last man standing' );
+* // returns 17
+*
+* @example
+* var out = numCodePoints( 'presidential election' );
+* // returns 21
+*
+* @example
+* var out = numCodePoints( 'अनुच्छेद' );
+* // returns 8
+*/
+function numCodePoints( str ) {
+ var count;
+ var i;
+
+ if ( !isString( str ) ) {
+ throw new TypeError( format( 'invalid argument. Must provide a string. Value: `%s`.', str ) );
+ }
+ count = 0;
+
+ // Process the string one Unicode code unit at a time and count UTF-16 surrogate pairs as a single Unicode code point...
+ for ( i = 0; i < str.length; i++ ) {
+ // Check for a high UTF-16 surrogate...
+ if ( RE_UTF16_HIGH_SURROGATE.test( str[ i ] ) ) {
+ // Check for an unpaired surrogate at the end of the input string...
+ if ( i === str.length-1 ) {
+ // We found an unpaired surrogate...
+ count += 1;
+ break;
+ }
+ // Check whether the high surrogate is paired with a low surrogate...
+ if ( RE_UTF16_LOW_SURROGATE.test( str[ i+1 ] ) ) {
+ // We found a surrogate pair:
+ i += 1; // bump the index to process the next code unit
+ count += 1;
+ }
+ } else {
+ count += 1;
+ }
+ }
+ return count;
+}
+
+
+// EXPORTS //
+
+module.exports = numCodePoints;
diff --git a/lib/node_modules/@stdlib/string/num-code-points/package.json b/lib/node_modules/@stdlib/string/num-code-points/package.json
new file mode 100644
index 000000000000..dec608eca593
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/package.json
@@ -0,0 +1,73 @@
+{
+ "name": "@stdlib/string/num-code-points",
+ "version": "0.0.0",
+ "description": "Return the number of code points in a string.",
+ "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"
+ }
+ ],
+ "bin": {
+ "num-code-points": "./bin/cli"
+ },
+ "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",
+ "length",
+ "len",
+ "unicode",
+ "code",
+ "point",
+ "segmentation",
+ "surrogate",
+ "astral",
+ "emojis"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/string/num-code-points/test/fixtures/stdin_error.js.txt b/lib/node_modules/@stdlib/string/num-code-points/test/fixtures/stdin_error.js.txt
new file mode 100644
index 000000000000..b42c70b3b554
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/test/fixtures/stdin_error.js.txt
@@ -0,0 +1,33 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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.
+*/
+
+var proc = require( 'process' );
+var resolve = require( 'path' ).resolve;
+var proxyquire = require( 'proxyquire' );
+
+var fpath = resolve( __dirname, '..', 'bin', 'cli' );
+
+proc.stdin.isTTY = false;
+
+proxyquire( fpath, {
+ '@stdlib/process/read-stdin': stdin
+});
+
+function stdin( clbk ) {
+ clbk( new Error( 'beep' ) );
+}
diff --git a/lib/node_modules/@stdlib/string/num-code-points/test/test.cli.js b/lib/node_modules/@stdlib/string/num-code-points/test/test.cli.js
new file mode 100644
index 000000000000..cf60c613972c
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/test/test.cli.js
@@ -0,0 +1,261 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 resolve = require( 'path' ).resolve;
+var exec = require( 'child_process' ).exec;
+var tape = require( 'tape' );
+var IS_BROWSER = require( '@stdlib/assert/is-browser' );
+var IS_WINDOWS = require( '@stdlib/assert/is-windows' );
+var replace = require( '@stdlib/string/replace' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var EXEC_PATH = require( '@stdlib/process/exec-path' );
+
+
+// VARIABLES //
+
+var fpath = resolve( __dirname, '..', 'bin', 'cli' );
+var opts = {
+ 'skip': IS_BROWSER || IS_WINDOWS
+};
+
+
+// FIXTURES //
+
+var PKG_VERSION = require( './../package.json' ).version;
+
+
+// TESTS //
+
+tape( 'command-line interface', function test( t ) {
+ t.ok( true, __filename );
+ t.end();
+});
+
+tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) {
+ var expected;
+ var cmd;
+
+ expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
+ 'encoding': 'utf8'
+ });
+ cmd = [
+ EXEC_PATH,
+ fpath,
+ '--help'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString(), expected+'\n', 'expected value' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) {
+ var expected;
+ var cmd;
+
+ expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
+ 'encoding': 'utf8'
+ });
+ cmd = [
+ EXEC_PATH,
+ fpath,
+ '-h'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString(), expected+'\n', 'expected value' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ fpath,
+ '--version'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ fpath,
+ '-V'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' );
+ }
+ t.end();
+ }
+});
+
+tape( 'the command-line interface prints the number of code points', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ '-e',
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\\nboop\'; require( \''+fpath+'\' );"'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '9\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when invoked with a `-l` flag, the command-line interface prints the number of code points for individual lines', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ '-e',
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\\nboop\'; process.argv[ 3 ] = \'-l\'; require( \''+fpath+'\' );"'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '9\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
+tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) {
+ var cmd = [
+ 'printf "beep\nboop六"',
+ '|',
+ EXEC_PATH,
+ fpath
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '4\n5\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when used as a standard stream with `-l` flag, the command-line interface prints the number of code points for each line', opts, function test( t ) {
+ var cmd = [
+ 'printf "beep\nboop六"',
+ '|',
+ EXEC_PATH,
+ fpath,
+ '-l'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), '4\n5\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
+tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) {
+ var script;
+ var opts;
+ var cmd;
+
+ script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), {
+ 'encoding': 'utf8'
+ });
+
+ // Replace single quotes with double quotes:
+ script = replace( script, '\'', '"' );
+
+ cmd = [
+ EXEC_PATH,
+ '-e',
+ '\''+script+'\''
+ ];
+
+ opts = {
+ 'cwd': __dirname
+ };
+
+ exec( cmd.join( ' ' ), opts, done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.pass( error.message );
+ t.strictEqual( error.code, 1, 'expected exit code' );
+ }
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' );
+ t.end();
+ }
+});
diff --git a/lib/node_modules/@stdlib/string/num-code-points/test/test.js b/lib/node_modules/@stdlib/string/num-code-points/test/test.js
new file mode 100644
index 000000000000..1a440c7d529a
--- /dev/null
+++ b/lib/node_modules/@stdlib/string/num-code-points/test/test.js
@@ -0,0 +1,98 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 numCodePoints = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+ t.ok( true, __filename );
+ t.strictEqual( typeof numCodePoints, 'function', 'main export is a function' );
+ t.end();
+});
+
+tape( 'the function throws an error if not provided a string', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 5,
+ null,
+ true,
+ void 0,
+ NaN,
+ [],
+ {},
+ 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() {
+ numCodePoints( value );
+ };
+ }
+});
+
+tape( 'the function returns 0 if provided an empty string', function test( t ) {
+ t.strictEqual( numCodePoints( '' ), 0, 'returns expected value' );
+ t.end();
+});
+
+tape( 'the function returns the Unicode aware length of a provided string', function test( t ) {
+ var out;
+
+ out = numCodePoints( 'hello world' );
+ t.strictEqual( out, 11, 'returns expected value' );
+
+ out = numCodePoints( '!!!' );
+ t.strictEqual( out, 3, 'returns expected value' );
+
+ out = numCodePoints( 'अनुच्छेद' );
+ t.strictEqual( out, 8, 'returns expected value' );
+
+ out = numCodePoints( '六' );
+ t.strictEqual( out, 1, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function returns the number of code points (surrogates)', function test( t ) {
+ var out;
+
+ out = numCodePoints( '𐒻𐓟' );
+ t.strictEqual( out, 2, 'returns expected value' );
+
+ out = numCodePoints( '𐒻' );
+ t.strictEqual( out, 1, 'returns expected value' );
+
+ out = numCodePoints( '\uD800' ); // trailing unpaired high surrogate
+ t.strictEqual( out, 1, '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 bf86b54fe5e1..30b61a1950d1 100644
--- a/lib/node_modules/@stdlib/string/truncate/README.md
+++ b/lib/node_modules/@stdlib/string/truncate/README.md
@@ -20,7 +20,7 @@ limitations under the License.
# truncate
-> Truncate a string to a specified length.
+> Truncate a string.
@@ -40,9 +40,9 @@ limitations under the License.
var truncate = require( '@stdlib/string/truncate' );
```
-#### truncate( str, len\[, ending] )
+#### truncate( str, N\[, ending]\[, options] )
-Truncates a string to a specified length.
+Truncates a string.
```javascript
var out = truncate( 'beep boop', 7 );
@@ -59,6 +59,16 @@ out = truncate( 'beep boop', 7, '!!!' );
// returns 'beep!!!'
```
+The function supports the following options:
+
+- **mode**: type of characters to return. 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). When the `mode` is `'grapheme'`, `N` specifies the maximum number of grapheme clusters in the returned string.
+ - `'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). When the `mode` is `'code_point'`, `N` specifies the maximum number of Unicode code points in the returned string.
+ - `'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). When the `mode` is `'code_unit'`, `N` specifies the number of maximum number of UTF-16 code units in the returned string.
+
+ Default: `'grapheme'`.
+
@@ -67,6 +77,18 @@ out = truncate( 'beep boop', 7, '!!!' );
+## Notes
+
+- By default, the function assumes the general case in which an input string may contain an arbitrary number of grapheme clusters. This assumption comes with a performance cost. Accordingly, if an input string is known to only contain visual characters of a particular type (e.g., only alphanumeric), one can achieve better performance by specifying the appropriate `mode` option.
+
+
+
+
+
+
+
+
@@ -124,9 +146,10 @@ Options:
-h, --help Print this message.
-V, --version Print the package version.
- --len length String length.
+ --N length String length.
--ending str Custom ending. Default: '...'.
--split sep Delimiter for stdin data. Default: '/\\r?\\n/'.
+ --mode mode Type of character to return. Default: 'grapheme'.
```
@@ -143,10 +166,10 @@ Options:
```bash
# Not escaped...
- $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --len 6 --split /\r?\n/
+ $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --N 6 --split /\r?\n/
# Escaped...
- $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --len 6 --split /\\r?\\n/
+ $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --N 6 --split /\\r?\\n/
```
- The implementation ignores trailing delimiters.
@@ -164,24 +187,24 @@ Options:
### Examples
```bash
-$ truncate 'Hello, World!' --len 8
+$ truncate 'Hello, World!' --N 8
Hello...
-$ truncate 'Hello, World!' --len 6 --ending '!'
+$ truncate 'Hello, World!' --N 6 --ending '!'
Hello!
```
To use as a [standard stream][standard-streams],
```bash
-$ echo -n 'Hello, World!' | truncate --len 8
+$ echo -n 'Hello, World!' | truncate --N 8
Hello...
```
By default, when used as a [standard stream][standard-streams], the implementation assumes newline-delimited data. To specify an alternative delimiter, set the `split` option.
```bash
-$ echo -n 'Hello, World!\tBeep Boop' | truncate --split '\t' --len 8
+$ echo -n 'Hello, World!\tBeep Boop' | truncate --split '\t' --N 8
Hello...
Beep ...
```
diff --git a/lib/node_modules/@stdlib/string/truncate/benchmark/benchmark.js b/lib/node_modules/@stdlib/string/truncate/benchmark/benchmark.js
index e7c47f509a5d..48cb0e63bd4e 100644
--- a/lib/node_modules/@stdlib/string/truncate/benchmark/benchmark.js
+++ b/lib/node_modules/@stdlib/string/truncate/benchmark/benchmark.js
@@ -22,70 +22,124 @@
var bench = require( '@stdlib/bench' );
var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
-var fromCodePoint = require( '@stdlib/string/from-code-point' );
var pkg = require( './../package.json' ).name;
var truncate = require( './../lib' );
-// FUNCTIONS //
+// MAIN //
-/**
-* Creates a benchmark function.
-*
-* @private
-* @param {PositiveInteger} len - string length
-* @returns {Function} benchmark function
-*/
-function createBenchmark( len ) {
- return benchmark;
-
- /**
- * Benchmark function.
- *
- * @private
- * @param {Benchmark} b - benchmark instance
- */
- function benchmark( b ) {
- var out;
- var i;
-
- b.tic();
- for ( i = 0; i < b.iterations; i++ ) {
- out = truncate( fromCodePoint( i%126 )+'eep boop', len );
- if ( typeof out !== 'string' ) {
- b.fail( 'should return a string' );
- }
- }
- b.toc();
- if ( !isString( out ) ) {
+bench( pkg, function benchmark( b ) {
+ var values;
+ var out;
+ var i;
+
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc'
+ ];
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 5 );
+ if ( typeof out !== 'string' ) {
b.fail( 'should return a string' );
}
- b.pass( 'benchmark finished' );
- b.end();
}
-}
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+bench( pkg+':mode=grapheme', function benchmark( b ) {
+ var values;
+ var opts;
+ var out;
+ var i;
-// MAIN //
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc'
+ ];
+ opts = {
+ 'mode': 'grapheme'
+ };
-/**
-* Main execution sequence.
-*
-* @private
-*/
-function main() {
- var min;
- var max;
- var f;
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 5, opts );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+':mode=code_point', function benchmark( b ) {
+ var values;
+ var opts;
+ var out;
var i;
- min = 1;
- max = 10;
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc'
+ ];
+ opts = {
+ 'mode': 'code_point'
+ };
- for ( i = min; i <= max; i++ ) {
- f = createBenchmark( i );
- bench( pkg+':len='+i, f );
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 5, opts );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
}
-}
+ b.pass( 'benchmark finished' );
+ b.end();
+});
-main();
+bench( pkg+':mode=code_unit', function benchmark( b ) {
+ var values;
+ var opts;
+ var out;
+ var i;
+
+ values = [
+ 'beep boop',
+ 'foo bar',
+ 'xyz abc'
+ ];
+ opts = {
+ 'mode': 'code_unit'
+ };
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = truncate( values[ i%values.length ], 5, opts );
+ if ( typeof out !== 'string' ) {
+ b.fail( 'should return a string' );
+ }
+ }
+ b.toc();
+ if ( !isString( out ) ) {
+ b.fail( 'should return a string' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/string/truncate/bin/cli b/lib/node_modules/@stdlib/string/truncate/bin/cli
index a306c0c52a1a..c3148ce084d4 100644
--- a/lib/node_modules/@stdlib/string/truncate/bin/cli
+++ b/lib/node_modules/@stdlib/string/truncate/bin/cli
@@ -42,9 +42,11 @@ var truncate = require( './../lib' );
* @returns {void}
*/
function main() {
+ var ending;
var split;
var flags;
var args;
+ var opts;
var cli;
var len;
@@ -62,11 +64,21 @@ function main() {
if ( flags.help || flags.version ) {
return;
}
+ if ( flags.ending ) {
+ ending = flags.ending;
+ }
+ else {
+ ending = '...';
+ }
+ opts = {};
+ if ( flags.mode ) {
+ opts.mode = flags.mode;
+ }
// Get any provided command-line arguments:
args = cli.args();
- len = parseInt( flags.len, 10 );
+ len = parseInt( flags.N, 10 );
// Check if we are receiving data from `stdin`...
if ( !stdinStream.isTTY ) {
@@ -80,10 +92,10 @@ function main() {
}
return stdin( onRead );
}
- if ( flags.ending ) {
- console.log( truncate( args[ 0 ], len, flags.ending ) ); // eslint-disable-line no-console
- } else {
- console.log( truncate( args[ 0 ], len ) ); // eslint-disable-line no-console
+ try {
+ console.log( truncate( args[ 0 ], len, ending, opts ) ); // eslint-disable-line no-console
+ } catch ( error ) {
+ return cli.error( error );
}
/**
@@ -106,15 +118,16 @@ function main() {
if ( lines[ lines.length-1 ] === '' ) {
lines.pop();
}
- if ( flags.ending ) {
- for ( i = 0; i < lines.length; i++ ) {
- console.log( truncate( lines[ i ], len, flags.ending ) ); // eslint-disable-line no-console
- }
- } else {
- for ( i = 0; i < lines.length; i++ ) {
- console.log( truncate( lines[ i ], len ) ); // eslint-disable-line no-console
+ if ( lines.length ) {
+ try {
+ console.log( truncate( lines[ 0 ], len, ending, opts ) ); // eslint-disable-line no-console
+ } catch ( error ) {
+ return cli.error( error );
}
}
+ for ( i = 1; i < lines.length; i++ ) {
+ console.log( truncate( lines[ i ], len, ending, opts ) ); // eslint-disable-line no-console
+ }
}
}
diff --git a/lib/node_modules/@stdlib/string/truncate/docs/repl.txt b/lib/node_modules/@stdlib/string/truncate/docs/repl.txt
index 0ba0c4f35b62..48341cb23071 100644
--- a/lib/node_modules/@stdlib/string/truncate/docs/repl.txt
+++ b/lib/node_modules/@stdlib/string/truncate/docs/repl.txt
@@ -1,18 +1,37 @@
-{{alias}}( str, len[, ending] )
- Truncates a string to a specified length.
+{{alias}}( str, N[, ending][, options] )
+ Truncates a string.
Parameters
----------
str: string
Input string.
- len: integer
+ N: integer
Output string length.
ending: string (optional)
Custom ending. Default: '...'.
+ options: Object (optional)
+ Options.
+
+ options.mode: string (optional)
+ Type of characters to return. The following modes 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).
+
+ Default: 'grapheme'.
+
Returns
-------
out: string
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..f1eee700bc79 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
@@ -20,11 +20,53 @@
///
+// tslint:disable:unified-signatures
+
+/**
+* Interface describing function options.
+*/
+interface Options {
+ /**
+ * Specifies the type of characters to return (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.
+* Truncates a string.
*
* @param str - input string
-* @param len - output string length (including ending)
+* @param N - output string length (including ending)
+* @param options - options
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, {
+* 'mode': 'code_unit'
+* });
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( '🐶🐮🐷🐰🐸', 5, {
+* 'mode': 'grapheme'
+* });
+* // returns '🐶🐮...'
+*/
+declare function truncate( str: string, N: number, options?: Options ): string;
+
+/**
+* Truncates a string.
+*
+* @param str - input string
+* @param N - output string length (including ending)
* @param ending - custom ending (default: `...`)
* @returns truncated string
*
@@ -36,8 +78,29 @@
* var out = truncate( 'beep boop', 7, '|' );
* // returns 'beep b|'
*/
-declare function truncate( str: string, len: number, ending?: string ): string;
+declare function truncate( str: string, N: number, ending?: string ): string;
+/**
+* Truncates a string.
+*
+* @param str - input string
+* @param N - output string length (including ending)
+* @param ending - custom ending (default: `...`)
+* @returns truncated string
+*
+* @example
+* var out = truncate( 'beep boop', 7, {
+* 'mode': 'code_unit'
+* });
+* // returns 'beep...'
+*
+* @example
+* var out = truncate( 'beep boop', 7, '|', {
+* 'mode': 'grapheme'
+* });
+* // returns 'beep b|'
+*/
+declare function truncate( str: string, N: number, ending: string, options?: Options ): string;
// EXPORTS //
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..7dda55a3e27e 100644
--- a/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/truncate/docs/types/test.ts
@@ -25,6 +25,8 @@ import truncate = require( './index' );
{
truncate( 'abcdefghi', 3 ); // $ExpectType string
truncate( 'abcdefghi', 10, '|' ); // $ExpectType string
+ truncate( 'abcdefghi', 5, {} ); // $ExpectType string
+ truncate( 'abcdefghi', 5, '~', {} ); // $ExpectType string
}
// The compiler throws an error if the function is not provided a string as its first argument...
@@ -57,8 +59,19 @@ import truncate = require( './index' );
truncate( 'beep boop', 4, ( x: number ): number => x, 0 ); // $ExpectError
}
+// The compiler throws an error if the function is provided an invalid `mode` option...
+{
+ truncate( 'abc', 1, '~', { 'mode': true } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': false } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': null } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': '' } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': [] } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': {} } ); // $ExpectError
+ truncate( 'abc', 1, '~', { 'mode': ( x: number ): number => x } ); // $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/docs/usage.txt b/lib/node_modules/@stdlib/string/truncate/docs/usage.txt
index 2f3734bdadb9..ecde43df28c3 100644
--- a/lib/node_modules/@stdlib/string/truncate/docs/usage.txt
+++ b/lib/node_modules/@stdlib/string/truncate/docs/usage.txt
@@ -5,6 +5,7 @@ Options:
-h, --help Print this message.
-V, --version Print the package version.
- --len length String length.
+ --N length String length.
--ending str Custom ending. Default: '...'.
--split sep Delimiter for stdin data. Default: '/\\r?\\n/'.
+ --mode mode Type of character to return. Default: 'grapheme'.
diff --git a/lib/node_modules/@stdlib/string/truncate/etc/cli_opts.json b/lib/node_modules/@stdlib/string/truncate/etc/cli_opts.json
index 5dd6d7cb5402..f9ab6a0ecfe0 100644
--- a/lib/node_modules/@stdlib/string/truncate/etc/cli_opts.json
+++ b/lib/node_modules/@stdlib/string/truncate/etc/cli_opts.json
@@ -1,8 +1,9 @@
{
"string": [
- "len",
+ "N",
"ending",
- "split"
+ "split",
+ "mode"
],
"boolean": [
"help",
diff --git a/lib/node_modules/@stdlib/string/truncate/lib/index.js b/lib/node_modules/@stdlib/string/truncate/lib/index.js
index 6fed90ec2705..cbdd230f57a8 100644
--- a/lib/node_modules/@stdlib/string/truncate/lib/index.js
+++ b/lib/node_modules/@stdlib/string/truncate/lib/index.js
@@ -19,7 +19,7 @@
'use strict';
/**
-* Truncate a string to a specified length.
+* Truncate a string.
*
* @module @stdlib/string/truncate
*
diff --git a/lib/node_modules/@stdlib/string/truncate/lib/main.js b/lib/node_modules/@stdlib/string/truncate/lib/main.js
index 5aadc30d4da4..a457f69bd4ed 100644
--- a/lib/node_modules/@stdlib/string/truncate/lib/main.js
+++ b/lib/node_modules/@stdlib/string/truncate/lib/main.js
@@ -22,22 +22,41 @@
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 hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var isPlainObject = require( '@stdlib/assert/is-plain-object' );
+var contains = require( '@stdlib/array/base/assert/contains' ).factory;
+var truncateGraphemeCluster = require( '@stdlib/string/base/truncate-grapheme-clusters' );
+var truncateCodePoint = require( '@stdlib/string/base/truncate-code-points' );
+var truncateCodeUnit = require( '@stdlib/string/base/truncate' );
var format = require( '@stdlib/string/format' );
+// VARIABLES //
+
+var MODES = [ 'grapheme', 'code_point', 'code_unit' ];
+var FCNS = {
+ 'grapheme': truncateGraphemeCluster,
+ 'code_point': truncateCodePoint,
+ 'code_unit': truncateCodeUnit
+};
+var isMode = contains( MODES );
+
+
// MAIN //
/**
-* Truncates a string to a specified length.
+* Truncates a string.
*
* @param {string} str - input string
-* @param {integer} len - output string length (including ending)
+* @param {integer} N - output string length (including ending)
* @param {string} [ending='...'] - custom ending
+* @param {Options} [options] - options
+* @param {string} [options.mode="grapheme"] - type of "character" to return (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} options argument must be an object
+* @throws {TypeError} must provide valid options
* @returns {string} truncated string
*
* @example
@@ -70,38 +89,52 @@ var format = require( '@stdlib/string/format' );
* var out = truncate( str, 6 );
* // returns '🐺 W...'
*/
-function truncate( str, len, ending ) {
- var endingLength;
- var fromIndex;
- var nVisual;
- var idx;
+function truncate( str, N ) {
+ 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 ( !isNonNegativeInteger( N ) ) {
+ throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', N ) );
}
- if ( arguments.length > 2 ) {
+ opts = {
+ 'mode': 'grapheme'
+ };
+ nargs = arguments.length;
+
+ if (nargs === 2 ) {
+ ending = '...';
+ } else if ( nargs === 3 ) {
+ ending = arguments[ 2 ];
+ if ( isPlainObject( ending )) {
+ options = ending;
+ ending = '...';
+ } else if ( !isString( ending ) ) {
+ throw new TypeError( format( 'invalid argument. Third argument must be a string. Value: `%s`.', str ) );
+ }
+ } else {
+ ending = arguments[ 2 ];
if ( !isString( ending ) ) {
- throw new TypeError( format( 'invalid argument. Third argument must be a string. Value: `%s`.', ending ) );
+ throw new TypeError( format( 'invalid argument. Third argument must be a string. Value: `%s`.', str ) );
+ }
+ 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, N, ending );
}
diff --git a/lib/node_modules/@stdlib/string/truncate/package.json b/lib/node_modules/@stdlib/string/truncate/package.json
index 29d4c86b6ac6..5c0cf227b9ce 100644
--- a/lib/node_modules/@stdlib/string/truncate/package.json
+++ b/lib/node_modules/@stdlib/string/truncate/package.json
@@ -1,7 +1,7 @@
{
"name": "@stdlib/string/truncate",
"version": "0.0.0",
- "description": "Truncate a string to a specified length.",
+ "description": "Truncate a string.",
"license": "Apache-2.0",
"author": {
"name": "The Stdlib Authors",
diff --git a/lib/node_modules/@stdlib/string/truncate/test/test.cli.js b/lib/node_modules/@stdlib/string/truncate/test/test.cli.js
index 75d1c10b824c..12ccff7031ab 100644
--- a/lib/node_modules/@stdlib/string/truncate/test/test.cli.js
+++ b/lib/node_modules/@stdlib/string/truncate/test/test.cli.js
@@ -149,7 +149,7 @@ tape( 'the command-line interface truncates a string', opts, function test( t )
cmd = [
EXEC_PATH,
'-e',
- '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep boop\'; process.argv[ 3 ] = \'--len=5\'; require( \''+fpath+'\' );"'
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep boop\'; process.argv[ 3 ] = \'--N=5\'; require( \''+fpath+'\' );"'
];
opts = {};
@@ -173,7 +173,7 @@ tape( 'the command-line interface truncates a string (custom ending)', opts, fun
cmd = [
EXEC_PATH,
'-e',
- '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep boop\'; process.argv[ 3 ] = \'--len=5\'; process.argv[ 4 ] = \'--ending=!\'; require( \''+fpath+'\' );"'
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep boop\'; process.argv[ 3 ] = \'--N=5\'; process.argv[ 4 ] = \'--ending=!\'; require( \''+fpath+'\' );"'
];
opts = {};
@@ -190,13 +190,53 @@ tape( 'the command-line interface truncates a string (custom ending)', opts, fun
}
});
+tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ '-e',
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep boop\'; process.argv[ 3 ] = \'--N=4\'; process.argv[ 4 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), 'b...\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
+tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) {
+ var cmd = [
+ EXEC_PATH,
+ '-e',
+ '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--N=4\'; process.argv[ 4 ] = \'--mode=foo\'; require( \''+fpath+'\' );"'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.pass( error.message );
+ t.strictEqual( error.code, 1, 'expected exit code' );
+ }
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString().length > 0, true, 'expected value' );
+ t.end();
+ }
+});
+
tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) {
var cmd = [
'printf "beep boop\nHello World!"',
'|',
EXEC_PATH,
fpath,
- '--len=5'
+ '--N=5'
];
exec( cmd.join( ' ' ), done );
@@ -218,7 +258,7 @@ tape( 'the command-line interface supports use as a standard stream (custom endi
'|',
EXEC_PATH,
fpath,
- '--len=5',
+ '--N=5',
'--ending="|"'
];
@@ -242,7 +282,7 @@ tape( 'the command-line interface supports specifying a custom delimiter when us
EXEC_PATH,
fpath,
'--split \'\t\'',
- '--len=5'
+ '--N=5'
];
exec( cmd.join( ' ' ), done );
@@ -258,6 +298,29 @@ tape( 'the command-line interface supports specifying a custom delimiter when us
}
});
+tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) {
+ var cmd = [
+ 'printf \'beep boop\tHello World!\'',
+ '|',
+ EXEC_PATH,
+ fpath,
+ '--N=5',
+ '--mode code_point'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.fail( error.message );
+ } else {
+ t.strictEqual( stdout.toString(), 'be...\n', 'expected value' );
+ t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' );
+ }
+ t.end();
+ }
+});
+
tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) {
var cmd = [
'printf \'beep boop\tHello World!\'',
@@ -265,7 +328,7 @@ tape( 'the command-line interface supports specifying a custom delimiter when us
EXEC_PATH,
fpath,
'--split=/\\\\t/',
- '--len=5'
+ '--N=5'
];
exec( cmd.join( ' ' ), done );
@@ -281,6 +344,29 @@ tape( 'the command-line interface supports specifying a custom delimiter when us
}
});
+tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) {
+ var cmd = [
+ 'printf \'beep boop\tHello World!\'',
+ '|',
+ EXEC_PATH,
+ fpath,
+ '--N=5',
+ '--mode=foo'
+ ];
+
+ exec( cmd.join( ' ' ), done );
+
+ function done( error, stdout, stderr ) {
+ if ( error ) {
+ t.pass( error.message );
+ t.strictEqual( error.code, 1, 'expected exit code' );
+ }
+ t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' );
+ t.strictEqual( stderr.toString().length > 0, true, 'expected value' );
+ t.end();
+ }
+});
+
tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) {
var script;
var opts;
diff --git a/lib/node_modules/@stdlib/string/truncate/test/test.js b/lib/node_modules/@stdlib/string/truncate/test/test.js
index 897a7e844f29..b533557c1b1c 100644
--- a/lib/node_modules/@stdlib/string/truncate/test/test.js
+++ b/lib/node_modules/@stdlib/string/truncate/test/test.js
@@ -59,6 +59,33 @@ tape( 'the function throws an error if not provided a string primitive', functio
}
});
+tape( 'the function throws an error if not provided a string primitive (options)', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 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( value, {} );
+ };
+ }
+});
+
tape( 'the function throws an error if not provided a nonnegative integer as its second argument', function test( t ) {
var values;
var i;
@@ -88,6 +115,35 @@ tape( 'the function throws an error if not provided a nonnegative integer as its
}
});
+tape( 'the function throws an error if not provided a nonnegative integer as its third argument (options)', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ '5',
+ -5,
+ 3.14,
+ 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', value, {} );
+ };
+ }
+});
+
tape( 'the function throws an error if provided a non-string as a third argument', function test( t ) {
var values;
var i;
@@ -99,7 +155,6 @@ tape( 'the function throws an error if provided a non-string as a third argument
void 0,
true,
[],
- {},
function noop() {}
];
@@ -115,7 +170,117 @@ 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 a non-string as a third argument (options)', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 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 an options argument which is not an object', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 3,
+ null,
+ true,
+ void 0,
+ NaN,
+ [],
+ 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', 1, '!!', value );
+ };
+ }
+});
+
+tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 3,
+ null,
+ true,
+ void 0,
+ NaN,
+ [],
+ 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', 1, {
+ 'mode': value
+ });
+ };
+ }
+});
+
+tape( 'the function throws an error if provided a `mode` option which is not a supported mode (fourth argument)', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ 'abc',
+ 3,
+ null,
+ true,
+ void 0,
+ NaN,
+ [],
+ 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', 1, '!', {
+ 'mode': value
+ });
+ };
+ }
+});
+
+tape( 'the function truncates a string to the specified length (default)', function test( t ) {
var expected;
var actual;
var str;
@@ -154,7 +319,7 @@ tape( 'the function truncates a string to the specified length', function test(
t.end();
});
-tape( 'the function truncates a string to the specified length (custom ending)', function test( t ) {
+tape( 'the function truncates a string to the specified length (custom ending, deafult)', function test( t ) {
var expected;
var actual;
var str;
@@ -198,3 +363,237 @@ tape( 'the function truncates a string to the specified length (custom ending)',
t.end();
});
+
+tape( 'the function truncates a string to the specified length (mode=grapheme)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'grapheme'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 6;
+ expected = '🐺 W...';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ending, mode=grapheme)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'grapheme'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep😃';
+ actual = truncate( str, len, '😃', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop foo bar';
+ len = 10;
+ expected = 'beep 🙃 🙃 🙃';
+ actual = truncate( str, len, ' 🙃 🙃 🙃', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = '🐺 Wolf Brothers 🐺';
+ len = 8;
+ expected = '🐺 Wolf 🐺';
+ actual = truncate( str, len, '🐺', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (mode=code_point)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'code_point'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ending, mode=code_point)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'code_point'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (mode=code_unit)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'code_unit'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'be...';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 0;
+ expected = '';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 1;
+ expected = '.';
+ actual = truncate( str, len, opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function truncates a string to the specified length (custom ending, mode=code_unit)', function test( t ) {
+ var expected;
+ var actual;
+ var opts;
+ var str;
+ var len;
+
+ opts = {
+ 'mode': 'code_unit'
+ };
+
+ str = 'beep boop';
+ len = 5;
+ expected = 'beep|';
+ actual = truncate( str, len, '|', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 10;
+ expected = 'beep boop';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ str = 'beep boop';
+ len = 3;
+ expected = 'be!';
+ actual = truncate( str, len, '!', opts );
+ t.strictEqual( actual, expected, 'returns expected value' );
+
+ t.end();
+});