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

sdk/lib/core/string.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * A sequence of characters.
  *
  * A string can be either single or multiline. Single line strings are
@@ skipping 308 matching lines @@
    *     2029          ; White_Space # Zp   PARAGRAPH SEPARATOR
    *     202F          ; White_Space # Zs   NARROW NO-BREAK SPACE
    *     205F          ; White_Space # Zs   MEDIUM MATHEMATICAL SPACE
    *     3000          ; White_Space # Zs   IDEOGRAPHIC SPACE
    *
    *     FEFF          ; BOM                ZERO WIDTH NO_BREAK SPACE
    */
   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 [width].
    *
    * 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 [width].
    *
-   * If [newLength] is already smaller than or equal to `this.length`,
-   * no padding will happen. A negative `newLength` is allowed,
-   * but no padding happens.
+   * If [width] is already smaller than or equal to `this.length`,
+   * no padding is added. A negative `width` is treated as zero.
    *
-   * The [padding] must have length 1.
+   * If [padding] has length different from 1, the result will not
+   * have length `width`. 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 width, [String padding = ' ']);
 
   /**
-   * Pads this string on the right if it is shorther than [newSize].
+   * Pads this string on the right if it is shorther than [width].
    *
-   * 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 [width].
    *
-   * If [newLength] is already smaller than or equal to `this.length`,
-   * no padding will happen. A negative `newLength` is allowed,
-   * but no padding happens.
+   * If [width] is already smaller than or equal to `this.length`,
+   * no padding is added. A negative `width` is treated as zero.
    *
-   * The [padding] must have length 1.
+   * If [padding] has length different from 1, the result will not
+   * have length `width`. 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 width, [String padding = ' ']);
 
   /**
    * Returns true if this string contains a match of [other]:
    *
    *     var string = 'Dart strings';
    *     string.contains('D');                     // true
    *     string.contains(new RegExp(r'[A-Z]'));    // true
    *
    * If [startIndex] is provided, this method matches only at or after that
    * index:
@@ skipping 333 matching lines @@
         _position = position - 1;
         _currentCodePoint = _combineSurrogatePair(prevCodeUnit, codeUnit);
         return true;
       }
     }
     _position = position;
     _currentCodePoint = codeUnit;
     return true;
   }
 }