8000 Auto-generated commit · stdlib-js/string-remove-first@9812c1d · GitHub
[go: up one dir, main page]
Skip to content

Commit 9812c1d

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 36360eb commit 9812c1d

File tree

13 files changed

+676
-43
lines changed

13 files changed

+676
-43
lines changed

‎.github/.keepalive

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.md

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,9 @@ The [branches.md][branches-url] file summarizes the available branches and displ
5151
var removeFirst = require( '@stdlib/string-remove-first' );
5252
```
5353

54-
#### removeFirst( str\[, n] )
54+
#### removeFirst( str\[, n]\[, options] )
5555

56-
Removes the first character of a `string`.
56+
Removes the first character(s) of a `string`.
5757

5858
```javascript
5959
var out = removeFirst( 'last man standing' );
@@ -63,7 +63,17 @@ out = removeFirst( 'Hidden Treasures' );
6363
// returns 'idden Treasures'
6464
```
6565

66-
If provided a second argument, the function removes the first `n` characters.
66+
The function supports the following options:
67+
68+
- **mode**: type of characters to return. Must be one of the following:
69+
70+
- `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji).
71+
- `'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).
72+
- `'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).
73+
74+
Default: `'grapheme'`.
75+
76+
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.
6777

6878
```javascript
6979
var out = removeFirst( 'foo bar', 4 );
@@ -77,6 +87,18 @@ out = removeFirst( 'foo bar', 10 );
7787

7888
<!-- /.usage -->
7989

90+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
91+
92+
<section class="notes">
93+
94+
## Notes
95+
341A
96+
- 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.
97+
98+
</section>
99+
100+
<!-- /.notes -->
101+
80102
<section class="examples">
81103

82104
## Examples
@@ -145,6 +167,7 @@ Options:
145167
-V, --version Print the package version.
146168
--n Number of characters to remove. Default: 1.
147169
--split sep Delimiter for stdin data. Default: '/\\r?\\n/'.
170+
--mode mode Type of character to return. Default: 'grapheme'.
148171
```
149172

150173
</section>

‎benchmark/benchmark.js

Lines changed: 101 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2018 The Stdlib Authors.
4+
* Copyright (c) 2023 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -22,24 +22,118 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var isString = require( '@stdlib/assert-is-string' ).isPrimitive;
25-
var fromCodePoint = require( '@stdlib/string-from-code-point' );
2625
var pkg = require( './../package.json' ).name;
2726
var removeFirst = require( './../lib' );
2827

2928

3029
// MAIN //
3130

3231
bench( pkg, function benchmark( b ) {
33-
var str;
32+
var values;
3433
var out;
3534
var i;
3635

36+
values = [
37+
'beep boop',
38+
'foo bar',
39+
'xyz abc'
40+
];
41+
42+
b.tic();
43+
for ( i = 0; i < b.iterations; i++ ) {
44+
out = removeFirst( values[ i%values.length ] );
45+
if ( typeof out !== 'string' ) {
46+
b.fail( 'should return a string' );
47+
}
48+
}
49+
b.toc();
50+
if ( !isString( out ) ) {
51+
b.fail( 'should return a string' );
52+
}
53+
b.pass( 'benchmark finished' );
54+
b.end();
55+
});
56+
57+
bench( pkg+':mode=grapheme', function benchmark( b ) {
58+
var values;
59+
var opts;
60+
var out;
61+
var i;
62+
63+
values = [
64+
'beep boop',
65+
'foo bar',
66+
'xyz abc'
67+
];
68+
opts = {
69+
'mode': 'grapheme'
70+
};
71+
72+
b.tic();
73+
for ( i = 0; i < b.iterations; i++ ) {
74+
out = removeFirst( values[ i%values.length ], opts );
75+
if ( typeof out !== 'string' ) {
76+
b.fail( 'should return a string' );
77+
}
78+
}
79+
b.toc();
80+
if ( !isString( out ) ) {
81+
b.fail( 'should return a string' );
82+
}
83+
b.pass( 'benchmark finished' );
84+
b.end();
85+
});
86+
87+
bench( pkg+':mode=code_point', function benchmark( b ) {
88+
var values;
89+
var opts;
90+
var out;
91+
var i;
92+
93+
values = [
94+
'beep boop',
95+
'foo bar',
96+
'xyz abc'
97+
];
98+
opts = {
99+
'mode': 'code_point'
100+
};
101+
102+
b.tic();
103+
for ( i = 0; i < b.iterations; i++ ) {
104+
out = removeFirst( values[ i%values.length ], opts );
105+
if ( typeof out !== 'string' ) {
106+
b.fail( 'should return a string' );
107+
}
108+
}
109+
b.toc();
110+
if ( !isString( out ) ) {
111+
b.fail( 'should return a string' );
112+
}
113+
b.pass( 'benchmark finished' );
114+
b.end();
115+
});
116+
117+
bench( pkg+':mode=code_unit', function benchmark( b ) {
118+
var values;
119+
var opts;
120+
var out;
121+
var i;
122+
123+
values = [
124+
'beep boop',
125+
'foo bar',
126+
'xyz abc'
127+
];
128+
opts = {
129+
'mode': 'code_unit'
130+
};
131+
37132
b.tic();
38133
for ( i = 0; i < b.iterations; i++ ) {
39-
str = fromCodePoint( i%126 ) + 'eep boop';
40-
out = removeFirst( str );
41-
if ( out !== 'eep boop' ) {
42-
b.fail( 'should return a shorter string' );
134+
out = removeFirst( values[ i%values.length ], opts );
135+
if ( typeof out !== 'string' ) {
136+
b.fail( 'should return a string' );
43137
}
44138
}
45139
b.toc();

‎bin/cli

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ function main() {
4545
var split;
4646
var flags;
4747
var args;
48+
var opts;
4849
var cli;
4950
var n;
5051

@@ -64,6 +65,12 @@ function main() {
6465
}
6566
if ( flags.n ) {
6667
n = parseInt( flags.n, 10 );
68+
} else {
69+
n = 1;
70+
}
71+
opts = {};
72+
if ( flags.mode ) {
73+
opts.mode = flags.mode;
6774
}
6875

6976
// Get any provided command-line arguments:
@@ -81,10 +88,10 @@ function main() {
8188
}
8289
return stdin( onRead );
8390
}
84-
if ( n ) {
85-
console.log( removeFirst( args[ 0 ], n ) ); // eslint-disable-line no-console
86-
} else {
87-
console.log( removeFirst( args[ 0 ] ) ); // eslint-disable-line no-console
91+
try {
92+
console.log( removeFirst( args[ 0 ], n, opts ) ); // eslint-disable-line no-console
93+
} catch ( error ) {
94+
return cli.error( error );
8895
}
8996

9097
/**
@@ -107,13 +114,14 @@ function main() {
107114
if ( lines[ lines.length-1 ] === '' ) {
108115
lines.pop();
109116
}
110-
if ( n ) {
111-
for ( i = 0; i < lines.length; i++ ) {
112-
console.log( removeFirst( lines[ i ], n ) ); // eslint-disable-line no-console
117+
if ( lines.length ) {
118+
try {
119+
console.log( removeFirst( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console
120+
} catch ( error ) {
121+
return cli.error( error );
113122
}
114-
} else {
115-
for ( i = 0; i < lines.length; i++ ) {
116-
console.log( removeFirst( lines[ i ] ) ); // eslint-disable-line no-console
123+
for ( i = 1; i < lines.length; i++ ) {
124+
console.log( removeFirst( lines[ i ], n, opts ) ); // eslint-disable-line no-console
117125
}
118126
}
119127
}

‎docs/repl.txt

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
{{alias}}( str[, n] )
2+
{{alias}}( str[, n][, options] )
33
Removes the first character(s) of a `string`.
44

55
Parameters
@@ -10,6 +10,25 @@
1010
n: integer (optional)
1111
Number of characters to remove. Default: 1.
1212

13+
options: Object (optional)
14+
Options.
15+
16+
options.mode: string (optional)
17+
Type of characters to return. The following modes are supported:
18+
19+
- grapheme: grapheme clusters. Appropriate for strings containing visual
20+
characters which can span multiple Unicode code points (e.g., emoji).
21+
- code_point: Unicode code points. Appropriate for strings containing
22+
visual characters which are comprised of more than one Unicode code
23+
unit (e.g., ideographic symbols and punctuation and mathematical
24+
alphanumerics).
25+
- code_unit': UTF-16 code units. Appropriate for strings containing
26+
visual characters drawn from the basic multilingual plane (BMP) (e.g.,
27+
common characters, such as those from the Latin, Greek, and Cyrillic
28+
alphabets).
29+
30+
Default: 'grapheme'.
31+
1332
Returns
1433
-------
1534
out: string

‎docs/types/index.d.ts

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,69 @@
1818

1919
// TypeScript Version: 2.0
2020

21+
// tslint:disable:unified-signatures
22+
23+
/**
24+
* Interface describing function options.
25+
*/
26+
interface Options {
27+
/**
28+
* Specifies the type of characters to return (default: 'grapheme').
29+
*
30+
* ## Notes
31+
*
32+
* - The following option values are supported:
33+
*
34+
* - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji).
35+
* - `'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).
36+
* - `'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).
37+
*/
38+
mode?: 'grapheme' | 'code_point' | 'code_unit';
39+
}
40+
41+
/**
42+
* Removes the first character(s) of a string.
43+
*
44+
* @param str - input string
45+
* @param n - number of characters to remove (default: 1)
46+
* @param options - options
47+
* @returns updated string
48+
*
49+
* @example
50+
* var out = removeFirst( 'last man standing', 1, {
51+
* 'mode': 'code_unit'
52+
* });
53+
* // returns 'ast man standing'
54+
*
55+
* @example
56+
* var out = removeFirst( '🐶🐮🐷🐰🐸', 2, {
57+
* 'mode': 'grapheme'
58+
* });
59+
* // returns '🐷🐰🐸'
60+
*/
61+
declare function removeFirst( str: string, n: number, options?: Options ): string;
62+
63+
/**
64+
* Removes the first character of a string.
65+
*
66+
* @param str - input string
67+
* @param options - options
68+
* @returns updated string
69+
*
70+
* @example
71+
* var out = removeFirst( 'last man standing', {
72+
* 'mode': 'code_unit'
73+
* });
74+
* // returns 'ast man standing'
75+
*
76+
* @example
77+
* var out = removeFirst( '🐶🐮🐷🐰🐸', 2, {
78+
* 'mode': 'grapheme'
79+
* });
80+
* // returns '🐷🐰🐸'
81+
*/
82+
declare function removeFirst( str: string, options?: Options ): string;
83+
2184
/**
2285
* Removes the first character(s) of a string.
2386
*

0 commit comments

Comments
 (0)
0