ECMAScript spec proposal for String.prototype.{padStart,padEnd}
CSS JavaScript HTML
Latest commit 30bea94 May 25, 2016 @ljharb ljharb Stage 4

README.md

String.prototype.padStart / String.prototype.padEnd

ECMAScript proposal, specs, tests, and reference implementation for String.prototype.padStart/padEnd.

This initial proposal was drafted by @KevinGrandon with input from @rwaldron and @dherman. Updated spec drafted by @ljharb with input from @rwaldron, @allenwb, and @dherman.

This proposal is currently at stage 4 of the process.

Designated TC39 reviewers: @littledan @michaelficarra

Rationale

Without a reasonable way to pad a string using native methods, working with JavaScript strings today is more painful than it should be. Without these functions, the language feels incomplete, and is a paper cut to what could be a very polished experience.

Due to common use, string padding functions exist in a majority of websites and frameworks. For example, nearly every app in FirefoxOS had implemented a left pad function, because they all needed some generic string padding operation.

It is highly probable that the majority of current string padding implementations are inefficient. Bringing this into the platform will improve performance of the web, and developer productivity as they no longer have to implement these common functions.

Spec

You can view the spec in markdown format or rendered as HTML.

Naming

For consistency with trimStart/trimRight, and reduce/reduceRight, despite the existence of startsWith/endsWith, we have settled on padLeft and padRight. Update per November 2015 TC39 meeting: the names will be padStart/padEnd, trimLeft/trimRight will change to trimStart/trimEnd, and trimLeft/trimRight aliases will be added to Annex B for web compatibility.

Semantics of "min length" vs "max length"

While updating this proposal with spec language, we discussed at length whether the first parameter should determine the minimum length or the maximum length of the padded string. Specifically, "min length" semantics says 'foo'.padEnd(4, '12') would output foo12, and "max length" semantics would output foo1. Since one of the primary use cases of padStart/padEnd is for formatting monospaced text in columns, and since "min length" semantics can be achieved via String#repeat, we decided that "max length" was the far more useful approach.

Left padding, with respect to the fill string: consistency with other languages

Per #6, the only languages we found that support multiple character fill strings that provide both "left" and "right" functionality are Ruby and PHP. Both language’s form of “pad on the left” takes the first part of the fill string, not the last. The clear example of why this matters is: "abc".padStart(10, "0123456789") - taking the last part of the fill string gives "3456789abc", whereas taking the first part gives "0123456abc". In other words, string.padStart(mask.length, mask) should do what one expects.