README
pad
Pad a string.
Installation
npm install @stdlib/string-pad
Usage
var pad = require( '@stdlib/string-pad' );
pad( str, len[, options] )
Pads a string
such that the padded string
has a length
of len
.
var str = pad( 'a', 5 );
// returns 'a '
The function accepts the following options
:
- lpad:
string
used to left pad. Default:''
. - rpad:
string
used to right pad. Default:' '
. - centerRight:
boolean
indicating whether to center right in the event of a tie. Default:false
(i.e., center left).
By default, an input string
is padded with spaces. To pad with a different character or sequence of characters, provide a pad string
.
var str = pad( 'a', 10, {
'lpad': 'b'
});
// returns 'bbbbbbbbba'
str = pad( 'a', 12, {
'rpad': 'b'
});
// returns 'abbbbbbbbbbb'
To center an input string
, provide both lpad
and rpad
options.
var opts = {
'lpad': 'a',
'rpad': 'c'
};
var str = pad( 'b', 11, opts );
// returns 'aaaaabccccc'
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).
var opts = {
'lpad': 'a',
'rpad': 'c'
};
var str = pad( 'b', 10, opts );
// returns 'aaaabccccc'
To center right, set the centerRight
option.
var opts = {
'lpad': 'a',
'rpad': 'c',
'centerRight': true
};
var str = pad( 'b', 10, opts );
// returns 'aaaaabcccc'
Notes
In contrast to lpad and rpad, any padding which does not evenly divide available space is trimmed such that the returned
string
length is alwayslen
.var opts = { 'lpad': 'boop', 'rpad': 'woot' }; var str = pad( 'beep', 10, opts ); // returns 'boobeepwoo'
Similarly, if
len < str.length
, the inputstring
is trimmed.// Pad right, trim right: var str = pad( 'beep', 2 ); // returns 'be' // Pad left, trim left: str = pad( 'beep', 2, { 'lpad': 'b' }); // returns 'ep' // Pad both, trim both: str = pad( 'beep', 2, { 'lpad': '@', 'rpad': '!' }); // returns 'ee' // Pad both, trim both starting from left: str = pad( 'abcdef', 3, { 'lpad': '@', 'rpad': '!' }); // returns 'cde' // Pad both, trim both starting from right: str = pad( 'abcdef', 3, { 'lpad': '@', 'rpad': '!', 'centerRight': true }); // returns 'bcd'
Examples
var round = require( '@stdlib/math-base-special-round' );
var randu = require( '@stdlib/random-base-randu' );
var pad = require( '@stdlib/string-pad' );
var str = 'boop';
var out;
var len;
var i;
for ( i = 0; i < 100; i++ ) {
len = round( randu()*10.0 ) + str.length;
out = pad( str, len, {
'lpad': 'beep',
'rpad': 'p'
});
console.log( '%s. %d. %d.', out, len, out.length );
}
CLI
Installation
To use the module as a general utility, install the module globally
npm install -g @stdlib/string-pad
Usage
Usage: padstr [options] [<string>] --len <length>
Options:
-h, --help Print this message.
-V, --version Print the package version.
--len length String length.
--lpad str String used to left pad. Default: ''.
--rpad str String used to right pad. Default: ' '.
--cright Center right in the event of a tie.
--split sep Delimiter for stdin data. Default: '/\\r?\\n/'.
Notes
If the split separator is a regular expression, ensure that the
split
option is either properly escaped or enclosed in quotes.# Not escaped... $ echo -n