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 [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]:
    *
    *     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;
   }
 }