lpad

Left pad a string.

Usage

var lpad = require( '@stdlib/string/left-pad' );

lpad( str, len[, pad] )

Left pads a string such that the padded string has a length of at least len.

var str = lpad( 'a', 5 );
// returns '    a'

By default, an input string is padded with a Unicode "space" character (U+0020). To pad with a different character or sequence of characters, provide a pad string.

var str = lpad( 'beep', 10, 'b' );
// returns 'bbbbbbbeep'

str = lpad( 'boop', 12, 'beep' );
// returns 'beepbeepboop'

Notes

  • 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

    var str = lpad( 'boop', 10, 'beep' ); // => length 12
// returns 'beepbeepboop'

str = str.substring( str.length-10 ); // => length 10
// returns 'epbeepboop'

  • This function differs from String.prototype.padStart in the following ways:

    • The function is not guaranteed to return a string having a length exactly equal to len (as explained above).
    • The function does not truncate pad (from the end) in order to ensure the returned string has length len.

    To replicate String.prototype.padStart truncation behavior

    var floorb = require( '@stdlib/math/base/special/floorb' );

function padStart( str, len, pad ) {
    var n;
    if ( len <= str.length ) {
        return str;
    }
    n = floorb( len-str.length, 1, pad.length ) + str.length;
    return pad.substring( 0, len-n ) + lpad( str, n, pad );
}

var str = padStart( 'boop', 10, 'beep' );
// returns 'bebeepboop'

Examples

var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
var lpad = require( '@stdlib/string/left-pad' );

var str = 'beep';
var i;
for ( i = 0; i < 100; i++ ) {
    console.log( lpad( str, discreteUniform( str.length, str.length+10 ), 'b' ) );
}

CLI

Usage

Usage: lpad [options] --len=<length> [<string>]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --len length          Minimum string length.
         --pad str             String used to pad. Default: ' '.
         --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 $'beep\nboop' | lpad -len 8 --split /\r?\n/

# Escaped...
$ echo -n $'beep\nboop' | lpad -len 8 --split /\\r?\\n/

  • The implementation ignores trailing delimiters.

Examples

$ lpad beep --len 10 --pad b
bbbbbbbeep

To use as a standard stream,

$ echo -n 'beep' | lpad --len 8
    beep

By default, when used as a standard stream, the implementation assumes newline-delimited data. To specify an alternative delimiter, set the split option.

$ echo -n 'boop\tbeep' |  lpad --len 8 --split '\t'
    boop
    beep

See Also

Did you find this page helpful?