Added examples to String docs.

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 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:
  *
- * Strings are immutable.
+ *     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)

  *
- * It is a compile-time error for a class to attempt to extend or implement
- * String.
+ * 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.

  *
- * For concatenating strings efficiently, use the [StringBuffer] class. For
- * working with regular expressions, use the [RegExp] class.
+ *     var clef = '\u{1D11E}';
+ *     clef.codeUnits;         // [0xD834, 0xDD1E]
+ *     clef.runes.toList();    // [0x1D11E]
+ *
+ * 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."

+ *
+ * ## 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);
     return new String.fromCharCodes(charCodes);
   }
 
   /**
    * 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:

[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}";
-   *     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.
+   *     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))`.
    */
   String operator [](int index);
 
   /**
    * Returns the 16-bit UTF-16 code unit at the given [index].
    */
   int codeUnitAt(int index);
 
   /**
    * 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;
 
   /**
    * 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].
    *
-   * 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
    *
-   * It is an error if [index] is negative or greater than [length].
+   * If [index] is provided, this method checks if the substring starting
+   * at that index starts with a match of [pattern]:
    *
-   * A [RegExp] containing "^" will not match if the [index] is greater than
+   *     string.startsWith('art', 1);                  // true
+   *     string.startsWith(new RegExp(r'\w{3}'));      // true
+   *
+   * 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]);
 
   /**
    * Returns whether this string is empty.
    */
   bool get isEmpty;
 
   /**
    * Returns whether 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]:
+   *     'dart' + 'lang'; // 'dartlang'
    *
-   *     var strings = ['foo', 'bar', 'geez'];
-   *     var concatenated = strings.join();
+   * Use [Iterable.join] to concatenate a sequence of strings:

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

Should also reference the StringBuffer class.

+   *
+   *     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.
    *
    * Here is the list of trimmed characters (following version 6.2):
    *
    *     0009..000D    ; White_Space # Cc   <control-0009>..<control-000D>
    *     0020          ; White_Space # Zs   SPACE
    *     0085          ; White_Space # Cc   <control-0085>
    *     00A0          ; White_Space # Zs   NO-BREAK SPACE
    *     1680          ; White_Space # Zs   OGHAM SPACE MARK
    *     180E          ; White_Space # Zs   MONGOLIAN VOWEL SEPARATOR
    *     2000..200A    ; White_Space # Zs   EN QUAD..HAIR SPACE
    *     2028          ; White_Space # Zl   LINE SEPARATOR
    *     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();
 
   /**
-   * 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);
 
   /**
    * Replaces all substrings matching [from] with [replace].
    *
    * Returns a new string where the non-overlapping substrings that match
    * [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.
    */
   String replaceAll(Pattern from, String replace);
 
   /**
    * Replace all substrings matching [from] by a string computed from the match.
    *
    * Returns a new string where 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 '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));
 
   /**
    * 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]

    *
    * Each match is converted to a string by calling [onMatch]. If [onMatch]
    * is omitted, the matched string is used.
    *
    * Each non-matched part is converted by a call to [onNonMatch]. If
    * [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),
                        String onNonMatch(String nonMatch)});
 
   /**
    * Returns an unmodifiable list of the UTF-16 code units of this string.
    */
   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();
 }
 
 /**
  * The runes (integer Unicode code points) of a [String].
  */
 class Runes extends IterableBase<int> {
   final String string;
   Runes(this.string);
 
   RuneIterator get iterator => new RuneIterator(string);
 
   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);
     if (_isTrailSurrogate(code) && string.length > 1) {
       int previousCode = string.codeUnitAt(length - 2);
       if (_isLeadSurrogate(previousCode)) {
         return _combineSurrogatePair(previousCode, code);
       }
     }
     return code;
@@ skipping 51 matching lines @@
       throw new RangeError.range(index, 0, string.length);
     }
     _checkSplitSurrogate(index);
   }
 
   /** Throw an error if the index is in the middle of a surrogate pair. */
   void _checkSplitSurrogate(int index) {
     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');
     }
   }
 
   /**
    * Returns the starting position of the current rune in the string.
    *
    * Returns null if the [current] rune is null.
    */
   int get rawIndex => (_position != _nextPosition) ? _position : null;
 
@@ skipping 94 matching lines @@
         _position = position - 1;
         _currentCodePoint = _combineSurrogatePair(prevCodeUnit, codeUnit);
         return true;
       }
     }
     _position = position;
     _currentCodePoint = codeUnit;
     return true;
   }
 }