Document the use of two type parameters in loadUnsafe, TypedArray etc., see #349

std/assembly/internal/arraybuffer.ts

@@ -64,18 +64,40 @@ export function reallocateUnsafe(buffer: ArrayBuffer, newByteLength: i32): Array
   return buffer;
 }
 
-@inline export function loadUnsafe<T,V>(buffer: ArrayBuffer, index: i32): V {
+// The helpers below use two different types in order to emit loads and stores that load respectively
-  return <V>load<T>(changetype<usize>(buffer) + (<usize>index << alignof<T>()), HEADER_SIZE);
+// store one type to/from memory while returning/taking the desired output/input type. This allows to
+// emit instructions like
+//
+// * `i32.load8` ^= `<i32>load<i8>(...)` that reads an i8 but returns an i32, or
+// * `i64.load32_s` ^= `<i64>load<i32>(...)`) that reads a 32-bit as a 64-bit integer
+//
+// without having to emit an additional instruction for conversion purposes. This is useful for
+// small integers only of course. When dealing with reference types like classes, both parameters
+// are usually the same, even though it looks ugly.
+//
+// TODO: is there a better way to model this?
+
+@inline export function loadUnsafe<T,TOut>(buffer: ArrayBuffer, index: i32): TOut {
+  return <TOut>load<T>(changetype<usize>(buffer) + (<usize>index << alignof<T>()), HEADER_SIZE);
 }
 
-@inline export function storeUnsafe<T,V>(buffer: ArrayBuffer, index: i32, value: V): void {
+@inline export function storeUnsafe<T,TIn>(buffer: ArrayBuffer, index: i32, value: TIn): void {
   store<T>(changetype<usize>(buffer) + (<usize>index << alignof<T>()), value, HEADER_SIZE);
 }
 
-@inline export function loadUnsafeWithOffset<T,V>(buffer: ArrayBuffer, index: i32, byteOffset: i32): V {
+@inline export function loadUnsafeWithOffset<T,TOut>(
-  return <V>load<T>(changetype<usize>(buffer) + <usize>byteOffset + (<usize>index << alignof<T>()), HEADER_SIZE);
+  buffer: ArrayBuffer,
+  index: i32,
+  byteOffset: i32
+): TOut {
+  return <TOut>load<T>(changetype<usize>(buffer) + <usize>byteOffset + (<usize>index << alignof<T>()), HEADER_SIZE);
 }
 
-@inline export function storeUnsafeWithOffset<T,V>(buffer: ArrayBuffer, index: i32, value: V, byteOffset: i32): void {
+@inline export function storeUnsafeWithOffset<T,TIn>(
+  buffer: ArrayBuffer,
+  index: i32,
+  value: TIn,
+  byteOffset: i32
+): void {
   store<T>(changetype<usize>(buffer) + <usize>byteOffset + (<usize>index << alignof<T>()), value, HEADER_SIZE);
 }

std/assembly/internal/typedarray.ts

@@ -12,8 +12,11 @@ import {
   defaultComparator
 } from "./array";
 
+// The internal TypedArray class uses two type parameters for the same reason as `loadUnsafe` and
+// `storeUnsafe` in 'internal/arraybuffer.ts'. See the documentation there for details.
+
 /** Typed array base class. Not a global object. */
-export abstract class TypedArray<T,V> {
+export abstract class TypedArray<T,TNative> {
 
   readonly buffer: ArrayBuffer;
   readonly byteOffset: i32;
@@ -47,19 +50,19 @@ export abstract class TypedArray<T,V> {
   }
 
   @operator("[]=")
-  protected __set(index: i32, value: V): void {
+  protected __set(index: i32, value: TNative): void {
     if (<u32>index >= <u32>(this.byteLength >>> alignof<T>())) throw new Error("Index out of bounds");
-    storeUnsafeWithOffset<T,V>(this.buffer, index, value, this.byteOffset);
+    storeUnsafeWithOffset<T,TNative>(this.buffer, index, value, this.byteOffset);
   }
 
   @inline @operator("{}=")
-  protected __unchecked_set(index: i32, value: V): void {
+  protected __unchecked_set(index: i32, value: TNative): void {
-    storeUnsafeWithOffset<T,V>(this.buffer, index, value, this.byteOffset);
+    storeUnsafeWithOffset<T,TNative>(this.buffer, index, value, this.byteOffset);
   }
 
   // copyWithin(target: i32, start: i32, end: i32 = this.length): this
 
-  fill(value: V, start: i32 = 0, end: i32 = i32.MAX_VALUE): this {
+  fill(value: TNative, start: i32 = 0, end: i32 = i32.MAX_VALUE): this {
     var buffer = this.buffer;
     var byteOffset = this.byteOffset;
     var len = this.length;
@@ -75,14 +78,14 @@ export abstract class TypedArray<T,V> {
       }
     } else {
       for (; start < end; ++start) {
-        storeUnsafeWithOffset<T,V>(buffer, start, value, byteOffset);
+        storeUnsafeWithOffset<T,TNative>(buffer, start, value, byteOffset);
       }
     }
     return this;
   }
 
   @inline
-  subarray(begin: i32 = 0, end: i32 = i32.MAX_VALUE): TypedArray<T,V> {
+  subarray(begin: i32 = 0, end: i32 = i32.MAX_VALUE): TypedArray<T,TNative> {
     var length = this.length;
     if (begin < 0) begin = max(length + begin, 0);
     else begin = min(begin, length);

tests/compiler/std/dataview.optimized.wat

@@ -379,7 +379,7 @@
   if
    i32.const 0
    i32.const 8
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable

tests/compiler/std/dataview.untouched.wat

@@ -426,7 +426,7 @@
   if
    i32.const 0
    i32.const 8
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -492,7 +492,7 @@
   if
    i32.const 0
    i32.const 8
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable

tests/compiler/std/typedarray.optimized.wat

@@ -398,7 +398,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -442,7 +442,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -489,7 +489,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -536,7 +536,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -1015,7 +1015,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1042,7 +1042,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1133,7 +1133,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1696,7 +1696,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1720,7 +1720,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1761,7 +1761,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1860,7 +1860,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable

tests/compiler/std/typedarray.untouched.wat

@@ -472,7 +472,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -537,7 +537,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -602,7 +602,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -667,7 +667,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -732,7 +732,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -797,7 +797,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -862,7 +862,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -927,7 +927,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -992,7 +992,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -1057,7 +1057,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 24
+   i32.const 27
    i32.const 34
    call $~lib/env/abort
    unreachable
@@ -1675,7 +1675,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1708,7 +1708,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -1841,7 +1841,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -2666,7 +2666,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -2700,7 +2700,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -2755,7 +2755,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -2789,7 +2789,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 51
+   i32.const 54
    i32.const 63
    call $~lib/env/abort
    unreachable
@@ -2914,7 +2914,7 @@
   if
    i32.const 0
    i32.const 48
-   i32.const 40
+   i32.const 43
    i32.const 63
    call $~lib/env/abort
    unreachable