Deprecate the use of runes in SourceFile. (#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.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0176b9f..68eafaa 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/lib/src/file.dart b/lib/src/file.dart
index 1d39cf1..0217c2d 100644
--- a/lib/src/file.dart
+++ b/lib/src/file.dart
@@ -49,15 +49,28 @@
/// 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()) {
diff --git a/pubspec.yaml b/pubspec.yaml
index 70f4e10..46e3d52 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: source_span
-version: 1.3.1
+version: 1.4.0
author: Dart Team <misc@dartlang.org>
description: A library for identifying source spans and locations.
homepage: https://github.com/dart-lang/source_span
