Clarify some documentation around runes, aka code points

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;
 
 /**
  * The String class represents sequences of characters. Strings are
  * immutable. A string is represented by a sequence of Unicode UTF-16
  * code units accessible through the [codeUnitAt] or the
@@ skipping 25 matching lines @@
    *
    * It is allowed (though generally discouraged) to create a String with only
    * one half of a surrogate pair.
    */
   factory String.fromCharCode(int charCode) {
     List<int> charCodes = new List<int>.filled(1, charCode);
     return new String.fromCharCodes(charCodes);
   }
 
   /**
-   * Gets the character (as [String]) at the given [index].
+   * 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
@@ skipping 20 matching lines @@
    *
    * 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).
    */
   int get length;
 
   /**
    * Returns whether the two strings are equal.
    *
-   * This method compares each individual code unit of the strings. 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.
+   * 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.
    *
    *     "Am\xe9lie"
    *     "Ame\u{301}lie"
    *
-   * In the first string the "é" is encoded as a single unicode code unit,
-   * whereas the second string encodes it as "e" with the combining
-   * accent character "◌́".
+   * 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 "◌́".
    */
   bool operator ==(var other);
 
   /**
    * Returns whether this string ends with [other].
    */
   bool endsWith(String other);
 
   /**
    * Returns whether this string starts with [other].
@@ skipping 149 matching lines @@
 
   /**
    * If this string is not already all upper case, returns a new string
    * where all characters are made upper case. Returns [:this:] otherwise.
    */
   // TODO(floitsch): document better. (See EcmaScript for description).
   String toUpperCase();
 }
 
 /**
- * The runes of a [String].
+ * The runes (21 bit integer Unicode code points) of a [String].
  */
 class Runes extends Iterable<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.");
@@ skipping 15 matching lines @@
 bool _isLeadSurrogate(int code) => (code & 0xFC00) == 0xD800;
 
 // Is then code (a 16-bit unsigned integer) a UTF-16 trail surrogate.
 bool _isTrailSurrogate(int code) => (code & 0xFC00) == 0xDC00;
 
 // Combine a lead and a trail surrogate value into a single code point.
 int _combineSurrogatePair(int start, int end) {
   return 0x10000 + ((start & 0x3FF) << 10) + (end & 0x3FF);
 }
 
-/** [Iterator] for reading Unicode code points out of a Dart string. */
+/** [Iterator] for reading runes (21 bit integer Unicode code points) out of a

[Lasse Reichstein Nielsen, 2013/02/28 12:31:21]

You can drop "21 bit integer" if you want, that's redundant when saying "code
points".

+ *  Dart string.
+ */
 class RuneIterator implements BidirectionalIterator<int> {
   /** String being iterated. */
   final String string;
   /** Position before the current code point. */
   int _position;
   /** Position after the current code point. */
   int _nextPosition;
   /**
    * Current code point.
    *
@@ skipping 70 matching lines @@
    */
   void reset([int rawIndex = 0]) {
     if (rawIndex < 0 || rawIndex > string.length) {
       throw new RangeError.range(rawIndex, 0, string.length);
     }
     _checkSplitSurrogate(rawIndex);
     _position = _nextPosition = rawIndex;
     _currentCodePoint = null;
   }
 
-  /** The rune starting at the current position in the string. */
+  /** The rune (21 bit integer Unicode code point) starting at the current

[Lasse Reichstein Nielsen, 2013/02/28 12:31:21]

Again.

+   *  position in the string. */
   int get current => _currentCodePoint;
 
   /**
    * The number of code units comprising the current rune.
    *
    * Returns zero if there is no current rune ([current] is null).
    */
   int get currentSize => _nextPosition - _position;
 
   /**
    * A string containing the current rune.
    *
    * For runes outside the basic multilingual plane, this will be
-   * a two-character String.
+   * a String of length 2, containing two code units.
    *
    * Returns null if [current] is null.
    */
   String get currentAsString {
     if (_position == _nextPosition) return null;
     if (_position + 1 == _nextPosition) return string[_position];
     return string.substring(_position, _nextPosition);
   }
 
   bool moveNext() {
@@ skipping 31 matching lines @@
         _position = position - 1;
         _currentCodePoint = _combineSurrogatePair(prevCodeUnit, codeUnit);
         return true;
       }
     }
     _position = position;
     _currentCodePoint = codeUnit;
     return true;
   }
 }