README.md (4822B)
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 # Right Pad 22 23 > Right pad a string. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var rpad = require( '@stdlib/string/right-pad' ); 31 ``` 32 33 #### rpad( str, len\[, pad] ) 34 35 Right pads a `string` such that the padded `string` has a `length` of **at least** `len`. 36 37 ```javascript 38 var str = rpad( 'a', 5 ); 39 // returns 'a ' 40 ``` 41 42 By default, an input `string` is padded with `spaces`. To pad with a different character or sequence of characters, provide a `pad` string. 43 44 ```javascript 45 var str = rpad( 'beep', 10, 'p' ); 46 // returns 'beeppppppp' 47 48 str = rpad( 'beep', 12, 'boop' ); 49 // returns 'beepboopboop' 50 ``` 51 52 </section> 53 54 <!-- /.usage --> 55 56 <section class="notes"> 57 58 ## Notes 59 60 - An output `string` is **not** guaranteed to have a length of **exactly** `len`, but to have a `length` of **at least** `len`. To generate a padded `string` having a `length` equal to `len` 61 62 ```javascript 63 var str = rpad( 'beep', 10, 'boop' ); 64 // returns 'beepboopboop' => length 12 65 66 str = str.substring( 0, 10 ); 67 // returns 'beepboopbo' => length 10 68 ``` 69 70 </section> 71 72 <!-- /.notes --> 73 74 <section class="examples"> 75 76 ## Examples 77 78 <!-- eslint no-undef: "error" --> 79 80 ```javascript 81 var round = require( '@stdlib/math/base/special/round' ); 82 var randu = require( '@stdlib/random/base/randu' ); 83 var rpad = require( '@stdlib/string/right-pad' ); 84 85 var str = 'beep'; 86 var n; 87 var i; 88 89 for ( i = 0; i < 100; i++ ) { 90 n = round( randu()*10.0 ) + str.length; 91 console.log( rpad( str, n, 'p' ) ); 92 } 93 ``` 94 95 </section> 96 97 <!-- /.examples --> 98 99 * * * 100 101 <section class="cli"> 102 103 ## CLI 104 105 <section class="usage"> 106 107 ### Usage 108 109 ```text 110 Usage: rpad [options] [<string>] --len=<length> 111 112 Options: 113 114 -h, --help Print this message. 115 -V, --version Print the package version. 116 --len length Minimum string length. 117 --pad str String used to pad. Default: ' '. 118 --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. 119 ``` 120 121 </section> 122 123 <!-- /.usage --> 124 125 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 126 127 <section class="notes"> 128 129 ### Notes 130 131 - If the split separator is a [regular expression][mdn-regexp], ensure that the `split` option is either properly escaped or enclosed in quotes. 132 133 ```bash 134 # Not escaped... 135 $ echo -n $'beep\nboop' | rpad --len 8 --pad % --split /\r?\n/ 136 137 # Escaped... 138 $ echo -n $'beep\nboop' | rpad --len 8 --pad % --split /\\r?\\n/ 139 ``` 140 141 - The implementation ignores trailing delimiters. 142 143 </section> 144 145 <!-- /.notes --> 146 147 <section class="examples"> 148 149 ### Examples 150 151 ```bash 152 $ rpad beep --len 10 --pad p 153 beeppppppp 154 ``` 155 156 To use as a [standard stream][standard-streams], 157 158 ```bash 159 $ echo -n 'boop' | rpad --len 8 --pad % 160 boop%%%% 161 ``` 162 163 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. 164 165 ```bash 166 $ echo -n 'boop\tbeep' | rpad --len 8 --pad % --split '\t' 167 boop%%%% 168 beep%%%% 169 ``` 170 171 </section> 172 173 <!-- /.examples --> 174 175 </section> 176 177 <!-- /.cli --> 178 179 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 180 181 <section class="related"> 182 183 * * * 184 185 ## See Also 186 187 - <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> 188 - <span class="package-name">[`@stdlib/string/pad`][@stdlib/string/pad]</span><span class="delimiter">: </span><span class="description">pad a string.</span> 189 190 </section> 191 192 <!-- /.related --> 193 194 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 195 196 <section class="links"> 197 198 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 199 200 [mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions 201 202 <!-- <related-links> --> 203 204 [@stdlib/string/left-pad]: https://github.com/stdlib-js/string/tree/main/left-pad 205 206 [@stdlib/string/pad]: https://github.com/stdlib-js/string/tree/main/pad 207 208 <!-- </related-links> --> 209 210 </section> 211 212 <!-- /.links -->