First step towards implementing dart:typeddata library.

sdk/lib/typeddata/typeddata_base.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.
+
+part of dart.typeddata;
+
+/**
+ * A sequence of bytes that can be used to process large quantities of
+ * numerical data more efficiently using a typed view.

[sra1, 2013/02/26 07:25:30]

I don't really think of bitmaps and textures a 'numerical'.
Perhaps 'numerical and binary'.

[siva, 2013/02/27 19:51:51]

Reworded the comment.

On 2013/02/26 07:25:30, sra1 wrote:

+ */

[sra1, 2013/02/26 07:25:30]

I would say that this is the sequence of bytes underlying a typed data object.

(In some ways 'Allocation' might be a better name for this class.)

[siva, 2013/02/27 19:51:51]

Reworded the comment.

On 2013/02/26 07:25:30, sra1 wrote:

+abstract class ByteBuffer {
+  /**
+   * Returns the length of this byte buffer, in bytes.
+   */
+  int lengthInBytes();

[Lasse Reichstein Nielsen, 2013/02/25 12:02:51]

Should be a getter.

[sra1, 2013/02/26 07:25:30]

'byteLength' would be more familiar to users of DOM typed arrays.

[siva, 2013/02/27 19:51:51]

I seem to prefer more verbose names as it clearly documents the field.

On 2013/02/26 07:25:30, sra1 wrote:

[siva, 2013/02/27 19:51:51]

Done.

+
+}
+
+
+/**
+ * A typed view of a sequence of bytes.
+ */
+abstract class TypedData {

[sra1, 2013/02/26 07:25:30]

'TypedData' is a bit of a strange name. In Dart, all values, hence all data, is
typed.  This library allows you to view bytes as several types, so in a sense,
this in *untyped data*.
I don't have a good suggestion, perhaps 'BinaryData'.

[siva, 2013/02/27 19:51:51]

I think in the g+ discussion there was a lot of back and forth on the name to
use for this class. I think we finally settled on TypedData. At this point I
don't think I want to get into another naming discussion, let us stick with
TypedData and after things are working reasonably well we can re visit.

On 2013/02/26 07:25:30, sra1 wrote:

[Lasse Reichstein Nielsen, 2013/02/28 09:05:13]

Do you have a link to this g+ discussion?

+  /**
+   * Returns the number of bytes in the representation of each element in
+   * this list, or the number bytes in the representation of the entire
+   * object if it is not a list.

[sra1, 2013/02/26 07:25:30]

So elementSizeInBytes for a ByteData is not 1?

[siva, 2013/02/27 19:51:51]

Removed that line in the comment regarding the entire object if it is not a
list, seems incorrect (some left over comment from scalar list).

On 2013/02/26 07:25:30, sra1 wrote:

+   */
+  int elementSizeInBytes();

[Lasse Reichstein Nielsen, 2013/02/25 12:02:51]

Also getter, and same for the ones below.

[sra1, 2013/02/26 07:25:30]

'bytesPerElement' is shorter and would be more familiar to users of DOM typed
arrays. 

[siva, 2013/02/27 19:51:51]

Ditto comment regarding more verbose names. If there is a general consensus on
naming these the same as DOM typed arrays, I am willing to change these names.

On 2013/02/26 07:25:30, sra1 wrote:

[siva, 2013/02/27 19:51:51]

Done.

+
+  /**
+   * Returns the offset in bytes into the underlying byte buffer of this view.
+   */
+  int offsetInBytes();
+
+  /**
+   * Returns the length of this view, in bytes.
+   */
+  int 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 64-bit signed integer
+ * is represented by the bytes of a 64-bit floating point number:
+ *
+ *     var buffer = new Uint8List(8).buffer;
+ *     var bdata = new ByteData.view(buffer);
+ *     ba.setFloat64(0, 3.14159265358979323846);

[sra1, 2013/02/26 07:25:30]

ba -> bdata

[siva, 2013/02/27 19:51:51]

Done.

+ *     int huh = ba.getInt64(0);

[Lasse Reichstein Nielsen, 2013/02/25 12:02:51]

Should it be mentioned here that the code doesn't work in dart2js (since there
are no 64-bit integers)?

[sra1, 2013/02/26 07:25:30]

I would suggest

(1) change the example to a 32-bit example so the inevitable documentation of
what works is restricted to the classes and members that have special issues.

(2) make the example more meaningful.  E.g. extract the exponent and de-bias to
compute floorLog2.

[siva, 2013/02/27 19:51:51]

Changed the example to a 32 bit example to avoid the documentation issues of
dart2js.

On 2013/02/26 07:25:30, sra1 wrote:

[siva, 2013/02/27 19:51:51]

I have changed the example to use 32 bit values.
We probably need to document these differences between dart2js and dartVM in a
more centralized place.

On 2013/02/25 12:02:51, Lasse Reichstein Nielsen wrote:

+ */
+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 [start] 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.
+   */
+  external factory ByteData.view(ByteBuffer buffer,
+                                 [int start = 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 - startIndex` is greater than the length of this object.

[Lasse Reichstein Nielsen, 2013/02/25 12:02:51]

or if startIndex or endIndex are greater than the length, or if endIndex is less
than startIndex.

Maybe we should have a definition of startIndex and endIndex "representing a
valid subrange of this" that we can refer to instead of writing it all out every
time.

[siva, 2013/02/27 19:51:51]

Added conditions
endIndex is less than startIndex, or
startIndex is greater than the length of the object.

(the endIndex greater than the length of the object becomes implicit then).


On 2013/02/25 12:02:51, Lasse Reichstein Nielsen wrote:

+   */
+  ByteData subByteData(int startIndex, [int endIndex]);
+
+  /**
+   * 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
+   * 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.
+   *
+   * Throws [ArgumentError] if [value] is less than -128 or
+   * greater than 127.
+   */
+  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.
+   *
+   * Throws [ArgumentError] if [value] is negative or
+   * greater than 255.

[sra1, 2013/02/26 07:25:30]

This check is not done by DataView, so it will be expensive to implement for
dart2js.

[Ivan Posva, 2013/02/26 23:26:20]

We had a agreed on silently truncating for all operations, except of course
where truncating is replaced with clamping.

[siva, 2013/02/27 19:51:51]

Removed comment.

On 2013/02/26 07:25:30, sra1 wrote:

[siva, 2013/02/27 19:51:51]

Done.

+   */
+  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 - 1,

[sra1, 2013/02/26 07:25:30]

Missing </sup>, also more below.

[siva, 2013/02/27 19:51:51]

Done.

+   * inclusive.
+   *
+   * Throws [RangeError] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this object.

[sra1, 2013/02/26 07:25:30]

Endianness needs to be specified.

I assume that this operation is host-endian (compatible with Int16List), which
is unsuitable for parsing data sent by a server.  A network format will specify
endianness.

DOM can efficiently support explicit big-endian and little-endian.

host-endian is more difficult. I think at best we will have to dynamically
select between a big-endian and little-endian implementations of ByteData.  That
will inhibit static inlining and add unused methods to every download, but a
good JavaScript implementation should have something to work with for inlining.

[Ivan Posva, 2013/02/26 23:26:20]

In this first cut we left out endian-specific API to cut down on the surface
area.

On 2013/02/26 07:25:30, sra1 wrote:

[siva, 2013/02/27 19:51:51]

I have left out the endianness stuff in the first cut. Will add those in the
next CL.

On 2013/02/26 07:25:30, sra1 wrote:

+   */
+  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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is less than 2<sup>15</sup>
+   * or greater than 2<sup>15 - 1.
+   */
+  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 - 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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is negative or
+   * greater than 2<sup>16 - 1.
+   */
+  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 - 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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is less than 2<sup>31</sup>
+   * or greater than 2<sup>31 - 1.
+   */
+  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 - 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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is negative or
+   * greater than 2<sup>32 - 1.
+   */
+  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 - 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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is less than 2<sup>63</sup>
+   * or greater than 2<sup>63 - 1.
+   */
+  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 - 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 - 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.
+   *
+   * Throws [ArgumentError] if [value] is negative or
+   * greater than 2<sup>64 - 1.
+   */
+  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
+ * 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 [start] 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.
+   */
+  external factory Int8List.view(ByteBuffer buffer,
+                                 [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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.
+   */
+  external factory Uint8List.view(ByteBuffer buffer,
+                                  [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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.
+   */
+  external factory Uint8ClampedList.view(ByteBuffer buffer,
+                                         [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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 [ArgumentError] if the length of the specified region

[Ivan Posva, 2013/02/26 23:26:20]

As discussed length is length in elements like in the other constructor. This
documentation from the original scalarlist is outdated.

[siva, 2013/02/27 19:51:51]

Removed comment and changed the name 'start' to 'offsetInBytes' to make it more
explicit.

On 2013/02/26 23:26:20, Ivan Posva wrote:

+   * is not divisible by 2 (the size of an "int16" in bytes), or if the
+   * [start] of the region is not divisible by 2.

[sra1, 2013/02/26 07:25:30]

It took me a long time to see that [start] was aligned.

1. Call out each constraint in a separate sentence or paragraph so it is not so
easy to miss.

2. Except where there is a good reason, put constraints in the same order as the
arguments they constrain.

Missing from the description is the constraint that the view fits within the
buffer.

[siva, 2013/02/27 19:51:51]

[start] is not aligned renamed [start] to [offsetInBytes]

Added a RangeError comment to document the constraint of the view fitting in the
underlying buffer.

On 2013/02/26 07:25:30, sra1 wrote:

+   */

[sra1, 2013/02/26 07:25:30]

This 'length' is different to the other constructor's 'length'.

We can make the naming crisper by either (1) changing the API to take a length
counted in elements or (2) rename the parameter to make it obvious that the
argument is a count of bytes.

Counting in elements has the advantage that there can't be an ArgumentError due
to 'alignment' of the length.

The DOM names for the parameters to the analogous Int16Array constructor are
'byteOffset' and 'length'.

Unless there is a strong reason to do otherwise, I suggest following the DOM
here to avoid arbitrary incompatibility.  Even small differences like having to
convert a byte length to an element length and do the alignment check requires
additional code, and I don't think there is clear winner in terms of which is
the more readable code.

Is there a good reason not to go with the DOM names?
byteOffset
byteLength
length
bytesPerElement (BYTES_PER_ELEMENT)

The new names are longer but don't really add much: 
offsetInBytes
lengthInBytes
length
elementSizeInBytes

One advantage of keeping the same names for members is that the name in
exception messages are closer to the source.  If we inline Dart
"x.offsetInBytes" to  JS "x.byteOffset", and x is null, the message will contain
'byteOffset', not 'offsetInBytes'.  It would be less confusing to debug the JS
if they were both 'byteOffset'.

[siva, 2013/02/27 19:51:51]

'length' is length counted in elements.

On 2013/02/26 07:25:30, sra1 wrote:

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

[sra1, 2013/02/26 07:25:30]

Other things being equal, a constructor for an object with properties 'a' and
'b' where the values of 'a' and 'b' are determined by parameters to the
constructor should have parameters named 'a' and 'b'.

If we stick with the current getter names, rename this to 

[int offsetInBytes = 0, int lengthInBytes]

[siva, 2013/02/27 19:51:51]

renamed start to offsetInBytes.
length is not lengthInBytes so it remains length.

On 2013/02/26 07:25:30, sra1 wrote:

+}

[sra1, 2013/02/26 07:25:30]

The JS class/constructor, Int16Array, has a static constant BYTES_PER_ELEMENT,
which can be used to divide a byteLength to get an element length.

Are we going to provide something similar to enable expressions like the
following?

length = byteLength ~/ Int16List.BYTES_PER_ELEMENT;
byteLength = length * Int16List.BYTES_PER_ELEMENT;

[siva, 2013/02/27 19:51:51]

I have added a BYTES_PER_ELEMENT constant in each of the List classes.

On 2013/02/26 07:25:30, sra1 wrote:

+
+
+/**
+ * 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 2 (the size of a "uint16" in bytes), or if the
+   * [start] of the region is not divisible by 2.
+   */
+  external factory Uint16List.view(ByteBuffer buffer,
+                                   [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 4 (the size of an "int32" in bytes), or if the
+   * [start] of the region is not divisible by 4.
+   */
+  external factory Int32List.view(ByteBuffer buffer,
+                                  [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 4 (the size of a "uint32" in bytes), or if the
+   * [start] of the region is not divisible by 4.
+   */
+  external factory Uint32List.view(ByteBuffer buffer,

[Anton Muhin, 2013/02/25 20:11:20]

there are no .transferable constructors, is it by design?

[siva, 2013/02/27 19:51:51]

In this first cut I have left out the transferable stuff in order to get an
initial version implemented. The transferable stuff can be added once we are
done with this set.

On 2013/02/25 20:11:20, Anton Muhin wrote:

+                                   [int start = 0, int length]);
+}
+
+
+/**
+ * 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 8 (the size of an "int64" in bytes), or if the
+   * [start] of the region is not divisible by 8.
+   */
+  external factory Int64List.view(ByteBuffer buffer,
+                                  [int start = 0, int length]);
+}
+
+
+/**
+ * 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.
+ */
+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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 8 (the size of a "uint64" in bytes), or if the
+   * [start] of the region is not divisible by 8.
+   */
+  external factory Uint64List.view(ByteBuffer buffer,
+                                   [int start = 0, int length]);
+}
+
+
+/**
+ * A fixed-length list of IEEE 754 single-precision binary floating-point
+ * numbers  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 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 4 (the size of a "float32" in bytes), or if the
+   * [start] of the region is not divisible by 4.
+   */
+  external factory Float32List.view(ByteBuffer buffer,
+                                    [int start = 0, int length]);
+}
+
+
+/**
+ * A fixed-length list of IEEE 754 double-precision binary floating-point
+ * numbers  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 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 [start] 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 [ArgumentError] if the length of the specified region
+   * is not divisible by 8 (the size of a "float64" in bytes), or if the
+   * [start] of the region is not divisible by 8.
+   */
+  external factory Float64List.view(ByteBuffer buffer,
+                                    [int start = 0, int length]);
+}