Scanner for UTF-8 byte arrays

sdk/lib/_internal/compiler/compiler.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.
 
 library compiler;
 
 import 'dart:async';
 import 'implementation/apiimpl.dart';
 
 // Unless explicitly allowed, passing [:null:] for any argument to the
 // methods of library will result in an Error being thrown.
 
 /**
- * Returns a future that completes to the source corresponding to
- * [uri]. If an exception occurs, the future completes with this
- * exception.
+ * Returns a future that completes to the source corresponding to [uri].
+ * If an exception occurs, the future completes with this exception.
+ *
+ * The source can be represented either as a [:List<int>:] of UTF-8 bytes or as
+ * a [String].
+ *
+ * The following text is non-normative:
+ *
+ * It is recommended to return a UTF-8 encoded list of bytes because the scanner
+ * is more efficient in this case. In either case, the data structure is
+ * expected to hold a zero element at the last position. If this is not the
+ * case, the entire data structure is copied before scanning.
  */
-typedef Future<String> CompilerInputProvider(Uri uri);
+typedef Future/*<String | List<int>>*/ CompilerInputProvider(Uri uri);
 
 /// Deprecated, please use [CompilerInputProvider] instead.
 typedef Future<String> ReadStringFromUri(Uri uri);
 
 /**
  * Returns an [EventSink] that will serve as compiler output for the given
  * component.
  *
  * Components are identified by [name] and [extension]. By convention,
  * the empty string [:"":] will represent the main script
@@ skipping 145 matching lines @@
   final String name;
 
   /**
    * This constructor is not private to support user-defined
    * diagnostic kinds.
    */
   const Diagnostic(this.ordinal, this.name);
 
   String toString() => name;
 }