Backport changes to RuneIterator to non-NNBD SDK.

Change-Id: I02087a794cd731348f00e34eee8b154f80fe4c9a
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/135316
Commit-Queue: Leaf Petersen <leafp@google.com>
Reviewed-by: Bob Nystrom <rnystrom@google.com>

sdk/lib/core/string.dart

@@ -670,9 +670,10 @@ int _combineSurrogatePair(int start, int end) {
   return 0x10000 + ((start & 0x3FF) << 10) + (end & 0x3FF);
 }
 
-/** [Iterator] for reading runes (integer Unicode code points) out of a Dart
-  * string.
-  */
+/**
+ * [Iterator] for reading runes (integer Unicode code points) out of a Dart
+ * string.
+ */
 class RuneIterator implements BidirectionalIterator<int> {
   /** String being iterated. */
   final String string;
@@ -683,10 +684,10 @@ class RuneIterator implements BidirectionalIterator<int> {
   /**
    * Current code point.
    *
-   * If the iterator has hit either end, the [_currentCodePoint] is null
+   * If the iterator has hit either end, the [_currentCodePoint] is -1
    * and [: _position == _nextPosition :].
    */
-  int _currentCodePoint;
+  int _currentCodePoint = -1;
 
   /** Create an iterator positioned at the beginning of the string. */
   RuneIterator(String string)
@@ -725,9 +726,9 @@ class RuneIterator implements BidirectionalIterator<int> {
   /**
    * Returns the starting position of the current rune in the string.
    *
-   * Returns null if the [current] rune is null.
+   * Returns -1 if there is no current rune ([current] is -1).
    */
-  int get rawIndex => (_position != _nextPosition) ? _position : null;
+  int get rawIndex => (_position != _nextPosition) ? _position : -1;
 
   /**
    * Resets the iterator to the rune at the specified index of the string.
@@ -758,18 +759,21 @@ class RuneIterator implements BidirectionalIterator<int> {
     RangeError.checkValueInInterval(rawIndex, 0, string.length, "rawIndex");
     _checkSplitSurrogate(rawIndex);
     _position = _nextPosition = rawIndex;
-    _currentCodePoint = null;
+    _currentCodePoint = -1;
   }
 
-  /** The rune (integer Unicode code point) starting at the current position in
-   *  the string.
+  /**
+   * The rune (integer Unicode code point) starting at the current position in
+   * the string.
+   *
+   * If there is no current rune, the value -1 is used instead.
    */
   int get current => _currentCodePoint;
 
   /**
    * The number of code units comprising the current rune.
    *
-   * Returns zero if there is no current rune ([current] is null).
+   * Returns zero if there is no current rune ([current] is -1).
    */
   int get currentSize => _nextPosition - _position;
 
@@ -777,12 +781,12 @@ class RuneIterator implements BidirectionalIterator<int> {
    * A string containing the current rune.
    *
    * For runes outside the basic multilingual plane, this will be
-   * a String of length 2, containing two code units.
+   * a [String] of length 2, containing two code units.
    *
-   * Returns null if [current] is null.
+   * Returns an empty string if there is no current rune ([current] is -1).
    */
   String get currentAsString {
-    if (_position == _nextPosition) return null;
+    if (_position == _nextPosition) return "";
     if (_position + 1 == _nextPosition) return string[_position];
     return string.substring(_position, _nextPosition);
   }
@@ -790,7 +794,7 @@ class RuneIterator implements BidirectionalIterator<int> {
   bool moveNext() {
     _position = _nextPosition;
     if (_position == string.length) {
-      _currentCodePoint = null;
+      _currentCodePoint = -1;
       return false;
     }
     int codeUnit = string.codeUnitAt(_position);
@@ -811,7 +815,7 @@ class RuneIterator implements BidirectionalIterator<int> {
   bool movePrevious() {
     _nextPosition = _position;
     if (_position == 0) {
-      _currentCodePoint = null;
+      _currentCodePoint = -1;
       return false;
     }
     int position = _position - 1;

sdk_nnbd/lib/core/string.dart

@@ -299,7 +299,8 @@ abstract class String implements Comparable<String>, Pattern {
    *
    *     string.lastIndexOf(new RegExp(r'DART'));    // -1
    *
-   * The [start] must be non-negative and not greater than [length].
+   * If [start] is omitted, search starts from the end of the string.
+   * If supplied, [start] must be non-negative and not greater than [length].
    */
   int lastIndexOf(Pattern pattern, [int? start]);
 
@@ -607,7 +608,7 @@ abstract class String implements Comparable<String>, Pattern {
 
   /**
    * Converts all characters in this string to lower case.
-   * If the string is already in all lower case, this method returns [:this:].
+   * If the string is already in all lower case, this method returns `this`.
    *
    *     'ALPHABET'.toLowerCase(); // 'alphabet'
    *     'abc'.toLowerCase();      // 'abc'
@@ -620,7 +621,7 @@ abstract class String implements Comparable<String>, Pattern {
 
   /**
    * Converts all characters in this string to upper case.
-   * If the string is already in all upper case, this method returns [:this:].
+   * If the string is already in all upper case, this method returns `this`.
    *
    *     'alphabet'.toUpperCase(); // 'ALPHABET'
    *     'ABC'.toUpperCase();      // 'ABC'
@@ -682,7 +683,7 @@ class RuneIterator implements BidirectionalIterator<int> {
    * Current code point.
    *
    * If the iterator has hit either end, the [_currentCodePoint] is -1
-   * and [: _position == _nextPosition :].
+   * and `_position == _nextPosition`.
    */
   int _currentCodePoint = -1;
 
@@ -721,9 +722,9 @@ class RuneIterator implements BidirectionalIterator<int> {
   }
 
   /**
-   * Returns the starting position of the current rune in the string.
+   * The starting position of the current rune in the string.
    *
-   * Returns -1 if the [current] rune is `null`.
+   * Returns -1 if there is no current rune ([current] is -1).
    */
   int get rawIndex => (_position != _nextPosition) ? _position : -1;
 
@@ -734,8 +735,8 @@ class RuneIterator implements BidirectionalIterator<int> {
    * `string.length`, is an error. So is setting it in the middle of a surrogate
    *  pair.
    *
-   * Setting the position to the end of then string will set [current] to
-   * `null`.
+   * Setting the position to the end of then string means that there is no
+   * current rune.
    */
   void set rawIndex(int rawIndex) {
     RangeError.checkValidIndex(rawIndex, string, "rawIndex");
@@ -750,8 +751,9 @@ class RuneIterator implements BidirectionalIterator<int> {
    * You must call [moveNext] make the rune at the position current,
    * or [movePrevious] for the last rune before the position.
    *
-   * Setting a negative [rawIndex], or one greater than [:string.length:],
-   * is an error. So is setting it in the middle of a surrogate pair.
+   * The [rawIndex] must be non-negative and no greater than `string.length`.
+   * It must also not be the index of the trailing surrogate of a surrogate
+   * pair.
    */
   void reset([int rawIndex = 0]) {
     RangeError.checkValueInInterval(rawIndex, 0, string.length, "rawIndex");
@@ -771,7 +773,7 @@ class RuneIterator implements BidirectionalIterator<int> {
   /**
    * The number of code units comprising the current rune.
    *
-   * Returns zero if there is no current rune ([current] is null).
+   * Returns zero if there is no current rune ([current] is -1).
    */
   int get currentSize => _nextPosition - _position;
 

tests/corelib_2/string_runes_test.dart

@@ -41,16 +41,16 @@ main() {
 
     // Reset, moveNext.
     it.reset(1);
-    Expect.equals(null, it.rawIndex);
-    Expect.equals(null, it.current);
+    Expect.equals(-1, it.rawIndex);
+    Expect.equals(-1, it.current);
     it.moveNext();
     Expect.equals(1, it.rawIndex);
     Expect.equals(expectedRunes[1], it.current);
 
     // Reset, movePrevious.
     it.reset(1);
-    Expect.equals(null, it.rawIndex);
-    Expect.equals(null, it.current);
+    Expect.equals(-1, it.rawIndex);
+    Expect.equals(-1, it.current);
     it.movePrevious();
     Expect.equals(0, it.rawIndex);
     Expect.equals(expectedRunes[0], it.current);