voca/pad_left.js

The ultimate JavaScript string library

'use strict';

var is_nil = require('./internal/is_nil.js');
require('./is_string.js');
var coerce_to_string = require('./internal/coerce_to_string.js');
var to_integer = require('./internal/to_integer.js');
require('./repeat.js');
var build_padding = require('./internal/build_padding.js');

/**
 * Pads `subject` from left to a new `length`.
 *
 * @function padLeft
 * @static
 * @since 1.0.0
 * @memberOf Manipulate
 * @param {string} [subject=''] The string to pad.
 * @param {int} [length=0] The length to left pad the string. No changes are made if `length` is less than `subject.length`.
 * @param {string} [pad=' '] The string to be used for padding.
 * @return {string} Returns the left padded string.
 * @example
 * v.padLeft('dog', 5);
 * // => '  dog'
 *
 * v.padLeft('bird', 6, '-');
 * // => '--bird'
 *
 * v.padLeft('cat', 6, '-=');
 * // => '-=-cat'
 */

function padLeft(subject, length, pad) {
  var subjectString = coerce_to_string.coerceToString(subject);
  var lengthInt = is_nil.isNil(length) ? 0 : to_integer.clipNumber(to_integer.toInteger(length), 0, to_integer.MAX_SAFE_INTEGER);
  var padString = coerce_to_string.coerceToString(pad, ' ');

  if (lengthInt <= subjectString.length) {
    return subjectString;
  }

  return build_padding.buildPadding(padString, lengthInt - subjectString.length) + subjectString;
}

module.exports = padLeft;