README.md (5364B)
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 # truncate 22 23 > Truncate a string to a specified length. 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 truncate = require( '@stdlib/string/truncate' ); 41 ``` 42 43 #### truncate( str, len\[, ending] ) 44 45 Truncates a string to a specified length. 46 47 ```javascript 48 var out = truncate( 'beep boop', 7 ); 49 // returns 'beep...' 50 ``` 51 52 By default, the truncated string is appended with `'...'`. To customize the truncated string, provide an `ending` argument: 53 54 ```javascript 55 var out = truncate( 'beep boop', 7, '!' ); 56 // returns 'beep b!' 57 58 out = truncate( 'beep boop', 7, '!!!' ); 59 // returns 'beep!!!' 60 ``` 61 62 </section> 63 64 <!-- /.usage --> 65 66 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 67 68 <section class="notes"> 69 70 </section> 71 72 <!-- /.notes --> 73 74 <!-- Package usage examples. --> 75 76 <section class="examples"> 77 78 ## Examples 79 80 <!-- eslint no-undef: "error" --> 81 82 ```javascript 83 var truncate = require( '@stdlib/string/truncate' ); 84 85 var str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'; 86 var out = truncate( str, 14 ); 87 // returns 'Lorem ipsum...' 88 89 str = 'To be or not to be, that is the question'; 90 out = truncate( str, 19, '!' ); 91 // returns 'To be or not to be!' 92 93 str = 'The quick fox jumps over the lazy dog.'; 94 out = truncate( str, 16, '...' ); 95 // returns 'The quick fox...' 96 97 str = '🐺 Wolf Brothers 🐺'; 98 out = truncate( str, 6 ); 99 // returns '🐺 W...' 100 ``` 101 102 </section> 103 104 <!-- /.examples --> 105 106 <!-- Section for describing a command-line interface. --> 107 108 * * * 109 110 <section class="cli"> 111 112 ## CLI 113 114 <!-- CLI usage documentation. --> 115 116 <section class="usage"> 117 118 ### Usage 119 120 ```text 121 Usage: truncate [options] [<string>] --len <length> 122 123 Options: 124 125 -h, --help Print this message. 126 -V, --version Print the package version. 127 --len length String length. 128 --ending str Custom ending. Default: '...'. 129 --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. 130 ``` 131 132 </section> 133 134 <!-- /.usage --> 135 136 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 137 138 <section class="notes"> 139 140 ### Notes 141 142 - If the split separator is a [regular expression][mdn-regexp], ensure that the `split` option is either properly escaped or enclosed in quotes. 143 144 ```bash 145 # Not escaped... 146 $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --len 6 --split /\r?\n/ 147 148 # Escaped... 149 $ echo -n $'Hello, World!\nBeep Boop Baz' | truncate --len 6 --split /\\r?\\n/ 150 ``` 151 152 - The implementation ignores trailing delimiters. 153 154 </section> 155 156 </section> 157 158 <!-- /.notes --> 159 160 <!-- CLI usage examples. --> 161 162 <section class="examples"> 163 164 ### Examples 165 166 ```bash 167 $ truncate 'Hello, World!' --len 8 168 Hello... 169 170 $ truncate 'Hello, World!' --len 6 --ending '!' 171 Hello! 172 ``` 173 174 To use as a [standard stream][standard-streams], 175 176 ```bash 177 $ echo -n 'Hello, World!' | truncate --len 8 178 Hello... 179 ``` 180 181 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. 182 183 ```bash 184 $ echo -n 'Hello, World!\tBeep Boop' | truncate --split '\t' --len 8 185 Hello... 186 Beep ... 187 ``` 188 189 </section> 190 191 <!-- /.examples --> 192 193 </section> 194 195 <!-- /.cli --> 196 197 <!-- 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. --> 198 199 <section class="references"> 200 201 </section> 202 203 <!-- /.references --> 204 205 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 206 207 <section class="related"> 208 209 * * * 210 211 ## See Also 212 213 - <span class="package-name">[`@stdlib/string/truncate-middle`][@stdlib/string/truncate-middle]</span><span class="delimiter">: </span><span class="description">truncate a string in the middle to a specified length.</span> 214 215 </section> 216 217 <!-- /.related --> 218 219 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 220 221 <section class="links"> 222 223 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 224 225 [mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions 226 227 <!-- <related-links> --> 228 229 [@stdlib/string/truncate-middle]: https://github.com/stdlib-js/string/tree/main/truncate-middle 230 231 <!-- </related-links> --> 232 233 </section> 234 235 <!-- /.links -->