First step towards implementing dart:typeddata library.

sdk/lib/typeddata/typeddata_base.dart

Index: sdk/lib/typeddata/typeddata_base.dart
===================================================================
--- sdk/lib/typeddata/typeddata_base.dart	(revision 0)
+++ sdk/lib/typeddata/typeddata_base.dart	(revision 0)
@@ -0,0 +1,711 @@
+// 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.
+
+part of dart.typeddata;
+
+/**
+ * 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.
+ */
+abstract class ByteBuffer {
+  /**
+   * Returns the length of this byte buffer, in bytes.
+   */
+  int get lengthInBytes;
+
+}
+
+
+/**
+ * A typed view of a sequence of bytes.
+ */
+abstract class TypedData {
+  /**
+   * Returns the number of bytes in the representation of each element in this list.

[sra1, 2013/02/28 02:41:58]

Line length?

[siva, 2013/03/01 01:15:56]

Fixed.

On 2013/02/28 02:41:58, sra1 wrote:

+   */
+  int get elementSizeInBytes;
+
+  /**
+   * Returns the offset in bytes into the underlying byte buffer of this view.
+   */
+  int get offsetInBytes;
+
+  /**
+   * Returns the length of this view, in bytes.
+   */
+  int get lengthInBytes;
+
+  /**
+   * Returns the byte buffer associated with this object.
+   */
+  ByteBuffer get buffer;
+}
+
+
+/**
+ * A fixed-length, random-access sequence of bytes that also provides random
+ * 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:

[Ivan Posva, 2013/02/28 05:00:02]

As far as I remember the plan was to allow ByteData unaligned access as we are
potentially dealing with files or network streams.

[siva, 2013/03/01 01:15:56]

I thought random-access also meant unaligned access.
I could make it more explicit by adding a note on unaligned access.

On 2013/02/28 05:00:02, Ivan Posva wrote:

+ *
+ *     var buffer = new Uint8List(8).buffer;
+ *     var bdata = new ByteData.view(buffer);
+ *     bdata.setFloat32(0, 3.04);
+ *     int huh = bdata.getInt32(0);
+ */
+abstract class ByteData implements TypedData {
+  /**
+   * Creates a [ByteData] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory ByteData(int 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 this object.
+   */
+  external factory ByteData.view(ByteBuffer buffer,
+                                 [int offsetInBytes = 0, int length]);
+
+  /**
+   * Returns a [ByteData] _view_ of a portion of this ByteData object
+   * in the given range.
+   * [startIndex] is inclusive and [endIndex] is exclusive.
+   * The returned object is backed by the same byte buffer as this object.
+   * In other words, changes to the returned object are visible in this object
+   * and vice-versa.
+   *
+   * Throws [RangeError] if [startIndex] or [endIndex] are negative, or
+   * if [endIndex] is less than [startIndex], or
+   * if [startIndex] is greater than the length of this object, or
+   * if `endIndex - startIndex` is greater than the length of this object.
+   */
+  ByteData subByteData(int startIndex, [int endIndex]);

[Ivan Posva, 2013/02/28 05:00:02]

Basically this is a sugar for:
var sb = new ByteData.view(original.buffer, original.offsetInBytes + startIndex,
endIndex-startIndex);

The startIndex, endIndex names do not match the rest of the names used in this
file. I am not sure this is really needed, how about removing it for now?

[siva, 2013/03/01 01:15:56]

Yes. It is basically sugar for that with the additional Range checks. I think it
was trying to mimic the subarray call in JS. I have removed it for now. We can
always add it back if needed.

On 2013/02/28 05:00:02, Ivan Posva wrote:

+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 1`, which is the offset of the first byte in the

[Ivan Posva, 2013/02/28 05:00:02]

I am not sure I understand the purpose of the return value of the setter.

[siva, 2013/03/01 01:15:56]

I don't remember why this returns setInt8 (Carl at some point explained this but
I don't recall).
We should remove it for now and can revisit if needed.

On 2013/02/28 05:00:02, Ivan Posva wrote:

+   * buffer after the byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * greater than or equal to the length of this object.
+   */
+  int setInt8(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 1`, which is the offset of the first byte in the
+   * buffer after the byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative,
+   * or greater than or equal to the length of this object.
+   */
+  int setUint8(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 2`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
+  int setInt16(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 2`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.
+   */
+  int setUint16(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
+  int setInt32(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
+  int setUint32(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
+  int setInt64(int byteOffset, int value);
+
+  /**
+   * 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);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
+  int setUint64(int byteOffset, int value);
+
+  /**
+   * 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.
+   */
+  double getFloat32(int byteOffset);
+
+  /**
+   * 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.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this object.
+   */
+  int setFloat32(int byteOffset, double value);
+
+  /**
+   * 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.
+   */
+  double getFloat64(int byteOffset);
+
+  /**
+   * 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].
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in this
+   * object after the last byte that was set by this call. This return value
+   * can be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this object.
+   */
+  int setFloat64(int byteOffset, double value);
+}
+
+
+/**
+ * A fixed-length list of 8-bit signed integers.
+ * For long lists, this implementation will be considerably

[Ivan Posva, 2013/02/28 05:00:02]

will -> can

[siva, 2013/03/01 01:15:56]

Done.

+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Int8List implements List<int>, TypedData {
+  /**
+   * Creates an [Int8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Int8List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Int8List.view(ByteBuffer buffer,
+                                 [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 1;
+}
+
+
+/**
+ * A fixed-length list of 8-bit unsigned integers.
+ * For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Uint8List implements List<int>, TypedData {
+  /**
+   * Creates a [Uint8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Uint8List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Uint8List.view(ByteBuffer buffer,
+                                  [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 1;
+}
+
+
+/**
+ * A fixed-length list of 8-bit unsigned integers.
+ * For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ * Indexed store clamps the value to range 0..0xFF.
+ */
+abstract class Uint8ClampedList implements List<int>, TypedData {
+  /**
+   * Creates a [Uint8ClampedList] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Uint8ClampedList(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Uint8ClampedList.view(ByteBuffer buffer,
+                                         [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 1;
+}
+
+
+/**
+ * A fixed-length list of 16-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Int16List implements List<int>, TypedData {
+  /**
+   * Creates an [Int16List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Int16List(int length);
+
+  /**
+   * 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 this object.

[sra1, 2013/02/28 02:41:58]

this object -> [buffer]

[siva, 2013/03/01 01:15:56]

Done.

+   */
+  external factory Int16List.view(ByteBuffer buffer,
+                                  [int offsetInBytes = 0, int length]);

[Ivan Posva, 2013/02/28 05:00:02]

Isn't the expectation that offsetInBytes is aligned to BYTES_PER_ELEMENT?

[siva, 2013/03/01 01:15:56]

The current scalarlist implementation doesn't seem to require that but the JS
specification does state that the byteOffset should be a multiple of the element
size of the specific type. We should probably add that as an ArgumentError.

On 2013/02/28 05:00:02, Ivan Posva wrote:

+
+  static const int BYTES_PER_ELEMENT = 2;
+}
+
+
+/**
+ * A fixed-length list of 16-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Uint16List implements List<int>, TypedData {
+  /**
+   * Creates a [Uint16List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
+  external factory Uint16List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Uint16List.view(ByteBuffer buffer,
+                                   [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 2;
+}
+
+
+/**
+ * A fixed-length list of 32-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Int32List implements List<int>, TypedData {
+  /**
+   * Creates an [Int32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Int32List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Int32List.view(ByteBuffer buffer,
+                                  [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 4;
+}
+
+
+/**
+ * A fixed-length list of 32-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Uint32List implements List<int>, TypedData {
+  /**
+   * Creates a [Uint32List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
+  external factory Uint32List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Uint32List.view(ByteBuffer buffer,
+                                   [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 4;
+}
+
+
+/**
+ * A fixed-length list of 64-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
+abstract class Int64List implements List<int>, TypedData {
+  /**
+   * Creates an [Int64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Int64List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Int64List.view(ByteBuffer buffer,
+                                  [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 8;
+}
+
+
+/**
+ * A fixed-length list of 64-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.

[sra1, 2013/02/28 02:41:58]

I agree that this boilerplate comment is true for Uint8List, but it might not be
true if the list contains values that predominantly fit in a Smi, especially on
a 32 bit VM.

perhaps 'may be' rather than 'will be'.

[siva, 2013/03/01 01:15:56]

The comment was changed to 'can be'.

Your point about a list consisting of predominantly Smi values being more
efficient than Int64List could be true if you stayed primarily in Dart, the
minute you start any DOM interaction and going across the C++ boundary the new
direct access API functions we have will definitely make Int64List more
efficient.

On 2013/02/28 02:41:58, sra1 wrote:

+ */
+abstract class Uint64List implements List<int>, TypedData {
+  /**
+   * Creates a [Uint64List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
+  external factory Uint64List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Uint64List.view(ByteBuffer buffer,
+                                   [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 8;
+}
+
+
+/**
+ * A fixed-length list of IEEE 754 single-precision binary floating-point
+ * numbers  that is viewable as a [ByteArray]. For long lists, this

[Ivan Posva, 2013/02/28 05:00:02]

ByteArray?

[siva, 2013/03/01 01:15:56]

Done.

+ * implementation will be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
+abstract class Float32List implements List<double>, TypedData {
+  /**
+   * Creates a [Float32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Float32List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Float32List.view(ByteBuffer buffer,
+                                    [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 4;
+}
+
+
+/**
+ * A fixed-length list of IEEE 754 double-precision binary floating-point
+ * numbers  that is viewable as a [ByteArray]. For long lists, this

[Ivan Posva, 2013/02/28 05:00:02]

ditto

[siva, 2013/03/01 01:15:56]

Done.

+ * implementation will be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
+abstract class Float64List implements List<double>, TypedData {
+  /**
+   * Creates a [Float64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
+  external factory Float64List(int length);
+
+  /**
+   * 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 this object.
+   */
+  external factory Float64List.view(ByteBuffer buffer,
+                                    [int offsetInBytes = 0, int length]);
+
+  static const int BYTES_PER_ELEMENT = 8;
+}