Added examples to String docs.

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 2e0259e33407a04562cc5c0e2b08820bcd8c52d1..488078d803a74eabbf71b1a9bb0713ec798aa9a9 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -5,45 +5,119 @@
 part of dart.core;
 
 /**
- * A class for working with a sequence of characters.
+ * A sequence of characters.
+ *
+ * A string can be either single or multiline. Single line strings are

[sra1, 2013/09/27 04:22:22]

Wearing my pedant hat:

A string itself if neither.

A string literal is a way of writing a string value.  A string literal can be
either ....

+ * written using matching single or double quotes, and multiline strings are
+ * written using triple quotes. The following are all valid Dart strings:
+ *
+ *     'Single quotes';
+ *     "Double quotes";
+ *     'Double quotes in "single" quotes';
+ *     "Single quotes in 'double' quotes";
+ *
+ *     '''A
+ *     multiline
+ *     string''';
+ *
+ *     """
+ *     Another
+ *     multiline
+ *     string""";
+ *
+ * Strings are immutable. Although you cannot change a string, you can perform
+ * an operation on a string and assign the result to a new string:

[sra1, 2013/09/27 04:22:22]

You can't perform an operation 'on' a string because it is immutable. Maybe
'with' is more accurate.

You can't assign the result to a new string.  The new string is a value that is
the result of an operation, not something that is assigned to.

"Although you cannot change a string, you can perform
an operation with a string to produce a new string an assign the result to a
variable:"

+ *
+ *     var string = 'Dart is fun';
+ *     var newString = string.substring(0, 5);
+ *
+ * You can use the plus (`+`) operator to concatenate strings:
+ *
+ *     'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'
+ *
+ * You can also use adjacent string literals for concatenation:

[sra1, 2013/09/27 04:22:22]

This is not really a concatenation operation, it is more a way of breaking up a
string literal or interpolated string into pieces.

+ *
+ *     'Dart ' 'is ' 'fun!';    // 'Dart is fun!'
+ *
+ * You can use `${}` to interpolate the value of Dart expressions
+ * within strings. The curly braces can be omitted when evaluating identifiers:
+ *
+ *     string = 'dartlang';
+ *     '$string has ${string.length} letters'; // 'dartlang has 8 letters'
  *
  * A string is represented by a sequence of Unicode UTF-16 code units
- * accessible through the [codeUnitAt] or the [codeUnits] members. Their
- * string representation is accessible through the index-operator.
+ * accessible through the [codeUnitAt] or the [codeUnits] members:
+ *
+ *     string = 'Dart';
+ *     string.codeUnitAt(0); // 68
+ *     string.codeUnits;     // [68, 97, 114, 116]
+ *
+ * The string representation of code units is accessible through the index
+ * operator:
+ *
+ *     string[0];            // 'D'
  *
  * The characters of a string are encoded in UTF-16. Decoding UTF-16, which
  * combines surrogate pairs, yields Unicode code points. Following a similar
- * terminology to Go we use the name "rune" for an integer representing a
- * Unicode code point. The runes of a string are accessible through the [runes]
- * getter.
+ * terminology to Go, we use the name 'rune' for an integer representing a
+ * Unicode code point. Use the [runes] property to get the runes of a string:
+ *
+ *     string.runes.toList(); // [68, 97, 114, 116]
+ *
+ * For a character outside the Basic Multilingual Plane (plane 0) that is
+ * composed of a surrogate pair, [runes] combines the pair and returns a
+ * single integer.  For example, the Unicode character for a
+ * musical G-clef ('𝄞') with rune value 0x1D11E consists of a UTF-16 surrogate
+ * pair: `0xD834` and `0xDD1E`. Using [codeUnits] returns the surrogate pair,
+ * and using `runes` returns their combined value:
  *
- * Strings are immutable.
+ *     var clef = '\u{1D11E}';
+ *     clef.codeUnits;         // [0xD834, 0xDD1E]
+ *     clef.runes.toList();    // [0x1D11E]
  *
- * It is a compile-time error for a class to attempt to extend or implement
- * String.
+ * The String class can not be extended or implemented. Attempting to do so
+ * yields a compile-time error.
  *
- * For concatenating strings efficiently, use the [StringBuffer] class. For
- * working with regular expressions, use the [RegExp] class.
+ * ## Other resources
+ *
+ * See [StringBuffer] to efficiently build a string incrementally. See
+ * [RegExp] to work with regular expressions.
+ *
+ * Also see:
+
+ * * [Dart Cookbook](https://www.dartlang.org/docs/cookbook/#strings)
+ * for String examples and recipes.
+ * * [Dart Up and Running]
+ * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-strings-and-regular-expressions)
  */
 abstract class String implements Comparable<String>, Pattern {
   /**
    * Allocates a new String for the specified [charCodes].
    *
    * The [charCodes] can be UTF-16 code units or runes. If a char-code value is
-   * 16-bit it is copied verbatim. If it is greater than 16 bits it is
-   * decomposed into a surrogate pair.
+   * 16-bit, it is copied verbatim:
+   *
+   *     new String.fromCharCodes([68]); // 'D'
+   *
+   * If a char-code value is greater than 16-bits, it is decomposed into a
+   * surrogate pair:
+   *
+   *     var clef = new String.fromCharCodes([0x1D11E]);
+   *     clef.codeUnitAt(0); // 0xD834
+   *     clef.codeUnitAt(1); // 0xDD1E
    */
   external factory String.fromCharCodes(Iterable<int> charCodes);
 
   /**
    * Allocates a new String for the specified [charCode].
    *
-   * The new string contains a single code unit if the [charCode] can be
-   * represented by a single UTF-16 code unit. Otherwise the [length] is 2 and
-   * the code units form a surrogate pair.
+   * If the [charCode] can be represented by a single UTF-16 code unit, the new
+   * string contains a single code unit. Otherwise, the [length] is 2 and
+   * the code units form a surrogate pair. See documentation for
+   * [fromCharCodes].
    *
-   * It is allowed (though generally discouraged) to create a String with only
-   * one half of a surrogate pair.
+   * Creating a String with half of a surrogate pair is legal but generally
+   * discouraged.
    */
   factory String.fromCharCode(int charCode) {
     List<int> charCodes = new List<int>.filled(1, charCode);
@@ -53,22 +127,14 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * Gets the character (as a single-code-unit [String]) at the given [index].
    *
-   * The returned string represents exactly one UTF-16 code unit which may be
-   * half of a surrogate pair. For example the Unicode character for a
-   * musical G-clef ("𝄞") with rune value 0x1D11E consists of a UTF-16 surrogate
-   * pair: `0xD834` and `0xDD1E`. Using the index-operator on this string yields
-   * a String with half of a surrogate pair:
-   *
-   *     var clef = "\u{1D11E}";
-   *     clef.length;  // => 2
-   *     clef.runes.first == 0x1D11E;  // => true
-   *     clef.runes.length;  // => 1
-   *     clef.codeUnitAt(0);  // => 0xD834
-   *     clef.codeUnitAt(1);  // => 0xDD1E
-   *     // The following strings are halves of a UTF-16 surrogate pair and
-   *     // thus invalid UTF-16 strings:
-   *     clef[0];  // => a string of length 1 with code-unit value 0xD834.
-   *     clef[1];  // => a string of length 1 with code-unit value 0xDD1E.
+   * The returned string represents exactly one UTF-16 code unit, which may be
+   * half of a surrogate pair. A single member of a surrogate pair is an
+   * invalid UTF-16 string:
+   *
+   *     var clef = '\u{1D11E}';
+   *     // These represent invalid UTF-16 strings.
+   *     clef[0].codeUnits;      // [0xD834]
+   *     clef[1].codeUnits;      // [0xDD1E]
    *
    * This method is equivalent to
    * `new String.fromCharCode(this.codeUnitAt(index))`.
@@ -84,101 +150,137 @@ abstract class String implements Comparable<String>, Pattern {
    * The length of the string.
    *
    * Returns the number of UTF-16 code units in this string. The number
-   * of [runes] might be less, if the string contains characters outside
-   * the basic multilingual plane (plane 0).
+   * of [runes] might be fewer, if the string contains characters outside
+   * the Basic Multilingual Plane (plane 0):
+   *
+   *     'Dart'.length;          // 4
+   *     'Dart'.runes.length;    // 4
+   *
+   *     var clef = '\u{1D11E}';
+   *     clef.length;            // 2
+   *     clef.runes.length;      // 1
    */
   int get length;
 
   /**
-   * Returns whether the two strings are equal.
+   * Returns true if the two strings are equal. False, otherwise.
    *
    * This method compares each individual code unit of the strings.
-   * Equivalently (for strings that are well-formed UTF-16) it compares each
-   * individual rune (code point).  It does not check for Unicode equivalence.
-   * For example the two following strings both represent the string "Amélie"
-   * but, due to their different encoding will not return equal.
+   * It does not check for Unicode equivalence.
+   * For example, both the following strings represent the string 'Amélie',
+   * but due to their different encoding, are not equal:
    *
-   *     "Am\xe9lie"
-   *     "Ame\u{301}lie"
+   *     'Am\xe9lie' == 'Ame\u{301}lie'; // false
    *
-   * In the first string the "é" is encoded as a single unicode code unit (also
-   * a single rune), whereas the second string encodes it as "e" with the
-   * combining accent character "◌́".
+   * The first string encodes 'é' as a single unicode code unit (also
+   * a single rune), whereas the second string encodes it as 'e' with the
+   * combining accent character '◌́'.
    */
   bool operator ==(var other);
 
   /**
-   * Returns whether this string ends with [other].
+   * Returns true if this string ends with [other]. For example:
+   *
+   *     'Dart'.endsWith('t'); // true
    */
   bool endsWith(String other);
 
   /**
-   * Returns whether this string starts with a match of [pattern].
+   * Returns true if this string starts with a match of [pattern].
+   *
+   *     var string = 'Dart';
+   *     string.startsWith('D');                       // true
+   *     string.startsWith(new RegExp(r'[A-Z][a-z]')); // true
    *
-   * If [index] is provided, instead check if the substring starting
-   * at that index starts with a match of [pattern].
+   * If [index] is provided, this method checks if the substring starting
+   * at that index starts with a match of [pattern]:
    *
-   * It is an error if [index] is negative or greater than [length].
+   *     string.startsWith('art', 1);                  // true
+   *     string.startsWith(new RegExp(r'\w{3}'));      // true
    *
-   * A [RegExp] containing "^" will not match if the [index] is greater than
+   * [index] must not be negative or greater than [length].
+   *
+   * A [RegExp] containing '^' does not match if the [index] is greater than
    * zero. The pattern works on the string as a whole, and does not extract
-   * a substring starting at [index] first. That is.
-   *     "abc".startsWith(new RegExp("^.", 1)) == false
+   * a substring starting at [index] first:
+   *
+   *     string.startsWith(new RegExp(r'^art'), 1);    // false
+   *     string.startsWith(new RegExp(r'art'), 1);     // true
    */
   bool startsWith(Pattern pattern, [int index = 0]);
 
   /**
-   * Returns the first position of a match of [pattern] in this string,
-   * starting at [start] (inclusive).
+   * Returns the position of the first match of [pattern] in this string,
+   * starting at [start], inclusive:
    *
-   * Returns -1 if a match could not be found.
+   *     var string = 'Dartisans';
+   *     string.indexOf('art');                     // 1
+   *     string.indexOf(new RegExp(r'[A-Z][a-z]')); // 0
    *
-   * It is an error if start is negative or greater than [length].
+   * Returns -1 if no match is found:
+   *
+   *     string.indexOf(new RegExp(r'dart'));       // -1
+   *
+   * [start] must not be negative or greater than [length].
    */
   int indexOf(Pattern pattern, [int start]);
 
   /**
-   * Returns the last position of a match [pattern] in this string, searching
-   * backward starting at [start] (inclusive).
+   * Returns the position of the last match [pattern] in this string, searching
+   * backward starting at [start], inclusive:
+   *
+   *     var string = 'Dartisans';
+   *     string.lastIndexOf('a');                    // 6
+   *     string.lastIndexOf(new RegExp(r'a(r|n)'));  // 6
    *
    * Returns -1 if [other] could not be found.
    *
-   * It is an error if start is negative or greater than [length].
+   *     string.lastIndexOf(new RegExp(r'DART'));    // -1
+   *
+   * [start] must not be negative or greater than [length].
    */
   int lastIndexOf(Pattern pattern, [int start]);
 
   /**
-   * Returns whether this string is empty.
+   * Returns true if this string is empty.
    */
   bool get isEmpty;
 
   /**
-   * Returns whether this string is not empty.
+   * Returns true if this string is not empty.
    */
   bool get isNotEmpty;
 
   /**
    * Creates a new string by concatenating this string with [other].
    *
-   * A sequence of strings can be concatenated by using [Iterable.join]:
-   *
-   *     var strings = ['foo', 'bar', 'geez'];
-   *     var concatenated = strings.join();
+   *     'dart' + 'lang'; // 'dartlang'
    */
   String operator +(String other);
 
   /**
-   * Returns a substring of this string in the given range.
-   * [startIndex] is inclusive and [endIndex] is exclusive.
+   * Returns the substring of this string that extends from [startIndex],
+   * inclusive, to [endIndex], exclusive.
+   *
+   *     var string = 'dartlang';
+   *     string.substring(1);    // 'artlang'
+   *     string.substring(1, 4); // 'art'
    */
   String substring(int startIndex, [int endIndex]);
 
   /**
    * Removes leading and trailing whitespace from a string.
    *
-   * If the string contains leading or trailing whitespace a new string with no
-   * leading and no trailing whitespace is returned. Otherwise, the string
-   * itself is returned.
+   * If the string contains leading or trailing whitespace, a new string with no
+   * leading and no trailing whitespace is returned:
+   *
+   *     '\tDart is fun\n'.trim(); // 'Dart is fun'
+   *
+   * Otherwise, the original string itself is returned:
+   *
+   *     var str1 = 'Dart';
+   *     var str2 = str1.trim();
+   *     identical(str1, str2);    // true
    *
    * Whitespace is defined by the Unicode White_Space property (as defined in
    * version 6.2 or later) and the BOM character, 0xFEFF.
@@ -203,28 +305,39 @@ abstract class String implements Comparable<String>, Pattern {
   String trim();
 
   /**
-   * Returns whether this string contains a match of [other].
+   * Returns true if this string contains a match of [other]:
    *
-   * If [startIndex] is provided, only matches at or after that index
-   * are considered.
+   *     var string = 'Dart strings';
+   *     string.contains('D');                     // true
+   *     string.contains(new RegExp(r'[A-Z]'));    // true
    *
-   * It is an error if [startIndex] is negative or greater than [length].
+   * If [startIndex] is provided, this method matches only at or after that
+   * index:
+   *
+   *     string.contains('X', 1);                  // false
+   *     string.contains(new RegExp(r'[A-Z]'), 1); // false
+   *
+   * [startIndex] must not be negative or greater than [length].
    */
   bool contains(Pattern other, [int startIndex = 0]);
 
   /**
-   * Returns a new string where the first occurence of [from] in this string
-   * is replaced with [to].
+   * Returns a new string in which  the first occurence of [from] in this string
+   * is replaced with [to]:
+   *
+   *     '0.0001'.replaceFirst(new RegExp(r'0'), ''); // '.0001'
    */
   String replaceFirst(Pattern from, String to);
 
   /**
-   * Replaces all substrings matching [from] with [replace].
+   * Replaces all substrings that match [from] with [replace].
    *
-   * Returns a new string where the non-overlapping substrings that match
+   * Returns a new string in which the non-overlapping substrings matching
    * [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
    * by the literal string [replace].
    *
+   *     'resume'.replaceAll(new RegExp(r'e'), 'é'); // 'résumé'
+   *
    * Notice that the [replace] string is not interpreted. If the replacement
    * depends on the match (for example on a [RegExp]'s capture groups), use
    * the [replaceAllMapped] method instead.
@@ -232,50 +345,61 @@ abstract class String implements Comparable<String>, Pattern {
   String replaceAll(Pattern from, String replace);
 
   /**
-   * Replace all substrings matching [from] by a string computed from the match.
+   * Replace all substrings that match [from] by a string computed from the
+   * match.
    *
-   * Returns a new string where the non-overlapping substrings that match
+   * Returns a new string in which the non-overlapping substrings that match
    * [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
    * by the result of calling [replace] on the corresponding [Match] object.
    *
    * This can be used to replace matches with new content that depends on the
    * match, unlike [replaceAll] where the replacement string is always the same.
    *
-   * Example (simplified pig latin):
+   * The [replace] function is called with the [Match] generated
+   * by the pattern, and its result is used as replacement.
+   *
+   * The function defined below converts each word in a string to simplified
+   * 'pig latin' using [replaceAllMapped]:
+   *
    *     pigLatin(String words) => words.replaceAllMapped(
-   *         new RegExp(r"\b(\w*?)([aeiou]\w*)", caseSensitive: false),
+   *         new RegExp(r'\b(\w*?)([aeiou]\w*)', caseSensitive: false),
    *         (Match m) => "${m[2]}${m[1]}${m[1].isEmpty ? 'way' : 'ay'}");
    *
-   * This would convert each word of a text to "pig-latin", so for example
-   *   `pigLatin("I have a secret now!")`
-   * returns
-   *   `"Iway avehay away ecretsay ownay!"`
+   *     pigLatin('I have a secret now!'); // 'Iway avehay away ecretsay ownay!'
    */
   String replaceAllMapped(Pattern from, String replace(Match match));
 
   /**
-   * Splits the string around matches of [pattern]. Returns
+   * Splits the string at matches of [pattern]. Returns
    * a list of substrings.
    *
-   * Splitting with an empty string pattern (`""`) splits at UTF-16 code unit
-   * boundaries and not at rune boundaries. The following two expressions
-   * are hence equivalent:
+   * Splitting with an empty string pattern (`''`) splits at UTF-16 code unit
+   * boundaries and not at rune boundaries:
+   *
+   *     var string = 'Pub';
+   *     string.split('');                       // ['P', 'u', 'b']
    *
-   *     string.split("")
-   *     string.codeUnits.map((unit) => new String.fromCharCode(unit))
+   *     string.codeUnits.map((unit) {
+   *       return new String.fromCharCode(unit);
+   *     }).toList();                            // ['P', 'u', 'b']
    *
-   * Unless it guaranteed that the string is in the basic multilingual plane
-   * (meaning that each code unit represents a rune) it is often better to
-   * map the runes instead:
+   *     // String made up of two code units, but one rune.
+   *     string = '\u{1D11E}';
+   *     string.split('').length;                 // 2
    *
-   *     string.runes.map((rune) => new String.fromCharCode(rune))
+   * You should [map] the runes unless you are certain that the string is in
+   * the basic multilingual plane (meaning that each code unit represents a
+   * rune):
+   *
+   *     string.runes.map((rune) => new String.fromCharCode(rune));
    */
   List<String> split(Pattern pattern);
 
   /**
-   * Splits the string on the [pattern], then converts each part and each match.
+   * Splits the string, converts its parts, and combines them into a new

[sra1, 2013/09/27 04:22:22]

Perhaps: Splits the string into parts, ...

+   * string.
    *
-   * The pattern is used to split the string into parts and separating matches.
+   * [pattern] is used to split the string into parts and separating matches.
    *
    * Each match is converted to a string by calling [onMatch]. If [onMatch]
    * is omitted, the matched string is used.
@@ -284,6 +408,10 @@ abstract class String implements Comparable<String>, Pattern {
    * [onNonMatch] is omitted, the non-matching part is used.
    *
    * Then all the converted parts are combined into the resulting string.
+   *
+   *     'Eats shoots leaves'.splitMapJoin((new RegExp(r'shoots')),
+   *         onMatch:    (m) => '${m.group(0)}',
+   *         onNonMatch: (n) => '*'); // *shoots*
    */
   String splitMapJoin(Pattern pattern,
                       {String onMatch(Match match),
@@ -295,24 +423,36 @@ abstract class String implements Comparable<String>, Pattern {
   List<int> get codeUnits;
 
   /**
-   * Returns an iterable of Unicode code-points of this string.
+   * Returns an [Iterable] of Unicode code-points of this string.
    *
-   * If the string contains surrogate pairs, they will be combined and returned
+   * If the string contains surrogate pairs, they are combined and returned
    * as one integer by this iterator. Unmatched surrogate halves are treated
    * like valid 16-bit code-units.
    */
   Runes get runes;
 
   /**
-   * If this string is not already all lower case, returns a new string
-   * where all characters are made lower case. Returns [:this:] otherwise.
+   * Converts all characters in this string to lower case.

[sra1, 2013/09/27 04:22:22]

This sounds like the string is modified.

+   * If the string is already in all lower case, this method returns [:this:].
+   *
+   *     'ALPHABET'.toLowerCase(); // 'alphabet'
+   *     'abc'.toLowerCase();      // 'abc'
+   *
+   * This function uses the language independent Unicode mapping and thus only
+   * works in some languages.
    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toLowerCase();
 
   /**
-   * If this string is not already all upper case, returns a new string
-   * where all characters are made upper case. Returns [:this:] otherwise.
+   * Converts all characters in this string to upper case.
+   * If the string is already in all upper case, this method returns [:this:].
+   *
+   *     'alphabet'.toUpperCase(); // 'ALPHABET'
+   *     'ABC'.toUpperCase();      // 'ABC'
+   *
+   * This function uses the language independent Unicode mapping and thus only
+   * works in some languages.
    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toUpperCase();
@@ -329,7 +469,7 @@ class Runes extends IterableBase<int> {
 
   int get last {
     if (string.length == 0) {
-      throw new StateError("No elements.");
+      throw new StateError('No elements.');
     }
     int length = string.length;
     int code = string.codeUnitAt(length - 1);
@@ -401,7 +541,7 @@ class RuneIterator implements BidirectionalIterator<int> {
     if (index > 0 && index < string.length &&
         _isLeadSurrogate(string.codeUnitAt(index - 1)) &&
         _isTrailSurrogate(string.codeUnitAt(index))) {
-      throw new ArgumentError("Index inside surrogate pair: $index");
+      throw new ArgumentError('Index inside surrogate pair: $index');
     }
   }