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..a5fc62670517e79cd8f811a220a8c6d1ca8a31b4 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -7,31 +7,101 @@ part of dart.core;
 /**
  * A class for working with a sequence of characters.

[mem, 2013/09/05 23:09:09]

how about just "A sequence of characters."

One of the guidelines is to make "the first words meaningful" and to avoid
things like "support for" and "an api" for....

[shailentuli, 2013/09/23 11:50:27]

Punting to kathy.

[Kathy Walrath, 2013/09/25 18:47:38]

What mem sed.

  *
+ * A string can be either single or multiline. Single line strings are
+ * written using matching single or double quotes, and mutliline strings are
+ * written using triple quotes. These are all valid Dart strings:

[mem, 2013/09/05 23:09:09]

The following are all ...

[shailentuli, 2013/09/23 11:50:27]

Done.

+ *
+ *     'Single quotes';
+ *     "Double quotes";
+ *     'Double quotes in "single" quotes';
+ *     "Single quotes in 'double' quotes";
+ *
+ *     '''A
+ *     multiline
+ *     string''';
+ *
+ *     """
+ *     Another
+ *     multiline
+ *     string""";
+ *
+ * Strings are immutable. While you cannot change a string, you can perform an

[mem, 2013/09/05 23:09:09]

Although you cannot...

[shailentuli, 2013/09/23 11:50:27]

Done.

+ * operation on a string and assign the result to a new string:
+ *
+ *     var string = 'Dart is fun';
+ *     var newString = string.toUpperCase();

[mem, 2013/09/05 23:09:09]

Do you need
// 'Dart is fun'
// 'DART IS FUN'
??

Also use an exclamation mark! 'Dart is fun!'

[shailentuli, 2013/09/23 11:50:27]

Not really. I'm just showing assignment. 

+ *
+ * You can use the `+` operator to concatenate strings:

[mem, 2013/09/05 23:09:09]

You can use the plus (`+`) operator ...

[shailentuli, 2013/09/23 11:50:27]

Done.

+ *
+ *     'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'
+ *
+ * You can also use string literals for concatenation:

[mem, 2013/09/05 23:09:09]

You can also use adjacent string literals ...

[shailentuli, 2013/09/23 11:50:27]

Done.

+ *
+ *     'Dart ' 'is ' 'fun!';    // 'Dart is fun!'
+ *
+ * You can use `${}` syntax for interpolating the value of Dart expressions
+ * within strings. The curly braces can be omitted when evaluating identifiers:

[mem, 2013/09/05 23:09:09]

You can use `${}` ...

also
for interpolating -> to interpolate

[shailentuli, 2013/09/23 11:50:27]

Done.

+ *
+ *     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:

[mem, 2013/09/05 23:09:09]

--> accessible with [codeUnits] or [codeUnitAt]:

(also put in same order as snippet below)

[shailentuli, 2013/09/23 11:50:27]

Leaving Florian's ordering. Re-ordered my example.

+ *
+ *     string = 'Dart';
+ *     string.codeUnits;     // [68, 97, 114, 116]
+ *     string.codeUnitAt(0); // 68
+
+ * The string representation of the code units is accessible through the index

[mem, 2013/09/05 23:09:09]

The string representation -> the character representation

??

[shailentuli, 2013/09/23 11:50:27]

No, better as string. String is well understood, character is a bit fuzzy in
Dart. 

+ * 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
+ * terminology to Go we use the name 'rune' for an integer representing a

[mem, 2013/09/05 23:09:09]

Remove reference to Go....also reword...
A 'rune' is an integer representing a Unicode code point.

[shailentuli, 2013/09/23 11:50:27]

Keeping Florian's language. He wants the Go reference. I think it is good to
have it there.

  * Unicode code point. The runes of a string are accessible through the [runes]
- * getter.
+ * property:

[mem, 2013/09/05 23:09:09]

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

[mem, 2013/09/05 23:09:09]

I feel like this para is too much for the class-level section. Move to [runes].

[mem, 2013/09/05 23:09:09]

you haven't defined the basic multilingual plane

[shailentuli, 2013/09/23 11:50:27]

No, keeping it. This runes vs. codeUnits thing applies to several methods, and a
class level discussion is warranted.

[shailentuli, 2013/09/23 11:50:27]

That's OK. This is not a Dart concept. Its a big topic, and users are better off
understanding this very well from other sources.

+ * 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:

[mem, 2013/09/05 23:09:09]

Remove 'using', link to codeUnits

--> [codeUnits] returns the surrogate pair, and `runes` returns their combined
value

[shailentuli, 2013/09/23 11:50:27]

Keeping it as is, because I don't want the sentence to start with a lc letter.

  *
- * 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.

[mem, 2013/09/05 23:09:09]

Extending or implementing String is a compile-time error.

[shailentuli, 2013/09/23 11:50:27]

Done.

  *
- * 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

[mem, 2013/09/05 23:09:09]

delete 'incrementally'

[shailentuli, 2013/09/23 11:50:27]

No, keeping it. 'Build a string' by itself reads poorly to me.

+ * [RegExp] to work with regular expressions.
+ *
+ * See the [Dart Cookbook](https://www.dartlang.org/docs/cookbook/#strings)
+ * for String examples and recipes.

[mem, 2013/09/05 23:09:09]

Link to Dart Up & Running, language tour, and library tour

Also...make it into a bulleted list.

https://www.dartlang.org/docs/dart-up-and-running/contents/ch02.html#strings
https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-str...

[shailentuli, 2013/09/23 11:50:27]

Linking to the Library tour.

+ *
  */
 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 it is greater than 16-bits, it is decomposed into a surrogate pair:

[mem, 2013/09/05 23:09:09]

If a char-code value is greater than 16-bits,

[shailentuli, 2013/09/23 11:50:27]

Done.

+   *
+   *     var clef = new String.fromCharCodes([0x1D11E]);
+   *     clef.codeUnitAt(0); // 0xD834
+   *     clef.codeUnitAt(1); // 0xDD1E
    */
   external factory String.fromCharCodes(Iterable<int> charCodes);
 
@@ -40,7 +110,8 @@ abstract class String implements Comparable<String>, Pattern {
    *
    * 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

[mem, 2013/09/05 23:09:09]

Reverse the sense of the first sentence. Add comma after Otherwise.

If the [charCode] can be represented by a single UTF-16 code unit, then the new
string contains a single code unit. Otherwise,

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * the code units form a surrogate pair.
+   * 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.

[mem, 2013/09/05 23:09:09]

It is allowed is passive. How about the following instead:

You should avoid creating a String with half of a surrogate pair.

[shailentuli, 2013/09/23 11:50:27]

Done.

@@ -53,22 +124,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:
+   * 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}";
-   *     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.
+   *     // 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))`.
@@ -85,7 +148,14 @@ abstract class String implements Comparable<String>, Pattern {
    *
    * Returns the number of UTF-16 code units in this string. The number
    * of [runes] might be less, if the string contains characters outside

[mem, 2013/09/05 23:09:09]

might be less -> might be fewer

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * the basic multilingual plane (plane 0).
+   * the Basic Multilingual Plane (plane 0). For example:
+   *
+   *     'Dart'.length;          // 4
+   *     'Dart'.runes.length;    // 4
+   *
+   *     var clef = "\u{1D11E}";
+   *     clef.length;            // 2
+   *     clef.runes.length;      // 1
    */
   int get length;
 
@@ -95,11 +165,10 @@ abstract class String implements Comparable<String>, Pattern {
    * This method compares each individual code unit of the strings.
    * Equivalently (for strings that are well-formed UTF-16) it compares each

[mem, 2013/09/05 23:09:09]

For strings that are well-formed UTF-16, it compares ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    * 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.
+   * 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

[mem, 2013/09/05 23:09:09]

The first string encodes "é" as a single unicode code unit (also a single rune).

[shailentuli, 2013/09/23 11:50:27]

Done.

    * a single rune), whereas the second string encodes it as "e" with the

[mem, 2013/09/05 23:09:09]

The second string encodes "é" as the letter "e" and the combining accent
character "◌́".

[shailentuli, 2013/09/23 11:50:27]

Done.

@@ -108,32 +177,49 @@ abstract class String implements Comparable<String>, Pattern {
   bool operator ==(var other);
 
   /**
-   * Returns whether this string ends with [other].
+   * Returns whether this string ends with [other]. For example:

[mem, 2013/09/05 23:09:09]

Return true if this string ...

[shailentuli, 2013/09/23 11:50:27]

Done.

+   *
+   *     'Dart'.endsWith('t'); // true
    */
   bool endsWith(String other);
 
   /**
    * Returns whether this string starts with a match of [pattern].

[mem, 2013/09/05 23:09:09]

Returns true if this string...

[shailentuli, 2013/09/23 11:50:27]

Done.

    *
-   * If [index] is provided, instead check if the substring starting
-   * at that index 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 checks if the substring starting

[mem, 2013/09/05 23:09:09]

instead -> this method

[shailentuli, 2013/09/23 11:50:27]

Done.

+   * at that index starts with a match of [pattern]:
+   *
+   *     string.startsWith('art', 1);                  // true
+   *     string.startsWith(new RegExp(r'\w{3}'));      // true
    *
    * It is an error if [index] is negative or greater than [length].

[mem, 2013/09/05 23:09:09]

An error occurs if ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    *
-   * A [RegExp] containing "^" will not match if the [index] is greater than
+   * A [RegExp] containing '^' will not match if the [index] is greater than

[mem, 2013/09/05 23:09:09]

will -> does

[mem, 2013/09/05 23:09:09]

Here single quotes are used to delineate a character '^'. Other places use
double quotes "é".
Prolly should make that consistent.

[shailentuli, 2013/09/23 11:50:27]

Done.

[shailentuli, 2013/09/23 11:50:27]

Done.

    * 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. For example:
+   *
+   *     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,

[mem, 2013/09/05 23:09:09]

Returns the position of the first match of [pattern] ...

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * starting at [start] (inclusive).
+   * starting at [start] (inclusive). For example:
    *
-   * 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 a match is not found:

[mem, 2013/09/05 23:09:09]

Returns -1 if no match is found.

[shailentuli, 2013/09/23 11:50:27]

Done.

+   *
+   *     string.indexOf(new RegExp(r'dart'));       // -1
+   *
+   * It is an error if [start] is negative or greater than [length].

[mem, 2013/09/05 23:09:09]

An error occurs if ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    */
   int indexOf(Pattern pattern, [int start]);
 
@@ -141,8 +227,14 @@ abstract class String implements Comparable<String>, Pattern {
    * Returns the last position of a match [pattern] in this string, searching

[mem, 2013/09/05 23:09:09]

Returns the position of the last match of [pattern] ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    * 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.
    *
+   *     string.lastIndexOf(new RegExp(r'DART'));    // -1
+   *
    * It is an error if start is negative or greater than [length].

[mem, 2013/09/05 23:09:09]

An error occurs ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    */
   int lastIndexOf(Pattern pattern, [int start]);
@@ -160,16 +252,22 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * Creates a new string by concatenating this string with [other].
    *
+   *     'dart' + 'lang'; // 'dartlang'
+   *
    * A sequence of strings can be concatenated by using [Iterable.join]:

[mem, 2013/09/05 23:09:09]

Use [Iterable.join] to concatenate a sequence of strings.

[shailentuli, 2013/09/23 11:50:27]

Done.

    *
-   *     var strings = ['foo', 'bar', 'geez'];
-   *     var concatenated = strings.join();
+   *     var fruits = ['apple', 'banana', 'orange'];
+   *     fruits.join(" : "); // 'apple : banana : orange'
    */
   String operator +(String other);
 
   /**
    * Returns a substring of this string in the given range.

[mem, 2013/09/05 23:09:09]

Returns the substring of this string that extends from [startIndex] (inclusive)
to [endIndex] (exclusive).

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * [startIndex] is inclusive and [endIndex] is exclusive.
+   * [startIndex] is inclusive and [endIndex] is exclusive. For example:
+   *
+   *     var string = 'dartlang';
+   *     string.substring(1);    // 'artlang'
+   *     string.substring(1, 4); // 'art'
    */
   String substring(int startIndex, [int endIndex]);
 
@@ -177,8 +275,13 @@ abstract class String implements Comparable<String>, Pattern {
    * Removes leading and trailing whitespace from a string.
    *
    * If the string contains leading or trailing whitespace a new string with no

[mem, 2013/09/05 23:09:09]

whitespace --> whitespace,

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * leading and no trailing whitespace is returned. Otherwise, the string
-   * itself is returned.
+   * leading and no trailing whitespace is returned:
+   *
+   *     '\tDart is fun\n'.trim(); // 'Dart is fun'
+   *
+   * Otherwise, the string itself is returned:

[mem, 2013/09/05 23:09:09]

the string itself --> the original string

[shailentuli, 2013/09/23 11:50:27]

Done.

+   *
+   *     'Dart'.trim();            // 'Dart'
    *
    * Whitespace is defined by the Unicode White_Space property (as defined in
    * version 6.2 or later) and the BOM character, 0xFEFF.
@@ -203,10 +306,17 @@ abstract class String implements Comparable<String>, Pattern {
   String trim();
 
   /**
-   * Returns whether this string contains a match of [other].
+   * Returns whether this string contains a match of [other]:

[mem, 2013/09/05 23:09:09]

Returns true if this string contains a match of [other]:

[shailentuli, 2013/09/23 11:50:27]

Done.

+   *
+   *     var string = 'Dart strings';
+   *     string.contains('D');                     // true
+   *     string.contains(new RegExp(r'[A-Z]'));    // true
    *
    * If [startIndex] is provided, only matches at or after that index

[mem, 2013/09/05 23:09:09]

..., this method only considers matches at or after that index.

[shailentuli, 2013/09/23 11:50:27]

Done.

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * are considered.
+   * are considered:
+   *
+   *     string.contains('X', 1);                  // false
+   *     string.contains(new RegExp(r'[A-Z]'), 1); // false
    *
    * It is an error if [startIndex] is negative or greater than [length].

[mem, 2013/09/05 23:09:09]

An error occurs if ...

[shailentuli, 2013/09/23 11:50:27]

Done.

    */
@@ -214,7 +324,9 @@ abstract class String implements Comparable<String>, Pattern {
 
   /**
    * Returns a new string where the first occurence of [from] in this string

[mem, 2013/09/05 23:09:09]

where -> in which

[shailentuli, 2013/09/23 11:50:27]

Done.

-   * is replaced with [to].
+   * is replaced with [to]. For example:
+   *
+   *     '0.0001'.replaceFirst(new RegExp(r'0+'), ''); // '.0001'
    */
   String replaceFirst(Pattern from, String to);
 
@@ -225,6 +337,8 @@ abstract class String implements Comparable<String>, Pattern {
    * [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
    * by the literal string [replace].
    *
+   *     'resume'.replaceAll(new RegExp(r'e'), '\u00E9'); // '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.
@@ -241,15 +355,17 @@ abstract class String implements Comparable<String>, Pattern {
    * 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 some text to 'pig latin'

[mem, 2013/09/05 23:09:09]

some text -> a string

[shailentuli, 2013/09/23 11:50:27]

Done.

+   * using [replaceAllMapped]:
+   *
    *     pigLatin(String words) => words.replaceAllMapped(
    *         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));
 
@@ -258,22 +374,30 @@ abstract class String implements Comparable<String>, Pattern {
    * 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:
+   * boundaries and not at rune boundaries:
+   *
+   *     var string = 'Pub';
+   *     string.split('');                       // ['P', 'u', 'b']
+   *
+   *     string.codeUnits.map((unit) {
+   *       return new String.fromCharCode(unit);
+   *     }).toList();                            // ['P', 'u', 'b']
    *
-   *     string.split("")
-   *     string.codeUnits.map((unit) => new String.fromCharCode(unit))
+   *     // String made up of two code units, but one rune.
+   *     string = "\u{1D11E}";
+   *     string.split('').length;                 // 2
    *
    * Unless it guaranteed that the string is in the basic multilingual plane

[mem, 2013/09/05 23:09:09]

what is "it" here?

I'm not sure what this is saying...is this right?

You should [map] the runes if the string is not in the basic multilingual plane.

[shailentuli, 2013/09/23 11:50:27]

Using some of your's and some of Florian's language.

    * (meaning that each code unit represents a rune) it is often better to
    * map the runes instead:
    *
-   *     string.runes.map((rune) => new String.fromCharCode(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 on the [pattern], then converts each matched and

[mem, 2013/09/05 23:09:09]

on -> at

[shailentuli, 2013/09/23 11:50:27]

Done.

+   * unmatched part.

[mem, 2013/09/05 23:09:09]

converts it to what?

[mem, 2013/09/05 23:09:09]

How about this:

Splits the string based on [pattern], converts both the matched and unmatched
parts, and rejoins the parts into a new string.

[shailentuli, 2013/09/23 11:50:27]

Done.

    *
    * The pattern is used to split the string into parts and separating matches.
    *
@@ -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).toLowerCase()}*',
+   *         onNonMatch: (n) => n.toUpperCase()); // 'EATS *shoots* LEAVES'
    */
   String splitMapJoin(Pattern pattern,
                       {String onMatch(Match match),
@@ -297,7 +425,7 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * Returns an iterable of Unicode code-points of this string.

[mem, 2013/09/05 23:09:09]

iterable -> [Iterable]

[shailentuli, 2013/09/23 11:50:27]

Done.

    *
-   * 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.
    */
@@ -306,6 +434,9 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * If this string is not already all lower case, returns a new string

[mem, 2013/09/05 23:09:09]

Put the verb first....

Converts all characters in this string to lower case.

If the string is already in all lower case, this method returns this.

[shailentuli, 2013/09/23 11:50:27]

Done.

    * where all characters are made lower case. Returns [:this:] otherwise.
+   *
+   *     'ALPHABET'.toLowerCase(); // 'alphabet'
+   *     'abc'.toLowerCase();      // 'abc'
    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toLowerCase();
@@ -313,6 +444,9 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * If this string is not already all upper case, returns a new string

[mem, 2013/09/05 23:09:09]

same as toLowerCase.

[shailentuli, 2013/09/23 11:50:27]

Done.

    * where all characters are made upper case. Returns [:this:] otherwise.
+   *
+   *     'alphabet'.toUpperCase(); // 'ALPHABET'
+   *     'ABC'.toUpperCase();      // 'ABC'
    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toUpperCase();