Deprecate the use of runes in SourceFile. (flutter#16)

This behavior runs contrary to the rest of Dart's string handling, and
in particular breaks string_scanner. See dart-lang/string_scanner#4.

Author: nex3

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 1.4.0
+
+* The `new SourceFile()` constructor is deprecated. This constructed a source
+  file from a string's runes, rather than its code units, which runs counter to
+  the way Dart handles strings otherwise. The `new StringFile.fromString()`
+  constructor (see below) should be used instead.
+
+* The `new SourceFile.fromString()` constructor was added. This works like `new
+  SourceFile()`, except it uses code units rather than runes.
+
+* The current behavior when characters larger than `0xFFFF` are passed to `new
+  SourceFile.decoded()` is now considered deprecated.
+
 # 1.3.1
 
 * Properly highlight spans for lines that include tabs with

lib/src/file.dart

@@ -49,15 +49,28 @@ class SourceFile {
   /// previous result.
   int _cachedLine;
 
-  /// Creates a new source file from [text].
+  /// This constructor is deprecated.
   ///
-  /// [url] may be either a [String], a [Uri], or `null`.
+  /// Use [new SourceFile.fromString] instead.
+  @Deprecated("Will be removed in 2.0.0")
   SourceFile(String text, {url})
       : this.decoded(text.runes, url: url);
 
-  /// Creates a new source file from a list of decoded characters.
+  /// Creates a new source file from [text].
   ///
   /// [url] may be either a [String], a [Uri], or `null`.
+  SourceFile.fromString(String text, {url})
+      : this.decoded(text.codeUnits, url: url);
+
+  /// Creates a new source file from a list of decoded code units.
+  ///
+  /// [url] may be either a [String], a [Uri], or `null`.
+  ///
+  /// Currently, if [decodedChars] contains characters larger than `0xFFFF`,
+  /// they'll be treated as single characters rather than being split into
+  /// surrogate pairs. **This behavior is deprecated**. For
+  /// forwards-compatibility, callers should only pass in characters less than
+  /// or equal to `0xFFFF`.
   SourceFile.decoded(Iterable<int> decodedChars, {url})
       : url = url is String ? Uri.parse(url) : url,
         _decodedChars = new Uint32List.fromList(decodedChars.toList()) {

pubspec.yaml

@@ -1,5 +1,5 @@
 name: source_span
-version: 1.3.1
+version: 1.4.0
 author: Dart Team <[email protected]>
 description: A library for identifying source spans and locations.
 homepage: https://github.com/dart-lang/source_span