Version 0.8.10.9

dart/sdk/lib/typed_data/dart2js/typed_data_dart2js.dart

 // Copyright (c) 2013, 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.
 
 /**
  * Specialized integers and floating point numbers,
  * with SIMD support and efficient lists.
  */
 library dart.typed_data;
 
@@ skipping 12 matching lines @@
   static const Endianness BIG_ENDIAN = const Endianness(false);
   static const Endianness LITTLE_ENDIAN = const Endianness(true);
   static final Endianness HOST_ENDIAN =
     (new ByteData.view(new Int16List.fromList([1]).buffer)).getInt8(0) == 1 ?
     LITTLE_ENDIAN : BIG_ENDIAN;
 
   final bool _littleEndian;
 }
 
 
+/**
+ * A sequence of bytes underlying a typed data object.
+ * Used to process large quantities of binary or numerical data
+ * more efficiently using a typed view.
+ */
 class ByteBuffer native "ArrayBuffer" {
   @JSName('byteLength')
   final int lengthInBytes;
 }
 
 // TODO(12929): Remove this constant once V8 optimizes length access of
 // typed arrays. Firefox does not like accessing a named property of a
 // typed array, so we only use the new [:$dartCachedLength:] property in V8 and
 // Chrome.
 const fetchLength = const JS_CONST(r'''
     ((typeof version == "function" && typeof os == "object" && "system" in os)
     || (typeof navigator == "object"
         && navigator.userAgent.indexOf('Chrome') != -1))
         ? function(x) { return x.$dartCachedLength || x.length; }
         : function(x) { return x.length; };
 ''');
 
+/**
+ * A typed view of a sequence of bytes.
+ */
 class TypedData native "ArrayBufferView" {
+  /**
+   * Returns the byte buffer associated with this object.
+   */
   @Creates('ByteBuffer')
   @Returns('ByteBuffer|Null')
   final ByteBuffer buffer;
 
+  /**
+   * Returns the length of this view, in bytes.
+   */
   @JSName('byteLength')
   final int lengthInBytes;
 
+  /**
+   * Returns the offset in bytes into the underlying byte buffer of this view.
+   */
   @JSName('byteOffset')
   final int offsetInBytes;
 
+  /**
+   * Returns the number of bytes in the representation of each element in this
+   * list.
+   */
   @JSName('BYTES_PER_ELEMENT')
   final int elementSizeInBytes;
 
   void _invalidIndex(int index, int length) {
     if (index < 0 || index >= length) {
       throw new RangeError.range(index, 0, length);
     } else {
       throw new ArgumentError('Invalid list index $index');
     }
   }
@@ skipping 24 matching lines @@
 }
 
 
 // Ensures that [list] is a JavaScript Array or a typed array.  If necessary,
 // returns a copy of the list.
 List _ensureNativeList(List list) {
   return list;  // TODO: make sure.
 }
 
 
+/**
+ * A fixed-length, random-access sequence of bytes that also provides random
+ * and unaligned access to the fixed-width integers and floating point
+ * numbers represented by those bytes.
+ * ByteData may be used to pack and unpack data from external sources
+ * (such as networks or files systems), and to process large quantities
+ * of numerical data more efficiently than would be possible
+ * with ordinary [List] implementations. ByteData can save space, by
+ * eliminating the need for object headers, and time, by eliminating the
+ * need for data copies. Finally, ByteData may be used to intentionally
+ * reinterpret the bytes representing one arithmetic type as another.
+ * For example this code fragment determine what 32-bit signed integer
+ * is represented by the bytes of a 32-bit floating point number:
+ *
+ *     var buffer = new Uint8List(8).buffer;
+ *     var bdata = new ByteData.view(buffer);
+ *     bdata.setFloat32(0, 3.04);
+ *     int huh = bdata.getInt32(0);
+ */
 class ByteData extends TypedData native "DataView" {
+  /**
+   * Creates a [ByteData] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory ByteData(int length) => _create1(length);
 
+  /**
+   * Creates an [ByteData] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [ByteData] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   */
   factory ByteData.view(ByteBuffer buffer,
                         [int byteOffset = 0, int byteLength]) =>
       byteLength == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, byteLength);
 
+  /**
+   * Returns the floating point number represented by the four bytes at
+   * the specified [byteOffset] in this object, in IEEE 754
+   * single-precision binary floating-point format (binary32).
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
   num getFloat32(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getFloat32(byteOffset, endian._littleEndian);
 
   @JSName('getFloat32')
   @Returns('num')
   num _getFloat32(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the floating point number represented by the eight bytes at
+   * the specified [byteOffset] in this object, in IEEE 754
+   * double-precision binary floating-point format (binary64).
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   num getFloat64(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getFloat64(byteOffset, endian._littleEndian);
 
   @JSName('getFloat64')
   @Returns('num')
   num _getFloat64(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the (possibly negative) integer represented by the two bytes at
+   * the specified [byteOffset] in this object, in two's complement binary
+   * form.
+   * The return value will be between 2<sup>15</sup> and 2<sup>15</sup> - 1,
+   * inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
   int getInt16(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getInt16(byteOffset, endian._littleEndian);
 
   @JSName('getInt16')
   @Returns('int')
   int _getInt16(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the (possibly negative) integer represented by the four bytes at
+   * the specified [byteOffset] in this object, in two's complement binary
+   * form.
+   * The return value will be between 2<sup>31</sup> and 2<sup>31</sup> - 1,
+   * inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
   int getInt32(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getInt32(byteOffset, endian._littleEndian);
 
   @JSName('getInt32')
   @Returns('int')
   int _getInt32(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the (possibly negative) integer represented by the eight bytes at
+   * the specified [byteOffset] in this object, in two's complement binary
+   * form.
+   * The return value will be between 2<sup>63</sup> and 2<sup>63</sup> - 1,
+   * inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   int getInt64(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) {
     throw new UnsupportedError("Int64 accessor not supported by dart2js.");
   }
 
+  /**
+   * Returns the (possibly negative) integer represented by the byte at the
+   * specified [byteOffset] in this object, in two's complement binary
+   * representation. The return value will be between -128 and 127, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * greater than or equal to the length of this object.
+   */
   int getInt8(int byteOffset) native;
 
+  /**
+   * Returns the positive integer represented by the two bytes starting
+   * at the specified [byteOffset] in this object, in unsigned binary
+   * form.
+   * The return value will be between 0 and  2<sup>16</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
   int getUint16(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getUint16(byteOffset, endian._littleEndian);
 
   @JSName('getUint16')
   @Returns('int')
   int _getUint16(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the positive integer represented by the four bytes starting
+   * at the specified [byteOffset] in this object, in unsigned binary
+   * form.
+   * The return value will be between 0 and  2<sup>32</sup> - 1, inclusive.
+   *
+   */
   int getUint32(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _getUint32(byteOffset, endian._littleEndian);
 
   @JSName('getUint32')
   @Returns('int')
   int _getUint32(int byteOffset, [bool littleEndian]) native;
 
+  /**
+   * Returns the positive integer represented by the eight bytes starting
+   * at the specified [byteOffset] in this object, in unsigned binary
+   * form.
+   * The return value will be between 0 and  2<sup>64</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   int getUint64(int byteOffset, [Endianness endian=Endianness.BIG_ENDIAN]) {
     throw new UnsupportedError("Uint64 accessor not supported by dart2js.");
   }
 
+  /**
+   * Returns the positive integer represented by the byte at the specified
+   * [byteOffset] in this object, in unsigned binary form. The
+   * return value will be between 0 and 255, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * greater than or equal to the length of this object.
+   */
   int getUint8(int byteOffset) native;
 
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this
+   * object to the IEEE 754 single-precision binary floating-point
+   * (binary32) representation of the specified [value].
+   *
+   * **Note that this method can lose precision.** The input [value] is
+   * a 64-bit floating point value, which will be converted to 32-bit
+   * floating point value by IEEE 754 rounding rules before it is stored.
+   * If [value] cannot be represented exactly as a binary32, it will be
+   * converted to the nearest binary32 value.  If two binary32 values are
+   * equally close, the one whose least significant bit is zero will be used.
+   * Note that finite (but large) values can be converted to infinity, and
+   * small non-zero values can be converted to zero.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
   void setFloat32(int byteOffset, num value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setFloat32(byteOffset, value, endian._littleEndian);
 
   @JSName('setFloat32')
   void _setFloat32(int byteOffset, num value, [bool littleEndian]) native;
 
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this
+   * object to the IEEE 754 double-precision binary floating-point
+   * (binary64) representation of the specified [value].
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   void setFloat64(int byteOffset, num value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setFloat64(byteOffset, value, endian._littleEndian);
 
   @JSName('setFloat64')
   void _setFloat64(int byteOffset, num value, [bool littleEndian]) native;
 
+  /**
+   * Sets the two bytes starting at the specified [byteOffset] in this
+   * object to the two's complement binary representation of the specified
+   * [value], which must fit in two bytes. In other words, [value] must lie
+   * between 2<sup>15</sup> and 2<sup>15</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
   void setInt16(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setInt16(byteOffset, value, endian._littleEndian);
 
   @JSName('setInt16')
   void _setInt16(int byteOffset, int value, [bool littleEndian]) native;
 
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this
+   * object to the two's complement binary representation of the specified
+   * [value], which must fit in four bytes. In other words, [value] must lie
+   * between 2<sup>31</sup> and 2<sup>31</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
   void setInt32(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setInt32(byteOffset, value, endian._littleEndian);
 
   @JSName('setInt32')
   void _setInt32(int byteOffset, int value, [bool littleEndian]) native;
 
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this
+   * object to the two's complement binary representation of the specified
+   * [value], which must fit in eight bytes. In other words, [value] must lie
+   * between 2<sup>63</sup> and 2<sup>63</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   void setInt64(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) {
     throw new UnsupportedError("Int64 accessor not supported by dart2js.");
   }
 
+  /**
+   * Sets the byte at the specified [byteOffset] in this object to the
+   * two's complement binary representation of the specified [value], which
+   * must fit in a single byte. In other words, [value] must be between
+   * -128 and 127, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * greater than or equal to the length of this object.
+   */
   void setInt8(int byteOffset, int value) native;
 
+  /**
+   * Sets the two bytes starting at the specified [byteOffset] in this object
+   * to the unsigned binary representation of the specified [value],
+   * which must fit in two bytes. in other words, [value] must be between
+   * 0 and 2<sup>16</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
   void setUint16(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setUint16(byteOffset, value, endian._littleEndian);
 
   @JSName('setUint16')
   void _setUint16(int byteOffset, int value, [bool littleEndian]) native;
 
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this object
+   * to the unsigned binary representation of the specified [value],
+   * which must fit in four bytes. in other words, [value] must be between
+   * 0 and 2<sup>32</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
   void setUint32(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) =>
       _setUint32(byteOffset, value, endian._littleEndian);
 
   @JSName('setUint32')
   void _setUint32(int byteOffset, int value, [bool littleEndian]) native;
 
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this object
+   * to the unsigned binary representation of the specified [value],
+   * which must fit in eight bytes. in other words, [value] must be between
+   * 0 and 2<sup>64</sup> - 1, inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
   void setUint64(int byteOffset, int value, [Endianness endian=Endianness.BIG_ENDIAN]) {
     throw new UnsupportedError("Uint64 accessor not supported by dart2js.");
   }
 
+  /**
+   * Sets the byte at the specified [byteOffset] in this object to the
+   * unsigned binary representation of the specified [value], which must fit
+   * in a single byte. in other words, [value] must be between 0 and 255,
+   * inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative,
+   * or greater than or equal to the length of this object.
+   */
   void setUint8(int byteOffset, int value) native;
 
   static ByteData _create1(arg) =>
       JS('ByteData', 'new DataView(new ArrayBuffer(#))', arg).._setCachedLength();
 
   static ByteData _create2(arg1, arg2) =>
       JS('ByteData', 'new DataView(#, #)', arg1, arg2).._setCachedLength();
 
   static ByteData _create3(arg1, arg2, arg3) =>
       JS('ByteData', 'new DataView(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
-
+/**
+ * A fixed-length list of IEEE 754 single-precision binary floating-point
+ * numbers  that is viewable as a [TypedData]. For long lists, this
+ * implementation can be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
 class Float32List
     extends TypedData with ListMixin<double>, FixedLengthListMixin<double>
     implements JavaScriptIndexingBehavior, List<double>
     native "Float32Array" {
+  /**
+   * Creates a [Float32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Float32List(int length) => _create1(length);
 
+  /**
+   * Creates a [Float32List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Float32List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Float32List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Float32List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Float32List.view(ByteBuffer buffer,
                            [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 4;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 20 matching lines @@
   static Float32List _create2(arg1, arg2) =>
       JS('Float32List', 'new Float32Array(#, #)', arg1, arg2)
           .._setCachedLength();
 
   static Float32List _create3(arg1, arg2, arg3) =>
       JS('Float32List', 'new Float32Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of IEEE 754 double-precision binary floating-point
+ * numbers  that is viewable as a [TypedData]. For long lists, this
+ * implementation can be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
 class Float64List
     extends TypedData with ListMixin<double>, FixedLengthListMixin<double>
     implements JavaScriptIndexingBehavior, List<double>
     native "Float64Array" {
+  /**
+   * Creates a [Float64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Float64List(int length) => _create1(length);
 
+  /**
+   * Creates a [Float64List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Float64List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Float64List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Float64List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Float64List.view(ByteBuffer buffer,
                            [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 8;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 23 matching lines @@
         .._setCachedLength();
   }
 
   static Float64List _create3(arg1, arg2, arg3) {
     return JS('Float64List', 'new Float64Array(#, #, #)', arg1, arg2, arg3)
         .._setCachedLength();
   }
 }
 
 
+/**
+ * A fixed-length list of 16-bit signed integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Int16List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     native "Int16Array" {
+  /**
+   * Creates an [Int16List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Int16List(int length) => _create1(length);
 
+  /**
+   * Creates a [Int16List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Int16List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates an [Int16List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Int16List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Int16List.view(ByteBuffer buffer, [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 2;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
   int operator[](int index) {
@@ skipping 18 matching lines @@
 
   static Int16List _create2(arg1, arg2) =>
       JS('Int16List', 'new Int16Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Int16List _create3(arg1, arg2, arg3) =>
       JS('Int16List', 'new Int16Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 32-bit signed integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Int32List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     native "Int32Array" {
+  /**
+   * Creates an [Int32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Int32List(int length) => _create1(length);
 
+  /**
+   * Creates a [Int32List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Int32List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates an [Int32List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Int32List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Int32List.view(ByteBuffer buffer, [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 4;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
   int operator[](int index) {
@@ skipping 18 matching lines @@
 
   static Int32List _create2(arg1, arg2) =>
       JS('Int32List', 'new Int32Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Int32List _create3(arg1, arg2, arg3) =>
       JS('Int32List', 'new Int32Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 8-bit signed integers.
+ * For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Int8List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     native "Int8Array" {
+  /**
+   * Creates an [Int8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Int8List(int length) => _create1(length);
 
+  /**
+   * Creates a [Int8List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Int8List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates an [Int8List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Int8List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   */
   factory Int8List.view(ByteBuffer buffer, [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 1;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
   int operator[](int index) {
@@ skipping 18 matching lines @@
 
   static Int8List _create2(arg1, arg2) =>
       JS('Int8List', 'new Int8Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Int8List _create3(arg1, arg2, arg3) =>
       JS('Int8List', 'new Int8Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 16-bit unsigned integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Uint16List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     native "Uint16Array" {
+  /**
+   * Creates a [Uint16List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   factory Uint16List(int length) => _create1(length);
 
+  /**
+   * Creates a [Uint16List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Uint16List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Uint16List] _view_ of the specified region in
+   * the specified byte buffer. Changes in the [Uint16List] will be
+   * visible in the byte buffer and vice versa. If the [offsetInBytes] index
+   * of the region is not specified, it defaults to zero (the first byte in
+   * the byte buffer). If the length is not specified, it defaults to null,
+   * which indicates that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Uint16List.view(ByteBuffer buffer,
                           [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 2;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 19 matching lines @@
 
   static Uint16List _create2(arg1, arg2) =>
       JS('Uint16List', 'new Uint16Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Uint16List _create3(arg1, arg2, arg3) =>
       JS('Uint16List', 'new Uint16Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 32-bit unsigned integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Uint32List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     native "Uint32Array" {
+  /**
+   * Creates a [Uint32List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   factory Uint32List(int length) => _create1(length);
 
+  /**
+   * Creates a [Uint32List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Uint32List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Uint32List] _view_ of the specified region in
+   * the specified byte buffer. Changes in the [Uint32] will be
+   * visible in the byte buffer and vice versa. If the [offsetInBytes] index
+   * of the region is not specified, it defaults to zero (the first byte in
+   * the byte buffer). If the length is not specified, it defaults to null,
+   * which indicates that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Uint32List.view(ByteBuffer buffer,
                           [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 4;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 19 matching lines @@
 
   static Uint32List _create2(arg1, arg2) =>
       JS('Uint32List', 'new Uint32Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Uint32List _create3(arg1, arg2, arg3) =>
       JS('Uint32List', 'new Uint32Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 8-bit unsigned integers.
+ * For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ * Indexed store clamps the value to range 0..0xFF.
+ */
 class Uint8ClampedList extends TypedData with ListMixin<int>,
     FixedLengthListMixin<int> implements JavaScriptIndexingBehavior, List<int>
     native "Uint8ClampedArray,CanvasPixelArray" {
+  /**
+   * Creates a [Uint8ClampedList] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Uint8ClampedList(int length) => _create1(length);
 
+  /**
+   * Creates a [Uint8ClampedList] of the same size as the [elements]
+   * list and copies over the values clamping when needed.
+   */
   factory Uint8ClampedList.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Uint8ClampedList] _view_ of the specified region in the
+   * specified byte [buffer]. Changes in the [Uint8List] will be visible in the
+   * byte buffer and vice versa. If the [offsetInBytes] index of the region is
+   * not specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates that
+   * the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   */
   factory Uint8ClampedList.view(ByteBuffer buffer,
                                 [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 1;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 21 matching lines @@
   static Uint8ClampedList _create2(arg1, arg2) =>
       JS('Uint8ClampedList', 'new Uint8ClampedArray(#, #)', arg1, arg2)
           .._setCachedLength();
 
   static Uint8ClampedList _create3(arg1, arg2, arg3) =>
       JS('Uint8ClampedList', 'new Uint8ClampedArray(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 8-bit unsigned integers.
+ * For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Uint8List
     extends TypedData with ListMixin<int>, FixedLengthListMixin<int>
     implements JavaScriptIndexingBehavior, List<int>
     // On some browsers Uint8ClampedArray is a subtype of Uint8Array.  Marking
     // Uint8List as !nonleaf ensures that the native dispatch correctly handles
     // the potential for Uint8ClampedArray to 'accidentally' pick up the
     // dispatch record for Uint8List.
     native "Uint8Array,!nonleaf" {
+  /**
+   * Creates a [Uint8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Uint8List(int length) => _create1(length);
 
+  /**
+   * Creates a [Uint8List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Uint8List.fromList(List<num> list) =>
       _create1(_ensureNativeList(list));
 
+  /**
+   * Creates a [Uint8List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Uint8List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   */
   factory Uint8List.view(ByteBuffer buffer,
                          [int byteOffset = 0, int length]) =>
       length == null
           ? _create2(buffer, byteOffset)
           : _create3(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 1;
 
   int get length => JS("int", '#(#)', fetchLength, this);
 
@@ skipping 19 matching lines @@
 
   static Uint8List _create2(arg1, arg2) =>
       JS('Uint8List', 'new Uint8Array(#, #)', arg1, arg2).._setCachedLength();
 
   static Uint8List _create3(arg1, arg2, arg3) =>
       JS('Uint8List', 'new Uint8Array(#, #, #)', arg1, arg2, arg3)
           .._setCachedLength();
 }
 
 
+/**
+ * A fixed-length list of 64-bit signed integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Int64List extends TypedData implements JavaScriptIndexingBehavior, List<int> {
+  /**
+   * Creates an [Int64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   factory Int64List(int length) {
     throw new UnsupportedError("Int64List not supported by dart2js.");
   }
 
+  /**
+   * Creates a [Int64List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Int64List.fromList(List<int> list) {
     throw new UnsupportedError("Int64List not supported by dart2js.");
   }
 
+  /**
+   * Creates an [Int64List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Int64List] will be visible in the byte buffer
+   * and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates that
+   * the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Int64List.view(ByteBuffer buffer, [int byteOffset, int length]) {
     throw new UnsupportedError("Int64List not supported by dart2js.");
   }
 
   static const int BYTES_PER_ELEMENT = 8;
 }
 
 
+/**
+ * A fixed-length list of 64-bit unsigned integers that is viewable as a
+ * [TypedData]. For long lists, this implementation can be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 class Uint64List extends TypedData implements JavaScriptIndexingBehavior, List<int> {
+  /**
+   * Creates a [Uint64List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   factory Uint64List(int length) {
     throw new UnsupportedError("Uint64List not supported by dart2js.");
   }
 
+  /**
+   * Creates a [Uint64List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Uint64List.fromList(List<int> list) {
     throw new UnsupportedError("Uint64List not supported by dart2js.");
   }
 
+  /**
+   * Creates an [Uint64List] _view_ of the specified region in
+   * the specified byte buffer. Changes in the [Uint64List] will be
+   * visible in the byte buffer and vice versa. If the [offsetInBytes]
+   * index of the region is not specified, it defaults to zero (the first
+   * byte in the byte buffer). If the length is not specified, it defaults
+   * to null, which indicates that the view extends to the end of the byte
+   * buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   factory Uint64List.view(ByteBuffer buffer, [int byteOffset, int length]) {
     throw new UnsupportedError("Uint64List not supported by dart2js.");
   }
 
   static const int BYTES_PER_ELEMENT = 8;
 }
 
 
+/**
+ * A fixed-length list of Float32x4 numbers that is viewable as a
+ * [TypedData]. For long lists, this implementation will be considerably more
+ * space- and time-efficient than the default [List] implementation.
+ */
 class Float32x4List
     extends Object with ListMixin<Float32x4>, FixedLengthListMixin<Float32x4>
     implements List<Float32x4>, TypedData {
 
   final Float32List _storage;
 
   ByteBuffer get buffer => _storage.buffer;
 
   int get lengthInBytes => _storage.lengthInBytes;
 
@@ skipping 20 matching lines @@
     // [length]. However, [_checkIndex] only allows indices in the range
     // 0 .. length - 1. We therefore increment the [length] argument by one
     // for the [_checkIndex] checks.
     _checkIndex(start, length + 1);
     if (end == null) return length;
     _checkIndex(end, length + 1);
     if (start > end) throw new RangeError.range(start, 0, end);
     return end;
   }
 
+  /**
+   * Creates a [Float32x4List] of the specified length (in elements),
+   * all of whose elements are initially zero.
+   */
   Float32x4List(int length) : _storage = new Float32List(length*4);
 
   Float32x4List._externalStorage(Float32List storage) : _storage = storage;
 
   Float32x4List._slowFromList(List<Float32x4> list)
       : _storage = new Float32List(list.length * 4) {
     for (int i = 0; i < list.length; i++) {
       var e = list[i];
       _storage[(i*4)+0] = e.x;
       _storage[(i*4)+1] = e.y;
       _storage[(i*4)+2] = e.z;
       _storage[(i*4)+3] = e.w;
     }
   }
 
+  /**
+   * Creates a [Float32x4List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Float32x4List.fromList(List<Float32x4> list) {
     if (list is Float32x4List) {
       Float32x4List nativeList = list as Float32x4List;
       return new Float32x4List._externalStorage(
           new Float32List.fromList(nativeList._storage));
     } else {
       return new Float32x4List._slowFromList(list);
     }
   }
 
+  /**
+   * Creates a [Float32x4List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Float32x4List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   Float32x4List.view(ByteBuffer buffer,
                      [int byteOffset = 0, int length])
       : _storage = new Float32List.view(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 16;
 
   int get length => _storage.length ~/ 4;
 
   Float32x4 operator[](int index) {
     _checkIndex(index, length);
@@ skipping 12 matching lines @@
     _storage[(index*4)+3] = value._storage[3];
   }
 
   List<Float32x4> sublist(int start, [int end]) {
     end = _checkSublistArguments(start, end, length);
     return new Float32x4List._externalStorage(_storage.sublist(start*4, end*4));
   }
 }
 
 
+/**
+ * A fixed-length list of Int32x4 numbers that is viewable as a
+ * [TypedData]. For long lists, this implementation will be considerably more
+ * space- and time-efficient than the default [List] implementation.
+ */
 class Int32x4List
     extends Object with ListMixin<Int32x4>, FixedLengthListMixin<Int32x4>
     implements List<Int32x4>, TypedData {
 
   final Uint32List _storage;
 
   ByteBuffer get buffer => _storage.buffer;
 
   int get lengthInBytes => _storage.lengthInBytes;
 
@@ skipping 20 matching lines @@
     // [length]. However, [_checkIndex] only allows indices in the range
     // 0 .. length - 1. We therefore increment the [length] argument by one
     // for the [_checkIndex] checks.
     _checkIndex(start, length + 1);
     if (end == null) return length;
     _checkIndex(end, length + 1);
     if (start > end) throw new RangeError.range(start, 0, end);
     return end;
   }
 
+  /**
+   * Creates a [Int32x4List] of the specified length (in elements),
+   * all of whose elements are initially zero.
+   */
   Int32x4List(int length) : _storage = new Uint32List(length*4);
 
   Int32x4List._externalStorage(Uint32List storage) : _storage = storage;
 
   Int32x4List._slowFromList(List<Int32x4> list)
       : _storage = new Uint32List(list.length * 4) {
     for (int i = 0; i < list.length; i++) {
       var e = list[i];
       _storage[(i*4)+0] = e.x;
       _storage[(i*4)+1] = e.y;
       _storage[(i*4)+2] = e.z;
       _storage[(i*4)+3] = e.w;
     }
   }
 
+  /**
+   * Creates a [Int32x4List] with the same size as the [elements] list
+   * and copies over the elements.
+   */
   factory Int32x4List.fromList(List<Int32x4> list) {
     if (list is Int32x4List) {
       Int32x4List nativeList = list as Int32x4List;
       return new Int32x4List._externalStorage(
           new Uint32List.fromList(nativeList._storage));
     } else {
       return new Int32x4List._slowFromList(list);
     }
   }
 
+  /**
+   * Creates a [Int32x4List] _view_ of the specified region in the specified
+   * byte buffer. Changes in the [Int32x4List] will be visible in the byte
+   * buffer and vice versa. If the [offsetInBytes] index of the region is not
+   * specified, it defaults to zero (the first byte in the byte buffer).
+   * If the length is not specified, it defaults to null, which indicates
+   * that the view extends to the end of the byte buffer.
+   *
+   * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+   * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+   * the length of [buffer].
+   *
+   * Throws [ArgumentError] if [offsetInBytes] is not a multiple of
+   * BYTES_PER_ELEMENT.
+   */
   Int32x4List.view(ByteBuffer buffer,
                      [int byteOffset = 0, int length])
       : _storage = new Uint32List.view(buffer, byteOffset, length);
 
   static const int BYTES_PER_ELEMENT = 16;
 
   int get length => _storage.length ~/ 4;
 
   Int32x4 operator[](int index) {
     _checkIndex(index, length);
@@ skipping 12 matching lines @@
     _storage[(index*4)+3] = value._storage[3];
   }
 
   List<Int32x4> sublist(int start, [int end]) {
     end = _checkSublistArguments(start, end, length);
     return new Int32x4List._externalStorage(_storage.sublist(start*4, end*4));
   }
 }
 
 
+/**
+ * Interface of Dart Float32x4 immutable value type and operations.
+ * Float32x4 stores 4 32-bit floating point values in "lanes".
+ * The lanes are "x", "y", "z", and "w" respectively.
+ */
 class Float32x4 {
   final _storage = new Float32List(4);
 
   Float32x4(double x, double y, double z, double w) {
     _storage[0] = x;
     _storage[1] = y;
     _storage[2] = z;
     _storage[3] = w;
   }
   Float32x4.splat(double v) {
@@ skipping 560 matching lines @@
   Float32x4 reciprocalSqrt() {
     double _x = Math.sqrt(1.0 / _storage[0]);
     double _y = Math.sqrt(1.0 / _storage[1]);
     double _z = Math.sqrt(1.0 / _storage[2]);
     double _w = Math.sqrt(1.0 / _storage[3]);
     return new Float32x4(_x, _y, _z, _w);
   }
 }
 
 
+/**
+ * Interface of Dart Int32x4 and operations.
+ * Int32x4 stores 4 32-bit bit-masks in "lanes".
+ * The lanes are "x", "y", "z", and "w" respectively.
+ */
 class Int32x4 {
   final _storage = new Int32List(4);
 
   Int32x4(int x, int y, int z, int w) {
     _storage[0] = x;
     _storage[1] = y;
     _storage[2] = z;
     _storage[3] = w;
   }
 
@@ skipping 465 matching lines @@
     int _w = (cmw & stw) | (~cmw & sfw);
     var r = new Float32x4(0.0, 0.0, 0.0, 0.0);
     var rView = new Int32List.view(r._storage.buffer);
     rView[0] = _x;
     rView[1] = _y;
     rView[2] = _z;
     rView[3] = _w;
     return r;
   }
 }