README.md (4863B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2021 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # rtrimN 22 23 > Trim `n` characters from the end of a string. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var rtrimN = require( '@stdlib/string/right-trim-n' ); 41 ``` 42 43 #### rtrimN( str, n\[, chars] ) 44 45 Trims `n` characters from the end of a string. 46 47 ```javascript 48 var str = ' foo '; 49 var out = rtrimN( str, str.length ); 50 // returns ' foo' 51 52 out = rtrimN( str, 1 ); 53 // returns ' foo ' 54 ``` 55 56 By default, the function trims whitespace characters. To trim a different set of characters instead, provide a string or an array of characters to trim: 57 58 ```javascript 59 var str = '🐶🐶🐶 Animals 🐶🐶🐶'; 60 var out = rtrimN( str, str.length, [ '🐶', ' ' ] ); 61 // returns '🐶🐶🐶 Animals' 62 63 out = rtrimN( str, str.length, '🐶 ' ); 64 // returns '🐶🐶🐶 Animals' 65 ``` 66 67 </section> 68 69 <!-- /.usage --> 70 71 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 72 73 <section class="notes"> 74 75 </section> 76 77 <!-- /.notes --> 78 79 <!-- Package usage examples. --> 80 81 <section class="examples"> 82 83 ## Examples 84 85 <!-- eslint no-undef: "error" --> 86 87 ```javascript 88 var rtrimN = require( '@stdlib/string/right-trim-n' ); 89 90 var out = rtrimN( ' Whitespace ', 3 ); 91 // returns ' Whitespace' 92 93 out = rtrimN( '\t\t\tTabs\t\t\t', 2 ); 94 // returns '\t\t\tTabs\t' 95 96 out = rtrimN( '~~~CUSTOM~~~', 3, '~' ); 97 // returns '~~~CUSTOM' 98 ``` 99 100 </section> 101 102 <!-- /.examples --> 103 104 105 <!-- Section for describing a command-line interface. --> 106 107 * * * 108 109 <section class="cli"> 110 111 ## CLI 112 113 <!-- CLI usage documentation. --> 114 115 <section class="usage"> 116 117 ### Usage 118 119 ```text 120 Usage: rtrimn [options] --n=<number> 121 122 Options: 123 124 -h, --help Print this message. 125 -V, --version Print the package version. 126 --n number Number of characters to trim. 127 --chars str Characters to trim. Default: whitespace. 128 --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. 129 ``` 130 131 </section> 132 133 <!-- /.usage --> 134 135 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 136 137 <section class="notes"> 138 139 ### Notes 140 141 - If the split separator is a [regular expression][mdn-regexp], ensure that the `split` option is either properly escaped or enclosed in quotes. 142 143 ```bash 144 # Not escaped... 145 $ echo -n $' foo \n bar ' | rtrimn --n=3 --split /\r?\n/ 146 147 # Escaped... 148 $ echo -n $' foo \n bar ' | rtrimn --n=3 --split /\\r?\\n/ 149 ``` 150 151 - The implementation ignores trailing delimiters. 152 153 </section> 154 155 <!-- /.notes --> 156 157 <!-- CLI usage examples. --> 158 159 <section class="examples"> 160 161 ### Examples 162 163 ```bash 164 $ rtrimn ' Whitespace ' --n=3 165 Whitespace 166 ``` 167 168 To use as a [standard stream][standard-streams], 169 170 ```bash 171 $ echo -n '~beep~boop~~~' | rtrimn --n=2 --chars '~' 172 ~beep~boop~ 173 ``` 174 175 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. 176 177 ```bash 178 $ echo -n '~~~foo~~~\t~~~bar~~~\t~~~baz~~~' | rtrimn --split '\t' --chars '~' --n=3 179 ~~~foo 180 ~~~bar 181 ~~~baz 182 ``` 183 184 </section> 185 186 <!-- /.examples --> 187 188 </section> 189 190 <!-- /.cli --> 191 192 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 193 194 <section class="references"> 195 196 </section> 197 198 <!-- /.references --> 199 200 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 201 202 <section class="related"> 203 204 </section> 205 206 <!-- /.related --> 207 208 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 209 210 <section class="links"> 211 212 [mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions 213 214 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 215 216 </section> 217 218 <!-- /.links -->