Allow multi-codeunit padding in String.padLeft/padRight.

sdk/lib/core/string.dart

Index: sdk/lib/core/string.dart
diff --git a/sdk/lib/core/string.dart b/sdk/lib/core/string.dart
index 0a3c617d514986e5f2a039964385531983f5e88a..0e8445641b0b40f253f71e56a8c217f311076e0c 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -326,42 +326,53 @@ abstract class String implements Comparable<String>, Pattern {
   String trim();
 
   /**
-   * Creates a new string that repeats this string a number of times.
+   * Creates a new string by concatenating this string with itself a number
+   * of times.
    *
-   * If [separator] is provided, it is inserted between the copies
-   * of this string.
+   * The result of `str * n` is equivalent to
+   * `str + str + ...`(n times)`... + str`.
    *
-   * The [times] number must be non-negative.
+   * Returns an empty string if [times] is zero or negative.
    */
-  String repeat(int times, [String separator = ""]);
+  String operator *(int times);
 
   /**
-   * Pads this string on the left if it is shorther than [newSize].
+   * Pads this string on the left if it is shorther than [newLength].
    *
    * Return a new string that prepends [padding] onto this string
-   * until the total length is [newLength].
+   * one time for each position the length is less than [newLength].
    *
    * If [newLength] is already smaller than or equal to `this.length`,
    * no padding will happen. A negative `newLength` is allowed,

[sra1, 2014/02/19 21:18:09]

Maybe: happen -> be added.

[Lasse Reichstein Nielsen, 2014/02/20 07:16:40]

Done.

    * but no padding happens.
    *
-   * The [padding] must have length 1.
+   * If [padding] has length different from 1, the result will not
+   * have length `newLength`. This may be useful for cases where the
+   * padding is a longer string representing a single character, like
+   * `" "` or `"\u{10002}`".
+   * In that case, the user should make sure that `this.length` is
+   * the correct measure of the strings length.
    */
-  String padLeft(int newLength, String padding);
+  String padLeft(int newLength, [String padding = ' ']);

[sra1, 2014/02/19 21:18:09]

I think 'width' is a better name than 'newLength'.
We pad something 'to a width', and by using different roots, 'width' and
'length', it feels more comfortable that the input and output may be different
conceptual units.

E.g. it sounds better to say

  "the result will not have length `width`"

than

  "the result will not have length `newLength`"

[Lasse Reichstein Nielsen, 2014/02/20 07:16:40]

Done.

 
   /**
-   * Pads this string on the right if it is shorther than [newSize].
+   * Pads this string on the right if it is shorther than [newLength].
    *
-   * Return a new string that append [padding] after this string
-   * until the total length is [newLength].
+   * Return a new string that appends [padding] after this string
+   * one time for each position the length is less than [newLength].
    *
    * If [newLength] is already smaller than or equal to `this.length`,
    * no padding will happen. A negative `newLength` is allowed,
    * but no padding happens.
    *
-   * The [padding] must have length 1.
+   * If [padding] has length different from 1, the result will not
+   * have length `newLength`. This may be useful for cases where the
+   * padding is a longer string representing a single character, like
+   * `" "` or `"\u{10002}`".
+   * In that case, the user should make sure that `this.length` is
+   * the correct measure of the strings length.
    */
-  String padRight(int newLength, String padding);
+  String padRight(int newLength, [String padding = ' ']);
 
   /**
    * Returns true if this string contains a match of [other]: