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..0aac5eaa3f108f38ca99d6994427bd452d4614d5 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -7,43 +7,115 @@ part of dart.core;
 /**
  * A class for working with a sequence of characters.
  *
+ * A string can be either single or multiline. Single line strings are

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

"A string literal can be either single- or multiline." (or how do you abbreviate
"single-line or multi-line").

This talks about string *literals*. String objects do not have the notion of
single-line or multi-line, nor do they have any quoting.

String interpolations are string literals, but they do not represent a single
string. Rather they are expressions that evaluate to strings, just as  "foo" + x
+ "bar" .

+ * written using matching single or double quotes, and mutliline strings are

[floitsch, 2013/09/23 15:12:26]

multiline

+ * written using triple quotes. The following are all valid Dart strings:

[floitsch, 2013/09/23 15:12:26]

If you introduce multiline strings here, you should probably already mention
their peculiarity (that the remove a leading new line).

+ *
+ *     'Single quotes';
+ *     "Double quotes";
+ *     'Double quotes in "single" quotes';
+ *     "Single quotes in 'double' quotes";
+ *
+ *     '''A
+ *     multiline
+ *     string''';
+ *
+ *     """
+ *     Another
+ *     multiline
+ *     string""";

[Lasse Reichstein Nielsen, 2013/09/24 10:31:47]

Wrt. a recent mailing list thread, we should document that the last string
literal here does not start with a newline.

[floitsch, 2013/09/24 10:39:00]

See my comment at line 12.

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

[floitsch, 2013/09/23 15:12:26]

To me "operations on strings and assign the result to new strings" sounds more
natural.

+ *
+ *     var string = 'Dart is fun';
+ *     var newString = string.toUpperCase();

[floitsch, 2013/09/23 15:12:26]

Please don't use "toUpperCase" in the leading intro to Strings. If I could I
would remove it from strings entirely...

(yes. this is a personal pet peeve).

+ *
+ * You can use the plus (`+`) operator to concatenate strings:
+ *
+ *     'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'
+ *
+ * You can also use adjacent string literals for concatenation:
+ *
+ *     'Dart ' 'is ' 'fun!';    // 'Dart is fun!'

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

This makes it sound like the plus operator is the same as string juxtaposition.


I'd rather group the plus operator with string interpolations.
Something like:
 
 You can split a string literal into adjacent literal parts:
     'Dart ' 'is ' 'fun!' == 'Dart is fun!'
 
 You can dynamically create strings with varying content using
 `${expression}` to put the string representation of `expression`
 into a string.
     string = 'dartlang';
     '$string has ${string.length} letters';  // 'dartlang has 8 letters'
 The value of the expression is automatically converted to a String by callings
its `toString` method.
  
 You can also concatenate strings (and only strings) using the '+' operator:
     string = 'dartlang';
     string + 'has ' + string.length.toString() + 'letters';
 There is no automatic conversion, and the operands need to both be
 strings.
 

+ *
+ * You can use `${}` to interpolate the value of Dart expressions
+ * within strings. The curly braces can be omitted when evaluating identifiers:

[floitsch, 2013/09/23 15:12:26]

nit. (but no need to change the documentation): this is only true as long as the
identifier does not contain a "$".

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

[floitsch, 2013/09/23 15:12:26]

That example would be more interesting if it was actually different than the
codeunits.
Maybe make the original string "Dart \u{100d8}".
(the Dart unicode character
http://www.fileformat.info/info/unicode/char/100d8/index.htm)

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

[floitsch, 2013/09/23 15:12:26]

If you talk about runes here, no need to have the example above. It only becomes
clear after the explanation.

  *
- * 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.
+ * Extending or implementing String is a compile-time error.

[floitsch, 2013/09/23 15:12:26]

nit: this was already muddy before, but now that it's not the class that does
the implementing or extending we can't say that the action itself is a
compile-time error.

maybe.
"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 ITF-16 code unit, the new

[floitsch, 2013/09/23 15:12:26]

UTF

+   * 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.
+   * You should avoid creating a String with half of a surrogate pair.

[floitsch, 2013/09/23 15:12:26]

That doesn't feel like what I wanted to say.
Let's just write: "It is legal to create a String with only half of a surrogate
pair". (and I'm willing to negotiate on the "only").

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

I'd like to avoid the "It is". Also, why would you want to do this? It seems
like something you'd accidentally do, instead of intentionally.

How about something like:

Creating a String...pair is legal but generally discouraged.

On 2013/09/23 15:12:26, floitsch wrote:

    */
   factory String.fromCharCode(int charCode) {
     List<int> charCodes = new List<int>.filled(1, charCode);
@@ -53,22 +125,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:

[floitsch, 2013/09/23 15:12:26]

... UTF-16 string, but valid Dart string:

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

... but not a valid Dart String literal: "\uD800" is still a compile time error.

[floitsch, 2013/09/24 09:32:40]

Fwiw: we should change that. I filed http://dartbug.com/13535

+   *
+   *     var clef = '\u{1D11E}';
+   *     // These represent invalid UTF-16 strings.

[floitsch, 2013/09/23 15:12:26]

What are "these" ?
clef[0].codeUnits is not a string.

+   *     clef[0].codeUnits;      // [0xD834]
+   *     clef[1].codeUnits;      // [0xDD1E]
    *
    * This method is equivalent to
    * `new String.fromCharCode(this.codeUnitAt(index))`.
@@ -84,8 +148,15 @@ 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). For example:

[floitsch, 2013/09/23 15:12:26]

At some other place you removed the "Example" part.

I'm ok with keeping the "For example", though.

+   *
+   *     'Dart'.length;          // 4
+   *     'Dart'.runes.length;    // 4
+   *
+   *     var clef = '\u{1D11E}';
+   *     clef.length;            // 2
+   *     clef.runes.length;      // 1
    */
   int get length;
 
@@ -93,57 +164,79 @@ abstract class String implements Comparable<String>, Pattern {
    * Returns whether the two strings are equal.
    *
    * This method compares each individual code unit of the strings.
-   * Equivalently (for strings that are well-formed UTF-16) it compares each
+   * For strings that are well-formed UTF-16, it compares each

[floitsch, 2013/09/23 15:12:26]

This sentence now makes even less sense than before.
The "Equivalently" could have been "Consequently", but now the sentence almost
gives a new meaning (first "code unit", then "rune").

I vote for removal.

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

[floitsch, 2013/09/23 15:12:26]

ditto. At some other place you removed the "Example" introduction.

+   *
+   *     '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
+   * An error occurs if [index] is negative or greater than [length].

[floitsch, 2013/09/23 15:12:26]

As said in other CLs. We don't like "An error occurs". Either keep the "It is an
error", or write "[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. 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,
-   * starting at [start] (inclusive).
+   * Returns the position of the first match of [pattern] in this string,
+   * starting at [start] (inclusive). For example:

[floitsch, 2013/09/23 15:12:26]

ditto ("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 no match is found:
+   *
+   *     string.indexOf(new RegExp(r'dart'));       // -1
+   *
+   * An error occurs if [start] is negative or greater than [length].

[floitsch, 2013/09/23 15:12:26]

ditto ("An error occurs").

    */
   int indexOf(Pattern pattern, [int start]);
 
   /**
-   * Returns the last position of a match [pattern] in this string, searching
+   * 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
+   *
+   * In error occurs if start is negative or greater than [length].

[floitsch, 2013/09/23 15:12:26]

ditto. And "An error" not "In error".

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

But do rewrite to "It is an error if [start] is negative or greater than
[length]."

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

[floitsch, 2013/09/23 15:12:26]

Should also reference the StringBuffer class.

    *
-   *     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.
-   * [startIndex] is inclusive and [endIndex] is exclusive.
+   * Returns the substring of this string that extends from [startIndex]
+   * (inclusive) to [endIndex] (exclusive).

[floitsch, 2013/09/23 15:12:26]

"[startIndex](inclusive)" is valid markdown but won't do, what you thought it
would do(just look at the generated output).

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

[floitsch, 2013/09/23 15:12:26]

The correct example would verify that the returned value is identical.

+   *
+   *     '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,18 +307,27 @@ 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
+   *
+   * An error occurs if [startIndex] is negative or greater than [length].

[floitsch, 2013/09/23 15:12:26]

ditto ("An error occurs").

    */
   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]. For example:

[floitsch, 2013/09/23 15:12:26]

ditto ("for example").

+   *
+   *     '0.0001'.replaceFirst(new RegExp(r'0+'), ''); // '.0001'

[floitsch, 2013/09/23 15:12:26]

bad example.
Why the "0+" (and not just "0") ? What's the purpose?

    */
   String replaceFirst(Pattern from, String to);
 
@@ -225,6 +338,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é'

[floitsch, 2013/09/23 15:12:26]

no need for the \u. Just put "é" there.

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

Unless it is to distinguish it from "e\u0301" that we pointed out above?

+   *
    * 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 +356,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 a string to 'pig latin'

[floitsch, 2013/09/23 15:12:26]

to simplified 'pig latin' ... ?

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

Better say "simplified" since real pig-latin is based on vowel-sounds, not pure
syntax (e.g., "y" being a vowel in some cases).

+   * 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));
 
@@ -257,23 +374,35 @@ abstract class String implements Comparable<String>, Pattern {
    * Splits the string around 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:

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

Useful as example because it is a common case, but it's not really a property of
String.split, but of the empty string's behavior as a Pattern. Could it be
emphasized that this is an example, not a specification of split?

    *
-   *     string.split("")
-   *     string.codeUnits.map((unit) => new String.fromCharCode(unit))
+   *     var string = 'Pub';
+   *     string.split('');                       // ['P', 'u', 'b']
    *
-   * Unless it guaranteed that the string is in the basic multilingual plane
+   *     string.codeUnits.map((unit) {
+   *       return new String.fromCharCode(unit);
+   *     }).toList();                            // ['P', 'u', 'b']
+   *
+   *     // String made up of two code units, but one rune.
+   *     string = '\u{1D11E}';
+   *     string.split('').length;                 // 2

[Lasse Reichstein Nielsen, 2013/09/24 08:17:32]

We could define a RunePattern that would always match all of a surrogate pair,
or none of it. Using such a  const RunePattern('') as argument would not split
the string. I.e., it's ''.allMatches behavior, not String.split behavior we are
describing here.

+   *
+   * Unless it is 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.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

[floitsch, 2013/09/23 15:12:26]

I guess you wanted to remove the old paragraph.

+   * 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 based on [pattern], converts both the matched and

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

This is a pretty long description. How about just:

Splits the string, converts its parts, and combines them into a new string.

+   * unmatched parts, and rejoins the parts into a new string.
    *
    * The pattern is used to split the string into parts and separating matches.

[floitsch, 2013/09/23 15:12:26]

[pattern]

    *
@@ -284,6 +413,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()}*',

[floitsch, 2013/09/23 15:12:26]

please don't use toLowerCase/toUpperCase in examples that work with language. It
won't do the right thing in other languages.

+   *         onNonMatch: (n) => n.toUpperCase()); // 'EATS *shoots* LEAVES'
    */
   String splitMapJoin(Pattern pattern,
                       {String onMatch(Match match),
@@ -295,24 +428,30 @@ 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.
+   * If the string is already in all lower case, this method returns [:this:].
+   *
+   *     'ALPHABET'.toLowerCase(); // 'alphabet'
+   *     'abc'.toLowerCase();      // 'abc'

[floitsch, 2013/09/23 15:12:26]

Please add documentation that this function uses the language independent
Unicode mapping and thus only works in very few languages.

You can add the example of dotless I. In Turky "I".toLowerCase() should not be
"i".

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

[floitsch, 2013/09/23 15:12:26]

ditto.
"i".toUpperCase should be "İ" in Turkey.

http://en.wikipedia.org/wiki/Dotted_and_dotless_I

    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toUpperCase();
@@ -329,7 +468,7 @@ class Runes extends IterableBase<int> {
 
   int get last {
     if (string.length == 0) {
-      throw new StateError("No elements.");
+      throw new StateError('No elements.');

[floitsch, 2013/09/23 15:12:26]

why?

(not that I care).

     }
     int length = string.length;
     int code = string.codeUnitAt(length - 1);
@@ -401,7 +540,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');
     }
   }