Auto-generated commit

README.md

@@ -51,9 +51,9 @@ The [branches.md][branches-url] file summarizes the available branches and displ
 var removeFirst = require( '@stdlib/string-remove-first' );
 ```
 
-#### removeFirst( str\[, n] )
+#### removeFirst( str\[, n]\[, options] )
 
-Removes the first character of a `string`.
+Removes the first character(s) of a `string`.
 
 ```javascript
 var out = removeFirst( 'last man standing' );
@@ -63,7 +63,17 @@ out = removeFirst( 'Hidden Treasures' );
 // returns 'idden Treasures'
 ```
 
-If provided a second argument, the function removes the first `n` characters.
+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).
+    -   `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics).
+    -   `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets).
+
+    Default: `'grapheme'`.
+
+By default, the function returns the first character. To return the first `n` characters, provide a second argument specifying the number of characters to return.
 
 ```javascript
 var out = removeFirst( 'foo bar', 4 );
@@ -77,6 +87,18 @@ out = removeFirst( 'foo bar', 10 );
 
 <!-- /.usage -->
 
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## 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.
+
+</section>
+
+<!-- /.notes -->
+
 <section class="examples">
 
 ## Examples
@@ -145,6 +167,7 @@ Options:
   -V,    --version             Print the package version.
          --n                   Number of characters to remove. Default: 1.
          --split sep           Delimiter for stdin data. Default: '/\\r?\\n/'.
+         --mode mode           Type of character to return. Default: 'grapheme'.
 ```
 
 </section>

benchmark/benchmark.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2018 The Stdlib Authors.
+* 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.
@@ -22,24 +22,118 @@
 
 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 removeFirst = require( './../lib' );
 
 
 // MAIN //
 
 bench( pkg, function benchmark( b ) {
-	var str;
+	var values;
 	var out;
 	var i;
 
+	values = [
+		'beep boop',
+		'foo bar',
+		'xyz abc'
+	];
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		out = removeFirst( values[ i%values.length ] );
+		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=grapheme', function benchmark( b ) {
+	var values;
+	var opts;
+	var out;
+	var i;
+
+	values = [
+		'beep boop',
+		'foo bar',
+		'xyz abc'
+	];
+	opts = {
+		'mode': 'grapheme'
+	};
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		out = removeFirst( values[ i%values.length ], 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;
+
+	values = [
+		'beep boop',
+		'foo bar',
+		'xyz abc'
+	];
+	opts = {
+		'mode': 'code_point'
+	};
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		out = removeFirst( values[ i%values.length ], 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_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++ ) {
-		str = fromCodePoint( i%126 ) + 'eep boop';
-		out = removeFirst( str );
-		if ( out !== 'eep boop' ) {
-			b.fail( 'should return a shorter string' );
+		out = removeFirst( values[ i%values.length ], opts );
+		if ( typeof out !== 'string' ) {
+			b.fail( 'should return a string' );
 		}
 	}
 	b.toc();

bin/cli

@@ -45,6 +45,7 @@ function main() {
 	var split;
 	var flags;
 	var args;
+	var opts;
 	var cli;
 	var n;
 
@@ -64,6 +65,12 @@ function main() {
 	}
 	if ( flags.n ) {
 		n = parseInt( flags.n, 10 );
+	} else {
+		n = 1;
+	}
+	opts = {};
+	if ( flags.mode ) {
+		opts.mode = flags.mode;
 	}
 
 	// Get any provided command-line arguments:
@@ -81,10 +88,10 @@ function main() {
 		}
 		return stdin( onRead );
 	}
-	if ( n ) {
-		console.log( removeFirst( args[ 0 ], n ) ); // eslint-disable-line no-console
-	} else {
-		console.log( removeFirst( args[ 0 ] ) ); // eslint-disable-line no-console
+	try {
+		console.log( removeFirst( args[ 0 ], n, opts ) ); // eslint-disable-line no-console
+	} catch ( error ) {
+		return cli.error( error );
 	}
 
 	/**
@@ -107,13 +114,14 @@ function main() {
 		if ( lines[ lines.length-1 ] === '' ) {
 			lines.pop();
 		}
-		if ( n ) {
-			for ( i = 0; i < lines.length; i++ ) {
-				console.log( removeFirst( lines[ i ], n ) ); // eslint-disable-line no-console
+		if ( lines.length ) {
+			try {
+				console.log( removeFirst( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console
+			} catch ( error ) {
+				return cli.error( error );
 			}
-		} else {
-			for ( i = 0; i < lines.length; i++ ) {
-				console.log( removeFirst( lines[ i ] ) ); // eslint-disable-line no-console
+			for ( i = 1; i < lines.length; i++ ) {
+				console.log( removeFirst( lines[ i ], n, opts ) ); // eslint-disable-line no-console
 			}
 		}
 	}

docs/repl.txt

@@ -1,5 +1,5 @@
 
-{{alias}}( str[, n] )
+{{alias}}( str[, n][, options] )
     Removes the first character(s) of a `string`.
 
     Parameters
@@ -10,6 +10,25 @@
     n: integer (optional)
         Number of characters to remove. Default: 1.
 
+    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

docs/types/index.d.ts

@@ -18,6 +18,69 @@
 
 // TypeScript Version: 2.0
 
+// 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';
+}
+
+/**
+* Removes the first character(s) of a string.
+*
+* @param str - input string
+* @param n - number of characters to remove (default: 1)
+* @param options - options
+* @returns updated string
+*
+* @example
+* var out = removeFirst( 'last man standing', 1, {
+*     'mode': 'code_unit'
+* });
+* // returns 'ast man standing'
+*
+* @example
+* var out = removeFirst( '🐶🐮🐷🐰🐸', 2, {
+*     'mode': 'grapheme'
+* });
+* // returns '🐷🐰🐸'
+*/
+declare function removeFirst( str: string, n: number, options?: Options ): string;
+
+/**
+* Removes the first character of a string.
+*
+* @param str - input string
+* @param options - options
+* @returns updated string
+*
+* @example
+* var out = removeFirst( 'last man standing', {
+*     'mode': 'code_unit'
+* });
+* // returns 'ast man standing'
+*
+* @example
+* var out = removeFirst( '🐶🐮🐷🐰🐸', 2, {
+*     'mode': 'grapheme'
+* });
+* // returns '🐷🐰🐸'
+*/
+declare function removeFirst( str: string, options?: Options ): string;
+
 /**
 * Removes the first character(s) of a string.
 *