| OLD | NEW |
| 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
| 4 | 4 |
| 5 // TODO(ager): This should have a #library directive when the VM | 5 /** |
| 6 // can use normal library structuring. | 6 * The scalarlist library is used for Dart server applications, |
| 7 // | 7 * which run on a stand-alone Dart VM from the command line. |
| 8 // #library('dart:scalarlist'); | 8 * *This library does not work in browser based applications.* |
| 9 * |
| 10 * This library allows you to work with arrays of scalar values |
| 11 * of various sizes. |
| 12 */ |
| 13 #library('dart:scalarlist'); |
| 9 | 14 |
| 10 /** | 15 // TODO(ager): Inline the contents of byte_arrays.dart here and get |
| 11 * A random-access sequence of bytes that also provides random access to | 16 // rid of scalarlist_sources.gypi when the VM understands normal |
| 12 * the fixed-width integers and floating point numbers represented by | 17 // library structure for builtin libraries. |
| 13 * those bytes. Byte arrays may be used to pack and unpack data from | 18 #source('byte_arrays.dart'); |
| 14 * external sources (such as networks or files systems), and to process | |
| 15 * large quantities of numerical data more efficiently than would be possible | |
| 16 * with ordinary [List] implementations. Byte arrays can save space, by | |
| 17 * eliminating the need for object headers, and time, by eliminating the | |
| 18 * need for data copies. Finally, Byte arrays may be used to intentionally | |
| 19 * reinterpret the bytes representing one arithmetic type as another. | |
| 20 * For example this code fragment determine what 64-bit signed integer | |
| 21 * is represented by the bytes of a 64-bit floating point number: | |
| 22 * | |
| 23 * var ba = new ByteArray(8); | |
| 24 * ba.setFloat64(0, 3.14159265358979323846); | |
| 25 * int huh = ba.getInt64(0); | |
| 26 */ | |
| 27 abstract class ByteArray { | |
| 28 /** | |
| 29 * Returns the length of this byte array, in bytes. | |
| 30 */ | |
| 31 int lengthInBytes(); | |
| 32 | |
| 33 /** | |
| 34 * Returns a [ByteArray] _view_ of a portion of this byte array. | |
| 35 * The returned byte array consists of [length] bytes starting | |
| 36 * at position [start] in this byte array. The returned byte array | |
| 37 * is backed by the same data as this byte array. In other words, | |
| 38 * changes to the returned byte array are visible in this byte array | |
| 39 * and vice-versa. | |
| 40 * | |
| 41 * Throws [IndexOutOfRangeException] if [start] is negative, or if | |
| 42 * `start + length` is greater than the length of this byte array. | |
| 43 * | |
| 44 * Throws [IllegalArgumentException] if [length] is negative. | |
| 45 */ | |
| 46 ByteArray subByteArray([int start, int length]); | |
| 47 | |
| 48 /** | |
| 49 * Returns the (possibly negative) integer represented by the byte at the | |
| 50 * specified [byteOffset] in this byte array, in two's complement binary | |
| 51 * representation. The return value will be between -128 and 127, inclusive. | |
| 52 * | |
| 53 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 54 * greater than or equal to the length of this byte array. | |
| 55 */ | |
| 56 int getInt8(int byteOffset); | |
| 57 | |
| 58 /** | |
| 59 * Sets the byte at the specified [byteOffset] in this byte array to the | |
| 60 * two's complement binary representation of the specified [value], which | |
| 61 * must fit in a single byte. In other words, [value] must be between | |
| 62 * -128 and 127, inclusive. | |
| 63 * | |
| 64 * Returns `byteOffset + 1`, which is the offset of the first byte in the | |
| 65 * array after the byte that was set by this call. This return value can | |
| 66 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 67 * | |
| 68 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 69 * greater than or equal to the length of this byte array. | |
| 70 * | |
| 71 * Throws [IllegalArgumentException] if [value] is less than -128 or | |
| 72 * greater than 127. | |
| 73 */ | |
| 74 int setInt8(int byteOffset, int value); | |
| 75 | |
| 76 /** | |
| 77 * Returns the positive integer represented by the byte at the specified | |
| 78 * [byteOffset] in this byte array, in unsigned binary form. The | |
| 79 * return value will be between 0 and 255, inclusive. | |
| 80 * | |
| 81 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 82 * greater than or equal to the length of this byte array. | |
| 83 */ | |
| 84 int getUint8(int byteOffset); | |
| 85 | |
| 86 /** | |
| 87 * Sets the byte at the specified [byteOffset] in this byte array to the | |
| 88 * unsigned binary representation of the specified [value], which must fit | |
| 89 * in a single byte. in other words, [value] must be between 0 and 255, | |
| 90 * inclusive. | |
| 91 * | |
| 92 * Returns `byteOffset + 1`, which is the offset of the first byte in the | |
| 93 * array after the byte that was set by this call. This return value can | |
| 94 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 95 * | |
| 96 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, | |
| 97 * or greater than or equal to the length of this byte array. | |
| 98 * | |
| 99 * Throws [IllegalArgumentException] if [value] is negative or | |
| 100 * greater than 255. | |
| 101 */ | |
| 102 int setUint8(int byteOffset, int value); | |
| 103 | |
| 104 /** | |
| 105 * Returns the (possibly negative) integer represented by the two bytes at | |
| 106 * the specified [byteOffset] in this byte array, in two's complement binary | |
| 107 * form. The return value will be between 2<sup>15</sup> and 2<sup>15 - 1, | |
| 108 * inclusive. | |
| 109 * | |
| 110 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 111 * `byteOffset + 2` is greater than the length of this byte array. | |
| 112 */ | |
| 113 int getInt16(int byteOffset); | |
| 114 | |
| 115 /** | |
| 116 * Sets the two bytes starting at the specified [byteOffset] in this | |
| 117 * byte array to the two's complement binary representation of the specified | |
| 118 * [value], which must fit in two bytes. In other words, [value] must lie | |
| 119 * between 2<sup>15</sup> and 2<sup>15 - 1, inclusive. | |
| 120 * | |
| 121 * Returns `byteOffset + 2`, which is the offset of the first byte in the | |
| 122 * array after the last byte that was set by this call. This return value can | |
| 123 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 124 * | |
| 125 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 126 * `byteOffset + 2` is greater than the length of this byte array. | |
| 127 * | |
| 128 * Throws [IllegalArgumentException] if [value] is less than 2<sup>15</sup> | |
| 129 * or greater than 2<sup>15 - 1. | |
| 130 */ | |
| 131 int setInt16(int byteOffset, int value); | |
| 132 | |
| 133 /** | |
| 134 * Returns the positive integer represented by the two bytes starting | |
| 135 * at the specified [byteOffset] in this byte array, in unsigned binary | |
| 136 * form. The return value will be between 0 and 2<sup>16 - 1, inclusive. | |
| 137 * | |
| 138 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 139 * `byteOffset + 2` is greater than the length of this byte array. | |
| 140 */ | |
| 141 int getUint16(int byteOffset); | |
| 142 | |
| 143 /** | |
| 144 * Sets the two bytes starting at the specified [byteOffset] in this byte | |
| 145 * array to the unsigned binary representation of the specified [value], | |
| 146 * which must fit in two bytes. in other words, [value] must be between | |
| 147 * 0 and 2<sup>16 - 1, inclusive. | |
| 148 * | |
| 149 * Returns `byteOffset + 2`, which is the offset of the first byte in the | |
| 150 * array after the last byte that was set by this call. This return value can | |
| 151 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 152 * | |
| 153 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 154 * `byteOffset + 2` is greater than the length of this byte array. | |
| 155 * | |
| 156 * Throws [IllegalArgumentException] if [value] is negative or | |
| 157 * greater than 2<sup>16 - 1. | |
| 158 */ | |
| 159 int setUint16(int byteOffset, int value); | |
| 160 | |
| 161 /** | |
| 162 * Returns the (possibly negative) integer represented by the four bytes at | |
| 163 * the specified [byteOffset] in this byte array, in two's complement binary | |
| 164 * form. The return value will be between 2<sup>31</sup> and 2<sup>31 - 1, | |
| 165 * inclusive. | |
| 166 * | |
| 167 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 168 * `byteOffset + 4` is greater than the length of this byte array. | |
| 169 */ | |
| 170 int getInt32(int byteOffset); | |
| 171 | |
| 172 /** | |
| 173 * Sets the four bytes starting at the specified [byteOffset] in this | |
| 174 * byte array to the two's complement binary representation of the specified | |
| 175 * [value], which must fit in four bytes. In other words, [value] must lie | |
| 176 * between 2<sup>31</sup> and 2<sup>31 - 1, inclusive. | |
| 177 * | |
| 178 * Returns `byteOffset + 4`, which is the offset of the first byte in the | |
| 179 * array after the last byte that was set by this call. This return value can | |
| 180 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 181 * | |
| 182 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 183 * `byteOffset + 4` is greater than the length of this byte array. | |
| 184 * | |
| 185 * Throws [IllegalArgumentException] if [value] is less than 2<sup>31</sup> | |
| 186 * or greater than 2<sup>31 - 1. | |
| 187 */ | |
| 188 int setInt32(int byteOffset, int value); | |
| 189 | |
| 190 /** | |
| 191 * Returns the positive integer represented by the four bytes starting | |
| 192 * at the specified [byteOffset] in this byte array, in unsigned binary | |
| 193 * form. The return value will be between 0 and 2<sup>32 - 1, inclusive. | |
| 194 * | |
| 195 */ | |
| 196 int getUint32(int byteOffset); | |
| 197 | |
| 198 /** | |
| 199 * Sets the four bytes starting at the specified [byteOffset] in this byte | |
| 200 * array to the unsigned binary representation of the specified [value], | |
| 201 * which must fit in four bytes. in other words, [value] must be between | |
| 202 * 0 and 2<sup>32 - 1, inclusive. | |
| 203 * | |
| 204 * Returns `byteOffset + 4`, which is the offset of the first byte in the | |
| 205 * array after the last byte that was set by this call. This return value can | |
| 206 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 207 * | |
| 208 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 209 * `byteOffset + 4` is greater than the length of this byte array. | |
| 210 * | |
| 211 * Throws [IllegalArgumentException] if [value] is negative or | |
| 212 * greater than 2<sup>32 - 1. | |
| 213 */ | |
| 214 int setUint32(int byteOffset, int value); | |
| 215 | |
| 216 /** | |
| 217 * Returns the (possibly negative) integer represented by the eight bytes at | |
| 218 * the specified [byteOffset] in this byte array, in two's complement binary | |
| 219 * form. The return value will be between 2<sup>63</sup> and 2<sup>63 - 1, | |
| 220 * inclusive. | |
| 221 * | |
| 222 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 223 * `byteOffset + 8` is greater than the length of this byte array. | |
| 224 */ | |
| 225 int getInt64(int byteOffset); | |
| 226 | |
| 227 /** | |
| 228 * Sets the eight bytes starting at the specified [byteOffset] in this | |
| 229 * byte array to the two's complement binary representation of the specified | |
| 230 * [value], which must fit in eight bytes. In other words, [value] must lie | |
| 231 * between 2<sup>63</sup> and 2<sup>63 - 1, inclusive. | |
| 232 * | |
| 233 * Returns `byteOffset + 8`, which is the offset of the first byte in the | |
| 234 * array after the last byte that was set by this call. This return value can | |
| 235 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 236 * | |
| 237 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 238 * `byteOffset + 8` is greater than the length of this byte array. | |
| 239 * | |
| 240 * Throws [IllegalArgumentException] if [value] is less than 2<sup>63</sup> | |
| 241 * or greater than 2<sup>63 - 1. | |
| 242 */ | |
| 243 int setInt64(int byteOffset, int value); | |
| 244 | |
| 245 /** | |
| 246 * Returns the positive integer represented by the eight bytes starting | |
| 247 * at the specified [byteOffset] in this byte array, in unsigned binary | |
| 248 * form. The return value will be between 0 and 2<sup>64 - 1, inclusive. | |
| 249 * | |
| 250 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 251 * `byteOffset + 8` is greater than the length of this byte array. | |
| 252 */ | |
| 253 int getUint64(int byteOffset); | |
| 254 | |
| 255 /** | |
| 256 * Sets the eight bytes starting at the specified [byteOffset] in this byte | |
| 257 * array to the unsigned binary representation of the specified [value], | |
| 258 * which must fit in eight bytes. in other words, [value] must be between | |
| 259 * 0 and 2<sup>64 - 1, inclusive. | |
| 260 * | |
| 261 * Returns `byteOffset + 8`, which is the offset of the first byte in the | |
| 262 * array after the last byte that was set by this call. This return value can | |
| 263 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 264 * | |
| 265 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 266 * `byteOffset + 8` is greater than the length of this byte array. | |
| 267 * | |
| 268 * Throws [IllegalArgumentException] if [value] is negative or | |
| 269 * greater than 2<sup>64 - 1. | |
| 270 */ | |
| 271 int setUint64(int byteOffset, int value); | |
| 272 | |
| 273 /** | |
| 274 * Returns the floating point number represented by the four bytes at | |
| 275 * the specified [byteOffset] in this byte array, in IEEE 754 | |
| 276 * single-precision binary floating-point format (binary32). | |
| 277 * | |
| 278 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 279 * `byteOffset + 4` is greater than the length of this byte array. | |
| 280 */ | |
| 281 double getFloat32(int byteOffset); | |
| 282 | |
| 283 /** | |
| 284 * Sets the four bytes starting at the specified [byteOffset] in this | |
| 285 * byte array to the IEEE 754 single-precision binary floating-point | |
| 286 * (binary32) representation of the specified [value]. | |
| 287 * | |
| 288 * **Note that this method can lose precision.** The input [value] is | |
| 289 * a 64-bit floating point value, which will be converted to 32-bit | |
| 290 * floating point value by IEEE 754 rounding rules before it is stored. | |
| 291 * If [value] cannot be represented exactly as a binary32, it will be | |
| 292 * converted to the nearest binary32 value. If two binary32 values are | |
| 293 * equally close, the one whose least significant bit is zero will be used. | |
| 294 * Note that finite (but large) values can be converted to infinity, and | |
| 295 * small non-zero values can be converted to zero. | |
| 296 * | |
| 297 * Returns `byteOffset + 4`, which is the offset of the first byte in the | |
| 298 * array after the last byte that was set by this call. This return value can | |
| 299 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 300 * | |
| 301 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 302 * `byteOffset + 4` is greater than the length of this byte array. | |
| 303 */ | |
| 304 int setFloat32(int byteOffset, double value); | |
| 305 | |
| 306 /** | |
| 307 * Returns the floating point number represented by the eight bytes at | |
| 308 * the specified [byteOffset] in this byte array, in IEEE 754 | |
| 309 * double-precision binary floating-point format (binary64). | |
| 310 * | |
| 311 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 312 * `byteOffset + 8` is greater than the length of this byte array. | |
| 313 */ | |
| 314 double getFloat64(int byteOffset); | |
| 315 | |
| 316 /** | |
| 317 * Sets the eight bytes starting at the specified [byteOffset] in this | |
| 318 * byte array to the IEEE 754 double-precision binary floating-point | |
| 319 * (binary64) representation of the specified [value]. | |
| 320 * | |
| 321 * Returns `byteOffset + 8`, which is the offset of the first byte in the | |
| 322 * array after the last byte that was set by this call. This return value can | |
| 323 * be passed as the [byteOffset] parameter to a subsequent `setXxx` call. | |
| 324 * | |
| 325 * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or | |
| 326 * `byteOffset + 8` is greater than the length of this byte array. | |
| 327 */ | |
| 328 int setFloat64(int byteOffset, double value); | |
| 329 } | |
| 330 | |
| 331 /** | |
| 332 * A "mixin interface" that allows a type, typically but not necessarily | |
| 333 * a [List], to be viewed as a [ByteArray]. | |
| 334 */ | |
| 335 abstract class ByteArrayViewable { | |
| 336 /** | |
| 337 * Returns the number of bytes in the representation of each element in | |
| 338 * this list, or the number bytes in the representation of the entire | |
| 339 * object if it is not a list. | |
| 340 */ | |
| 341 int bytesPerElement(); | |
| 342 | |
| 343 /** | |
| 344 * Returns the length of this view, in bytes. | |
| 345 */ | |
| 346 int lengthInBytes(); | |
| 347 | |
| 348 /** | |
| 349 * Returns the byte array view of this object. This view allows the | |
| 350 * byte representation of the object to be read and written directly. | |
| 351 */ | |
| 352 ByteArray asByteArray([int start, int length]); | |
| 353 } | |
| 354 | |
| 355 | |
| 356 /** | |
| 357 * A fixed-length list of 8-bit signed integers that is viewable as a | |
| 358 * [ByteArray]. For long lists, this implementation will be considerably | |
| 359 * more space- and time-efficient than the default [List] implementation. | |
| 360 */ | |
| 361 class Int8List implements List<int>, ByteArrayViewable { | |
| 362 /** | |
| 363 * Creates an [Int8List] of the specified length (in elements), all of | |
| 364 * whose elements are initially zero. | |
| 365 */ | |
| 366 external Int8List(int length); | |
| 367 | |
| 368 /** | |
| 369 * Creates an [Int8List] _view_ of the specified region in the specified | |
| 370 * byte [array]. Changes in the [Int8List] will be visible in the byte | |
| 371 * array and vice versa. If the [start] index of the region is not specified, | |
| 372 * it defaults to zero (the first byte in the byte array). If the length is | |
| 373 * not specified, it defaults to null, which indicates that the view extends | |
| 374 * to the end of the byte array. | |
| 375 */ | |
| 376 external Int8List.view(ByteArray array, [int start, int length]); | |
| 377 } | |
| 378 | |
| 379 | |
| 380 /** | |
| 381 * A fixed-length list of 8-bit unsigned integers that is viewable as a | |
| 382 * [ByteArray]. For long lists, this implementation will be considerably | |
| 383 * more space- and time-efficient than the default [List] implementation. | |
| 384 */ | |
| 385 class Uint8List implements List<int>, ByteArrayViewable { | |
| 386 /** | |
| 387 * Creates a [Uint8List] of the specified length (in elements), all of | |
| 388 * whose elements are initially zero. | |
| 389 */ | |
| 390 external Uint8List(int length); | |
| 391 | |
| 392 /** | |
| 393 * Creates a [Uint8List] _view_ of the specified region in the specified | |
| 394 * byte [array]. Changes in the [Uint8List] will be visible in the byte | |
| 395 * array and vice versa. If the [start] index of the region is not specified, | |
| 396 * it defaults to zero (the first byte in the byte array). If the length is | |
| 397 * not specified, it defaults to null, which indicates that the view extends | |
| 398 * to the end of the byte array. | |
| 399 */ | |
| 400 external Uint8List.view(ByteArray array, [int start, int length]); | |
| 401 } | |
| 402 | |
| 403 | |
| 404 /** | |
| 405 * A fixed-length list of 16-bit signed integers that is viewable as a | |
| 406 * [ByteArray]. For long lists, this implementation will be considerably | |
| 407 * more space- and time-efficient than the default [List] implementation. | |
| 408 */ | |
| 409 class Int16List implements List<int>, ByteArrayViewable { | |
| 410 /** | |
| 411 * Creates an [Int16List] of the specified length (in elements), all of | |
| 412 * whose elements are initially zero. | |
| 413 */ | |
| 414 external Int16List(int length); | |
| 415 | |
| 416 /** | |
| 417 * Creates an [Int16List] _view_ of the specified region in the specified | |
| 418 * byte [array]. Changes in the [Int16List] will be visible in the byte | |
| 419 * array and vice versa. If the [start] index of the region is not specified, | |
| 420 * it defaults to zero (the first byte in the byte array). If the length is | |
| 421 * not specified, it defaults to null, which indicates that the view extends | |
| 422 * to the end of the byte array. | |
| 423 * | |
| 424 * Throws [IllegalArgumentException] if the length of the specified region | |
| 425 * is not divisible by 2 (the size of an "int16" in bytes), or if the | |
| 426 * [start] of the region is not divisible by 2. If, however, [array] | |
| 427 * is a view of another byte array, this constructor will throw | |
| 428 * [IllegalArgumentException] if the implicit starting position in the | |
| 429 * "ultimately backing" byte array is not divisible by 2. In plain terms, | |
| 430 * this constructor throws [IllegalArgumentException] if the specified | |
| 431 * region does not contain an integral number of "int16s," or if it | |
| 432 * is not "int16-aligned." | |
| 433 */ | |
| 434 external Int16List.view(ByteArray array, [int start, int length]); | |
| 435 } | |
| 436 | |
| 437 | |
| 438 /** | |
| 439 * A fixed-length list of 16-bit unsigned integers that is viewable as a | |
| 440 * [ByteArray]. For long lists, this implementation will be considerably | |
| 441 * more space- and time-efficient than the default [List] implementation. | |
| 442 */ | |
| 443 class Uint16List implements List<int>, ByteArrayViewable { | |
| 444 /** | |
| 445 * Creates a [Uint16List] of the specified length (in elements), all | |
| 446 * of whose elements are initially zero. | |
| 447 */ | |
| 448 external Uint16List(int length); | |
| 449 | |
| 450 /** | |
| 451 * Creates a [Uint16List] _view_ of the specified region in | |
| 452 * the specified byte [array]. Changes in the [Uint16List] will be | |
| 453 * visible in the byte array and vice versa. If the [start] index of the | |
| 454 * region is not specified, it defaults to zero (the first byte in the byte | |
| 455 * array). If the length is not specified, it defaults to null, which | |
| 456 * indicates that the view extends to the end of the byte array. | |
| 457 * | |
| 458 * Throws [IllegalArgumentException] if the length of the specified region | |
| 459 * is not divisible by 2 (the size of a "uint16" in bytes), or if the | |
| 460 * [start] of the region is not divisible by 2. If, however, [array] | |
| 461 * is a view of another byte array, this constructor will throw | |
| 462 * [IllegalArgumentException] if the implicit starting position in the | |
| 463 * "ultimately backing" byte array is not divisible by 2. In plain terms, | |
| 464 * this constructor throws [IllegalArgumentException] if the specified | |
| 465 * region does not contain an integral number of "uint16s," or if it | |
| 466 * is not "uint16-aligned." | |
| 467 */ | |
| 468 external Uint16List.view(ByteArray array, [int start, int length]); | |
| 469 } | |
| 470 | |
| 471 | |
| 472 /** | |
| 473 * A fixed-length list of 32-bit signed integers that is viewable as a | |
| 474 * [ByteArray]. For long lists, this implementation will be considerably | |
| 475 * more space- and time-efficient than the default [List] implementation. | |
| 476 */ | |
| 477 class Int32List implements List<int>, ByteArrayViewable { | |
| 478 /** | |
| 479 * Creates an [Int32List] of the specified length (in elements), all of | |
| 480 * whose elements are initially zero. | |
| 481 */ | |
| 482 external Int32List(int length); | |
| 483 | |
| 484 /** | |
| 485 * Creates an [Int32List] _view_ of the specified region in the specified | |
| 486 * byte [array]. Changes in the [Int32List] will be visible in the byte | |
| 487 * array and vice versa. If the [start] index of the region is not specified, | |
| 488 * it defaults to zero (the first byte in the byte array). If the length is | |
| 489 * not specified, it defaults to null, which indicates that the view extends | |
| 490 * to the end of the byte array. | |
| 491 * | |
| 492 * Throws [IllegalArgumentException] if the length of the specified region | |
| 493 * is not divisible by 4 (the size of an "int32" in bytes), or if the | |
| 494 * [start] of the region is not divisible by 4. If, however, [array] | |
| 495 * is a view of another byte array, this constructor will throw | |
| 496 * [IllegalArgumentException] if the implicit starting position in the | |
| 497 * "ultimately backing" byte array is not divisible by 4. In plain terms, | |
| 498 * this constructor throws [IllegalArgumentException] if the specified | |
| 499 * region does not contain an integral number of "int32s," or if it | |
| 500 * is not "int32-aligned." | |
| 501 */ | |
| 502 external Int32List.view(ByteArray array, [int start, int length]); | |
| 503 } | |
| 504 | |
| 505 | |
| 506 /** | |
| 507 * A fixed-length list of 32-bit unsigned integers that is viewable as a | |
| 508 * [ByteArray]. For long lists, this implementation will be considerably | |
| 509 * more space- and time-efficient than the default [List] implementation. | |
| 510 */ | |
| 511 class Uint32List implements List<int>, ByteArrayViewable { | |
| 512 /** | |
| 513 * Creates a [Uint32List] of the specified length (in elements), all | |
| 514 * of whose elements are initially zero. | |
| 515 */ | |
| 516 external Uint32List(int length); | |
| 517 | |
| 518 /** | |
| 519 * Creates a [Uint32List] _view_ of the specified region in | |
| 520 * the specified byte [array]. Changes in the [Uint32] will be | |
| 521 * visible in the byte array and vice versa. If the [start] index of the | |
| 522 * region is not specified, it defaults to zero (the first byte in the byte | |
| 523 * array). If the length is not specified, it defaults to null, which | |
| 524 * indicates that the view extends to the end of the byte array. | |
| 525 * | |
| 526 * Throws [IllegalArgumentException] if the length of the specified region | |
| 527 * is not divisible by 4 (the size of a "uint32" in bytes), or if the | |
| 528 * [start] of the region is not divisible by 4. If, however, [array] | |
| 529 * is a view of another byte array, this constructor will throw | |
| 530 * [IllegalArgumentException] if the implicit starting position in the | |
| 531 * "ultimately backing" byte array is not divisible by 4. In plain terms, | |
| 532 * this constructor throws [IllegalArgumentException] if the specified | |
| 533 * region does not contain an integral number of "uint32s," or if it | |
| 534 * is not "uint32-aligned." | |
| 535 */ | |
| 536 external Uint32List.view(ByteArray array, [int start, int length]); | |
| 537 } | |
| 538 | |
| 539 | |
| 540 /** | |
| 541 * A fixed-length list of 64-bit signed integers that is viewable as a | |
| 542 * [ByteArray]. For long lists, this implementation will be considerably | |
| 543 * more space- and time-efficient than the default [List] implementation. | |
| 544 */ | |
| 545 class Int64List implements List<int>, ByteArrayViewable { | |
| 546 /** | |
| 547 * Creates an [Int64List] of the specified length (in elements), all of | |
| 548 * whose elements are initially zero. | |
| 549 */ | |
| 550 external Int64List(int length); | |
| 551 | |
| 552 /** | |
| 553 * Creates an [Int64List] _view_ of the specified region in the specified | |
| 554 * byte [array]. Changes in the [Int64List] will be visible in the byte | |
| 555 * array and vice versa. If the [start] index of the region is not specified, | |
| 556 * it defaults to zero (the first byte in the byte array). If the length is | |
| 557 * not specified, it defaults to null, which indicates that the view extends | |
| 558 * to the end of the byte array. | |
| 559 * | |
| 560 * Throws [IllegalArgumentException] if the length of the specified region | |
| 561 * is not divisible by 8 (the size of an "int64" in bytes), or if the | |
| 562 * [start] of the region is not divisible by 8. If, however, [array] | |
| 563 * is a view of another byte array, this constructor will throw | |
| 564 * [IllegalArgumentException] if the implicit starting position in the | |
| 565 * "ultimately backing" byte array is not divisible by 8. In plain terms, | |
| 566 * this constructor throws [IllegalArgumentException] if the specified | |
| 567 * region does not contain an integral number of "int64s," or if it | |
| 568 * is not "int64-aligned." | |
| 569 */ | |
| 570 external Int64List.view(ByteArray array, [int start, int length]); | |
| 571 } | |
| 572 | |
| 573 | |
| 574 /** | |
| 575 * A fixed-length list of 64-bit unsigned integers that is viewable as a | |
| 576 * [ByteArray]. For long lists, this implementation will be considerably | |
| 577 * more space- and time-efficient than the default [List] implementation. | |
| 578 */ | |
| 579 class Uint64List implements List<int>, ByteArrayViewable { | |
| 580 /** | |
| 581 * Creates a [Uint64List] of the specified length (in elements), all | |
| 582 * of whose elements are initially zero. | |
| 583 */ | |
| 584 external Uint64List(int length); | |
| 585 | |
| 586 /** | |
| 587 * Creates an [Uint64List] _view_ of the specified region in | |
| 588 * the specified byte [array]. Changes in the [Uint64List] will be | |
| 589 * visible in the byte array and vice versa. If the [start] index of the | |
| 590 * region is not specified, it defaults to zero (the first byte in the byte | |
| 591 * array). If the length is not specified, it defaults to null, which | |
| 592 * indicates that the view extends to the end of the byte array. | |
| 593 * | |
| 594 * Throws [IllegalArgumentException] if the length of the specified region | |
| 595 * is not divisible by 8 (the size of a "uint64" in bytes), or if the | |
| 596 * [start] of the region is not divisible by 8. If, however, [array] | |
| 597 * is a view of another byte array, this constructor will throw | |
| 598 * [IllegalArgumentException] if the implicit starting position in the | |
| 599 * "ultimately backing" byte array is not divisible by 8. In plain terms, | |
| 600 * this constructor throws [IllegalArgumentException] if the specified | |
| 601 * region does not contain an integral number of "uint64s," or if it | |
| 602 * is not "uint64-aligned." | |
| 603 */ | |
| 604 external Uint64List.view(ByteArray array, [int start, int length]); | |
| 605 } | |
| 606 | |
| 607 | |
| 608 /** | |
| 609 * A fixed-length list of IEEE 754 single-precision binary floating-point | |
| 610 * numbers that is viewable as a [ByteArray]. For long lists, this | |
| 611 * implementation will be considerably more space- and time-efficient than | |
| 612 * the default [List] implementation. | |
| 613 */ | |
| 614 class Float32List implements List<double>, ByteArrayViewable { | |
| 615 /** | |
| 616 * Creates a [Float32List] of the specified length (in elements), all of | |
| 617 * whose elements are initially zero. | |
| 618 */ | |
| 619 external Float32List(int length); | |
| 620 | |
| 621 /** | |
| 622 * Creates a [Float32List] _view_ of the specified region in the specified | |
| 623 * byte [array]. Changes in the [Float32List] will be visible in the byte | |
| 624 * array and vice versa. If the [start] index of the region is not specified, | |
| 625 * it defaults to zero (the first byte in the byte array). If the length is | |
| 626 * not specified, it defaults to null, which indicates that the view extends | |
| 627 * to the end of the byte array. | |
| 628 * | |
| 629 * Throws [IllegalArgumentException] if the length of the specified region | |
| 630 * is not divisible by 4 (the size of a "float32" in bytes), or if the | |
| 631 * [start] of the region is not divisible by 4. If, however, [array] | |
| 632 * is a view of another byte array, this constructor will throw | |
| 633 * [IllegalArgumentException] if the implicit starting position in the | |
| 634 * "ultimately backing" byte array is not divisible by 4. In plain terms, | |
| 635 * this constructor throws [IllegalArgumentException] if the specified | |
| 636 * region does not contain an integral number of "float32s," or if it | |
| 637 * is not "float32-aligned." | |
| 638 */ | |
| 639 external Float32List.view(ByteArray array, [int start, int length]); | |
| 640 } | |
| 641 | |
| 642 | |
| 643 /** | |
| 644 * A fixed-length list of IEEE 754 double-precision binary floating-point | |
| 645 * numbers that is viewable as a [ByteArray]. For long lists, this | |
| 646 * implementation will be considerably more space- and time-efficient than | |
| 647 * the default [List] implementation. | |
| 648 */ | |
| 649 class Float64List implements List<double>, ByteArrayViewable { | |
| 650 /** | |
| 651 * Creates a [Float64List] of the specified length (in elements), all of | |
| 652 * whose elements are initially zero. | |
| 653 */ | |
| 654 external Float64List(int length); | |
| 655 | |
| 656 /** | |
| 657 * Creates a [Float64List] _view_ of the specified region in the specified | |
| 658 * byte [array]. Changes in the [Float64List] will be visible in the byte | |
| 659 * array and vice versa. If the [start] index of the region is not specified, | |
| 660 * it defaults to zero (the first byte in the byte array). If the length is | |
| 661 * not specified, it defaults to null, which indicates that the view extends | |
| 662 * to the end of the byte array. | |
| 663 * | |
| 664 * Throws [IllegalArgumentException] if the length of the specified region | |
| 665 * is not divisible by 8 (the size of a "float64" in bytes), or if the | |
| 666 * [start] of the region is not divisible by 8. If, however, [array] | |
| 667 * is a view of another byte array, this constructor will throw | |
| 668 * [IllegalArgumentException] if the implicit starting position in the | |
| 669 * "ultimately backing" byte array is not divisible by 8. In plain terms, | |
| 670 * this constructor throws [IllegalArgumentException] if the specified | |
| 671 * region does not contain an integral number of "float64s," or if it | |
| 672 * is not "float64-aligned." | |
| 673 */ | |
| 674 external Float64List.view(ByteArray array, [int start, int length]); | |
| 675 } | |
| OLD | NEW |