Add optional offset argument to StringScanner.peekCodePoint()

CHANGELOG.md

@@ -1,6 +1,8 @@
-## 1.2.1-wip
+## 1.3.0-wip
 
 * Require Dart 3.0.0
+* `StringScanner.peekCodePoint()` now accepts an optional `offset` argument like
+  `StringScanner.peekChar()`. 
 
 ## 1.2.0
 

lib/src/string_scanner.dart

@@ -158,19 +158,23 @@ class StringScanner {
     return decodeSurrogatePair(first, next);
   }
 
-  /// Returns the Unicode code point immediately after [position].
+  /// Returns the Unicode code point [offset] away from [position].
   ///
   /// This works like [peekChar], except that it automatically handles UTF-16
   /// surrogate pairs. Specifically, if the next two code units form a surrogate
   /// pair, returns the corresponding Unicode code point.
   ///
+  /// [offset] defaults to zero, and may be negative to inspect already-consumed
+  /// characters.
+  ///
   /// If next two characters are not a surrogate pair, the next code unit is
   /// returned as-is, even if it's an unpaired surrogate.
-  int? peekCodePoint() {
-    final first = peekChar();
+  int? peekCodePoint([int? offset]) {
+    offset ??= 0;
+    final first = peekChar(offset);
     if (first == null || !isHighSurrogate(first)) return first;
 
-    final next = peekChar(1);
+    final next = peekChar(offset + 1);
     if (next == null || !isLowSurrogate(next)) return first;
 
     return decodeSurrogatePair(first, next);

pubspec.yaml

@@ -1,5 +1,5 @@
 name: string_scanner
-version: 1.2.1-wip
+version: 1.3.0-wip
 description: A class for parsing strings using a sequence of patterns.
 repository: https://github.com/dart-lang/string_scanner
 

test/string_scanner_test.dart

@@ -154,6 +154,12 @@ void main() {
       expect(scanner.position, equals(0));
     });
 
+    test('peekCodePoint with an argument returns the nth character', () {
+      expect(scanner.peekCodePoint(4), equals(0x62));
+      expect(scanner.lastMatch, isNull);
+      expect(scanner.position, equals(0));
+    });
+
     test('a matching scanChar returns true moves forward', () {
       expect(scanner.scanChar($f), isTrue);
       expect(scanner.lastMatch, isNull);