README.md (6941B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # pad 22 23 > Pad a string. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var pad = require( '@stdlib/string/pad' ); 37 ``` 38 39 #### pad( str, len\[, options] ) 40 41 Pads a `string` such that the padded `string` has a `length` of `len`. 42 43 ```javascript 44 var str = pad( 'a', 5 ); 45 // returns 'a ' 46 ``` 47 48 The function accepts the following `options`: 49 50 - **lpad**: `string` used to left pad. Default: `''`. 51 - **rpad**: `string` used to right pad. Default: `' '`. 52 - **centerRight**: `boolean` indicating whether to center right in the event of a tie. Default: `false` (i.e., center left). 53 54 By default, an input `string` is padded with spaces. To pad with a different character or sequence of characters, provide a pad `string`. 55 56 ```javascript 57 var str = pad( 'a', 10, { 58 'lpad': 'b' 59 }); 60 // returns 'bbbbbbbbba' 61 62 str = pad( 'a', 12, { 63 'rpad': 'b' 64 }); 65 // returns 'abbbbbbbbbbb' 66 ``` 67 68 To center an input `string`, provide both `lpad` and `rpad` options. 69 70 ```javascript 71 var opts = { 72 'lpad': 'a', 73 'rpad': 'c' 74 }; 75 76 var str = pad( 'b', 11, opts ); 77 // returns 'aaaaabccccc' 78 ``` 79 80 When both `lpad` and `rpad` are specified and `len-str.length` is **odd**, left and right padding cannot equally split the available padding space. By default, right padding receives the extra character (i.e., the input `string` is left-centered). 81 82 ```javascript 83 var opts = { 84 'lpad': 'a', 85 'rpad': 'c' 86 }; 87 88 var str = pad( 'b', 10, opts ); 89 // returns 'aaaabccccc' 90 ``` 91 92 To center right, set the `centerRight` option. 93 94 ```javascript 95 var opts = { 96 'lpad': 'a', 97 'rpad': 'c', 98 'centerRight': true 99 }; 100 101 var str = pad( 'b', 10, opts ); 102 // returns 'aaaaabcccc' 103 ``` 104 105 </section> 106 107 <!-- /.usage --> 108 109 <section class="notes"> 110 111 ## Notes 112 113 - In contrast to [lpad][@stdlib/string/left-pad] and [rpad][@stdlib/string/right-pad], any padding which does not evenly divide available space is trimmed such that the returned `string` length is **always** `len`. 114 115 ```javascript 116 var opts = { 117 'lpad': 'boop', 118 'rpad': 'woot' 119 }; 120 var str = pad( 'beep', 10, opts ); 121 // returns 'boobeepwoo' 122 ``` 123 124 - Similarly, if `len < str.length`, the input `string` is trimmed. 125 126 ```javascript 127 // Pad right, trim right: 128 var str = pad( 'beep', 2 ); 129 // returns 'be' 130 131 // Pad left, trim left: 132 str = pad( 'beep', 2, { 133 'lpad': 'b' 134 }); 135 // returns 'ep' 136 137 // Pad both, trim both: 138 str = pad( 'beep', 2, { 139 'lpad': '@', 140 'rpad': '!' 141 }); 142 // returns 'ee' 143 144 // Pad both, trim both starting from left: 145 str = pad( 'abcdef', 3, { 146 'lpad': '@', 147 'rpad': '!' 148 }); 149 // returns 'cde' 150 151 // Pad both, trim both starting from right: 152 str = pad( 'abcdef', 3, { 153 'lpad': '@', 154 'rpad': '!', 155 'centerRight': true 156 }); 157 // returns 'bcd' 158 ``` 159 160 </section> 161 162 <!-- /.notes --> 163 164 <section class="examples"> 165 166 ## Examples 167 168 <!-- eslint no-undef: "error" --> 169 170 ```javascript 171 var round = require( '@stdlib/math/base/special/round' ); 172 var randu = require( '@stdlib/random/base/randu' ); 173 var pad = require( '@stdlib/string/pad' ); 174 175 var str = 'boop'; 176 var out; 177 var len; 178 var i; 179 180 for ( i = 0; i < 100; i++ ) { 181 len = round( randu()*10.0 ) + str.length; 182 out = pad( str, len, { 183 'lpad': 'beep', 184 'rpad': 'p' 185 }); 186 console.log( '%s. %d. %d.', out, len, out.length ); 187 } 188 ``` 189 190 </section> 191 192 <!-- /.examples --> 193 194 * * * 195 196 <section class="cli"> 197 198 ## CLI 199 200 <section class="usage"> 201 202 ### Usage 203 204 ```text 205 Usage: padstr [options] [<string>] --len <length> 206 207 Options: 208 209 -h, --help Print this message. 210 -V, --version Print the package version. 211 --len length String length. 212 --lpad str String used to left pad. Default: ''. 213 --rpad str String used to right pad. Default: ' '. 214 --cright Center right in the event of a tie. 215 --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. 216 ``` 217 218 </section> 219 220 <!-- /.usage --> 221 222 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 223 224 <section class="notes"> 225 226 ### Notes 227 228 - If the split separator is a [regular expression][mdn-regexp], ensure that the `split` option is either properly escaped or enclosed in quotes. 229 230 ```bash 231 # Not escaped... 232 $ echo -n $'beep\nboop' | padstr --len 10 --split /\r?\n/ 233 234 # Escaped... 235 $ echo -n $'beep\nboop' | padstr --len 10 --split /\\r?\\n/ 236 ``` 237 238 - The implementation ignores trailing delimiters. 239 240 </section> 241 242 <!-- /.notes --> 243 244 <section class="examples"> 245 246 ### Examples 247 248 ```bash 249 $ padstr beep --len 10 --lpad b --rpad p 250 bbbbeepppp 251 ``` 252 253 To use as a [standard stream][standard-streams], 254 255 ```bash 256 $ echo -n 'beep' | pad --len 9 --lpad a --rpad o 257 aabeepooo 258 ``` 259 260 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. 261 262 ```bash 263 $ echo -n 'beep\tboop' | pad --len 9 --lpad a --rpad o --split '\t' 264 aabeepooo 265 aaboopooo 266 ``` 267 268 </section> 269 270 <!-- /.examples --> 271 272 </section> 273 274 <!-- /.cli --> 275 276 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 277 278 <section class="related"> 279 280 * * * 281 282 ## See Also 283 284 - <span class="package-name">[`@stdlib/string/left-pad`][@stdlib/string/left-pad]</span><span class="delimiter">: </span><span class="description">left pad a string.</span> 285 - <span class="package-name">[`@stdlib/string/right-pad`][@stdlib/string/right-pad]</span><span class="delimiter">: </span><span class="description">right pad a string.</span> 286 287 </section> 288 289 <!-- /.related --> 290 291 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 292 293 <section class="links"> 294 295 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 296 297 [mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions 298 299 <!-- <related-links> --> 300 301 [@stdlib/string/left-pad]: https://github.com/stdlib-js/string/tree/main/left-pad 302 303 [@stdlib/string/right-pad]: https://github.com/stdlib-js/string/tree/main/right-pad 304 305 <!-- </related-links> --> 306 307 </section> 308 309 <!-- /.links -->