Stage 3 Draft / December 5, 2024

Float16Array

Contributing to this Proposal

You can discuss this proposal on GitHub.

1 Introduction

This proposal adds a new kind of TypedArray. TypedArrays are specified in a slightly different way from the rest of the standard library, so the specification for this proposal consists of a surprisingly small change.

2 Constructor Properties of the Global Object

The following subclause is inserted.

2.1 Float16Array ( . . . )

See 23.2.5.

3 Function Properties of the Math Object

3.1 Math.f16round ( x )

This function performs the following steps when called:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, return NaN.
  3. If n is one of +0𝔽, -0𝔽, +∞𝔽, or -∞𝔽, return n.
  4. Let n16 be the result of converting n to IEEE 754-2019 binary16 format using roundTiesToEven mode.
  5. Let n64 be the result of converting n16 to IEEE 754-2019 binary64 format.
  6. Return the ECMAScript Number value corresponding to n64.
 Note

This operation is not the same as casting to binary32 and then to binary16 because of the possibility of double-rounding: consider the number k = 1.00048828125000022204𝔽, for example, for which which Math.f16round(k) is 1.0009765625𝔽, but Math.f16round(Math.fround(k)) is 1𝔽.

Not all platforms provide native support for casting from binary64 to binary16. There are various libraries which can provide this, including the MIT-licensed half library. Alternatively, it is possible to first cast from binary64 to binary32 under roundTiesToEven and then check whether the result could lead to incorrect double-rounding. The cases which could can be handled explicitly by adjusting the mantissa of the binary32 value so that it is the value which would be produced by performing the initial cast under roundTiesToOdd. Casting the adjusted value to binary16 under roundTiesToEven then produces the correct value.

4 TypedArray Objects

The table below is modified by the addition of a row for float16.

Table 1: The TypedArray Constructors
Constructor Name and Intrinsic Element Type Element Size Conversion Operation Description
Int8Array
%Int8Array% 		Int8 1 ToInt8 8-bit two's complement signed integer
Uint8Array
%Uint8Array% 		Uint8 1 ToUint8 8-bit unsigned integer
Uint8ClampedArray
%Uint8ClampedArray% 		Uint8C 1 ToUint8Clamp 8-bit unsigned integer (clamped conversion)
Int16Array
%Int16Array% 		Int16 2 ToInt16 16-bit two's complement signed integer
Uint16Array
%Uint16Array% 		Uint16 2 ToUint16 16-bit unsigned integer
Int32Array
%Int32Array% 		Int32 4 ToInt32 32-bit two's complement signed integer
Uint32Array
%Uint32Array% 		Uint32 4 ToUint32 32-bit unsigned integer
BigInt64Array
%BigInt64Array% 		BigInt64 8 ToBigInt64 64-bit two's complement signed integer
BigUint64Array
%BigUint64Array% 		BigUint64 8 ToBigUint64 64-bit unsigned integer
Float16Array
%Float16Array% 		Float16 2 16-bit IEEE floating point
Float32Array
%Float32Array% 		Float32 4 32-bit IEEE floating point
Float64Array
%Float64Array% 		Float64 8 64-bit IEEE floating point

5 RawBytesToNumeric ( type, rawBytes, isLittleEndian )

The abstract operation RawBytesToNumeric takes arguments type (a TypedArray element type), rawBytes (a List of byte values), and isLittleEndian (a Boolean) and returns a Number or a BigInt.

The algorithm below is modified by the addition of a case for Float16.

  1. Let elementSize be the Element Size value specified in Table 1 for Element Type type.
  2. If isLittleEndian is false, reverse the order of the elements of rawBytes.
  3. If type is Float16, then
    1. Let value be the byte elements of rawBytes concatenated and interpreted as a little-endian bit string encoding of an IEEE 754-2019 binary16 value.
    2. If value is an IEEE 754-2019 binary16 NaN value, return the NaN Number value.
    3. Return the Number value that corresponds to value.
  4. If type is Float32, then
    1. Let value be the byte elements of rawBytes concatenated and interpreted as a little-endian bit string encoding of an IEEE 754-2019 binary32 value.
    2. If value is an IEEE 754-2019 binary32 NaN value, return the NaN Number value.
    3. Return the Number value that corresponds to value.
  5. If type is Float64, then
    1. Let value be the byte elements of rawBytes concatenated and interpreted as a little-endian bit string encoding of an IEEE 754-2019 binary64 value.
    2. If value is an IEEE 754-2019 binary64 NaN value, return the NaN Number value.
    3. Return the Number value that corresponds to value.
  6. If IsUnsignedElementType(type) is true, then
    1. Let intValue be the byte elements of rawBytes concatenated and interpreted as a bit string encoding of an unsigned little-endian binary number.
  7. Else,
    1. Let intValue be the byte elements of rawBytes concatenated and interpreted as a bit string encoding of a binary little-endian two's complement number of bit length elementSize × 8.
  8. If IsBigIntElementType(type) is true, return the BigInt value that corresponds to intValue.
  9. Otherwise, return the Number value that corresponds to intValue.

6 NumericToRawBytes ( type, value, isLittleEndian )

The abstract operation NumericToRawBytes takes arguments type (a TypedArray element type), value (a Number or a BigInt), and isLittleEndian (a Boolean) and returns a List of byte values.

The algorithm below is modified by the addition of a case for Float16.

  1. If type is Float16, then
    1. Let rawBytes be a List whose elements are the 2 bytes that are the result of converting value to IEEE 754-2019 binary16 format using roundTiesToEven mode. The bytes are arranged in little endian order. If value is NaN, rawBytes may be set to any implementation chosen IEEE 754-2019 binary16 format Not-a-Number encoding. An implementation must always choose the same encoding for each implementation distinguishable NaN value.
  2. Else if type is Float32, then
    1. Let rawBytes be a List whose elements are the 4 bytes that are the result of converting value to IEEE 754-2019 binary32 format using roundTiesToEven mode. The bytes are arranged in little endian order. If value is NaN, rawBytes may be set to any implementation chosen IEEE 754-2019 binary32 format Not-a-Number encoding. An implementation must always choose the same encoding for each implementation distinguishable NaN value.
  3. Else if type is Float64, then
    1. Let rawBytes be a List whose elements are the 8 bytes that are the IEEE 754-2019 binary64 format encoding of value. The bytes are arranged in little endian order. If value is NaN, rawBytes may be set to any implementation chosen IEEE 754-2019 binary64 format Not-a-Number encoding. An implementation must always choose the same encoding for each implementation distinguishable NaN value.
  4. Else,
    1. Let n be the Element Size value specified in Table 1 for Element Type type.
    2. Let convOp be the abstract operation named in the Conversion Operation column in Table 1 for Element Type type.
    3. Let intValue be ℝ(convOp(value)).
    4. If intValue ≥ 0, then
      1. Let rawBytes be a List whose elements are the n-byte binary encoding of intValue. The bytes are ordered in little endian order.
    5. Else,
      1. Let rawBytes be a List whose elements are the n-byte binary two's complement encoding of intValue. The bytes are ordered in little endian order.
  5. If isLittleEndian is false, reverse the order of the elements of rawBytes.
  6. Return rawBytes.

7 Properties of the DataView Prototype Object

The following two subclauses are inserted.

7.1 DataView.prototype.getFloat16 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Float16).

7.2 DataView.prototype.setFloat16 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Float16, value).