Reference for stage-3 float16array (mdn#33652)

* Reference for stage-3 float16array

* Address reviews

* math - remove x for other cases

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

files/en-us/web/javascript/guide/typed_arrays/index.md

@@ -57,6 +57,7 @@ Typed array views have self-descriptive names and provide views for all the usua
 | {{jsxref("Uint16Array")}}       | 0 to 65535                            | 2             | `unsigned short`      |
 | {{jsxref("Int32Array")}}        | -2147483648 to 2147483647             | 4             | `long`                |
 | {{jsxref("Uint32Array")}}       | 0 to 4294967295                       | 4             | `unsigned long`       |
+| {{jsxref("Float16Array")}}      | `-65504` to `65504`                   | 2             | N/A                   |
 | {{jsxref("Float32Array")}}      | `-3.4e38` to `3.4e38`                 | 4             | `unrestricted float`  |
 | {{jsxref("Float64Array")}}      | `-1.8e308` to `1.8e308`               | 8             | `unrestricted double` |
 | {{jsxref("BigInt64Array")}}     | -2<sup>63</sup> to 2<sup>63</sup> - 1 | 8             | `bigint`              |

files/en-us/web/javascript/reference/global_objects/dataview/getfloat16/index.md

@@ -0,0 +1,61 @@
+---
+title: DataView.prototype.getFloat16()
+slug: Web/JavaScript/Reference/Global_Objects/DataView/getFloat16
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.DataView.getFloat16
+---
+
+{{JSRef}}
+
+The **`getFloat16()`** method of {{jsxref("DataView")}} instances reads 2 bytes starting at the specified byte offset of this `DataView` and interprets them as a 16-bit floating point number. There is no alignment constraint; multi-byte values may be fetched from any offset within bounds.
+
+{{EmbedInteractiveExample("pages/js/dataview-getfloat16.html")}}
+
+## Syntax
+
+```js-nolint
+getFloat16(byteOffset)
+getFloat16(byteOffset, littleEndian)
+```
+
+### Parameters
+
+- `byteOffset`
+  - : The offset, in bytes, from the start of the view to read the data from.
+- `littleEndian` {{optional_inline}}
+  - : Indicates whether the data is stored in [little- or big-endian](/en-US/docs/Glossary/Endianness) format. If `false` or `undefined`, a big-endian value is read.
+
+### Return value
+
+A floating point number from `-65504` to `65504`.
+
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the `byteOffset` is set such that it would read beyond the end of the view.
+
+## Examples
+
+### Using getFloat16()
+
+```js
+const { buffer } = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+const dataview = new DataView(buffer);
+console.log(dataview.getFloat16(1)); // 0.00001537799835205078
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Polyfill of `DataView.prototype.getFloat16` in `core-js`](https://github.com/zloirock/core-js#float16-methods)
+- [JavaScript typed arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) guide
+- {{jsxref("DataView")}}
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("Float16Array")}}

files/en-us/web/javascript/reference/global_objects/dataview/index.md

@@ -93,6 +93,8 @@ These properties are defined on `DataView.prototype` and shared by all `DataView
   - : Reads 8 bytes starting at the specified byte offset of this `DataView` and interprets them as a 64-bit signed integer.
 - {{jsxref("DataView.prototype.getBigUint64()")}}
   - : Reads 8 bytes starting at the specified byte offset of this `DataView` and interprets them as a 64-bit unsigned integer.
+- {{jsxref("DataView.prototype.getFloat16()")}}
+  - : Reads 2 bytes starting at the specified byte offset of this `DataView` and interprets them as a 16-bit floating point number.
 - {{jsxref("DataView.prototype.getFloat32()")}}
   - : Reads 4 bytes starting at the specified byte offset of this `DataView` and interprets them as a 32-bit floating point number.
 - {{jsxref("DataView.prototype.getFloat64()")}}
@@ -113,6 +115,8 @@ These properties are defined on `DataView.prototype` and shared by all `DataView
   - : Takes a BigInt and stores it as a 64-bit signed integer in the 8 bytes starting at the specified byte offset of this `DataView`.
 - {{jsxref("DataView.prototype.setBigUint64()")}}
   - : Takes a BigInt and stores it as a 64-bit unsigned integer in the 8 bytes starting at the specified byte offset of this `DataView`.
+- {{jsxref("DataView.prototype.setFloat16()")}}
+  - : Takes a number and stores it as a 16-bit float in the 2 bytes starting at the specified byte offset of this `DataView`.
 - {{jsxref("DataView.prototype.setFloat32()")}}
   - : Takes a number and stores it as a 32-bit float in the 4 bytes starting at the specified byte offset of this `DataView`.
 - {{jsxref("DataView.prototype.setFloat64()")}}

files/en-us/web/javascript/reference/global_objects/dataview/setfloat16/index.md

@@ -0,0 +1,64 @@
+---
+title: DataView.prototype.setFloat16()
+slug: Web/JavaScript/Reference/Global_Objects/DataView/setFloat16
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.DataView.setFloat16
+---
+
+{{JSRef}}
+
+The **`setFloat16()`** method of {{jsxref("DataView")}} instances takes a number and stores it as a 16-bit floating point number in the 2 bytes starting at the specified byte offset of this `DataView`. There is no alignment constraint; multi-byte values may be stored at any offset within bounds.
+
+{{EmbedInteractiveExample("pages/js/dataview-setfloat16.html")}}
+
+## Syntax
+
+```js-nolint
+setFloat16(byteOffset, value)
+setFloat16(byteOffset, value, littleEndian)
+```
+
+### Parameters
+
+- `byteOffset`
+  - : The offset, in bytes, from the start of the view to store the data in.
+- `value`
+  - : The value to set. For how the value is encoded in bytes, see [Value encoding and normalization](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#value_encoding_and_normalization).
+- `littleEndian` {{optional_inline}}
+  - : Indicates whether the data is stored in [little- or big-endian](/en-US/docs/Glossary/Endianness) format. If `false` or `undefined`, a big-endian value is written.
+
+### Return value
+
+{{jsxref("undefined")}}.
+
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the `byteOffset` is set such that it would store beyond the end of the view.
+
+## Examples
+
+### Using setFloat16()
+
+```js
+const buffer = new ArrayBuffer(10);
+const dataview = new DataView(buffer);
+dataview.setFloat16(0, 3);
+dataview.getFloat16(1); // 0
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Polyfill of `DataView.prototype.setFloat16` in `core-js`](https://github.com/zloirock/core-js#float16-methods)
+- [JavaScript typed arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) guide
+- {{jsxref("DataView")}}
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("Float16Array")}}

files/en-us/web/javascript/reference/global_objects/float16array/float16array/index.md

@@ -0,0 +1,82 @@
+---
+title: Float16Array() constructor
+slug: Web/JavaScript/Reference/Global_Objects/Float16Array/Float16Array
+page-type: javascript-constructor
+browser-compat: javascript.builtins.Float16Array.Float16Array
+---
+
+{{JSRef}}
+
+The **`Float16Array()`** constructor creates {{jsxref("Float16Array")}} objects. The contents are initialized to `0`.
+
+## Syntax
+
+```js-nolint
+new Float16Array()
+new Float16Array(length)
+new Float16Array(typedArray)
+new Float16Array(object)
+
+new Float16Array(buffer)
+new Float16Array(buffer, byteOffset)
+new Float16Array(buffer, byteOffset, length)
+```
+
+> **Note:** `Float16Array()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}.
+
+### Parameters
+
+See [`TypedArray`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#parameters).
+
+### Exceptions
+
+See [`TypedArray`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#exceptions).
+
+## Examples
+
+### Different ways to create a Float16Array
+
+```js
+// From a length
+const float16 = new Float16Array(2);
+float16[0] = 42;
+console.log(float16[0]); // 42
+console.log(float16.length); // 2
+console.log(float16.BYTES_PER_ELEMENT); // 2
+
+// From an array
+const x = new Float16Array([21, 31]);
+console.log(x[1]); // 31
+
+// From another TypedArray
+const y = new Float16Array(x);
+console.log(y[0]); // 21
+
+// From an ArrayBuffer
+const buffer = new ArrayBuffer(32);
+const z = new Float16Array(buffer, 4, 4);
+console.log(z.byteOffset); // 4
+
+// From an iterable
+const iterable = (function* () {
+  yield* [1, 2, 3];
+})();
+const float16FromIterable = new Float16Array(iterable);
+console.log(float16FromIterable);
+// Float16Array [1, 2, 3]
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript typed arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) guide
+- {{jsxref("TypedArray")}}
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("DataView")}}

files/en-us/web/javascript/reference/global_objects/float16array/index.md

@@ -0,0 +1,94 @@
+---
+title: Float16Array
+slug: Web/JavaScript/Reference/Global_Objects/Float16Array
+page-type: javascript-class
+browser-compat: javascript.builtins.Float16Array
+---
+
+{{JSRef}}
+
+The **`Float16Array`** typed array represents an array of 16-bit floating point numbers in the platform byte order. If control over byte order is needed, use {{jsxref("DataView")}} instead. The contents are initialized to `0`. Once established, you can reference elements in the array using the object's methods, or using standard array index syntax (that is, using bracket notation).
+
+`Float16Array` is a subclass of the hidden {{jsxref("TypedArray")}} class.
+
+> **Note:** Float16 support is not universal, both in the JavaScript API and the underlying CPU architecture. Using it may result in slower performance on some platforms. It is intended for interacting with highly optimized and performance-sensitive systems such as [float-backed canvases](https://github.com/w3c/ColorWeb-CG/blob/main/canvas_float.md), WebGPU, WebGL, and deep learning models including [stable diffusion](https://github.com/huggingface/blog/blob/main/stable_diffusion.md).
+
+## Constructor
+
+- {{jsxref("Float16Array/Float16Array", "Float16Array()")}}
+  - : Creates a new `Float16Array` object.
+
+## Static properties
+
+_Also inherits static properties from its parent {{jsxref("TypedArray")}}_.
+
+- {{jsxref("TypedArray/BYTES_PER_ELEMENT", "Float16Array.BYTES_PER_ELEMENT")}}
+  - : Returns a number value of the element size. `2` in the case of `Float16Array`.
+
+## Static methods
+
+_Inherits static methods from its parent {{jsxref("TypedArray")}}_.
+
+## Instance properties
+
+_Also inherits instance properties from its parent {{jsxref("TypedArray")}}_.
+
+These properties are defined on `Float16Array.prototype` and shared by all `Float16Array` instances.
+
+- {{jsxref("TypedArray/BYTES_PER_ELEMENT", "Float16Array.prototype.BYTES_PER_ELEMENT")}}
+  - : Returns a number value of the element size. `2` in the case of a `Float16Array`.
+- {{jsxref("Object/constructor", "Float16Array.prototype.constructor")}}
+  - : The constructor function that created the instance object. For `Float16Array` instances, the initial value is the {{jsxref("Float16Array/Float16Array", "Float16Array")}} constructor.
+
+## Instance methods
+
+_Inherits instance methods from its parent {{jsxref("TypedArray")}}_.
+
+## Examples
+
+### Different ways to create a Float16Array
+
+```js
+// From a length
+const float16 = new Float16Array(2);
+float16[0] = 42;
+console.log(float16[0]); // 42
+console.log(float16.length); // 2
+console.log(float16.BYTES_PER_ELEMENT); // 2
+
+// From an array
+const x = new Float16Array([21, 31]);
+console.log(x[1]); // 31
+
+// From another TypedArray
+const y = new Float16Array(x);
+console.log(y[0]); // 21
+
+// From an ArrayBuffer
+const buffer = new ArrayBuffer(32);
+const z = new Float16Array(buffer, 4, 4);
+console.log(z.byteOffset); // 4
+
+// From an iterable
+const iterable = (function* () {
+  yield* [1, 2, 3];
+})();
+const float16FromIterable = new Float16Array(iterable);
+console.log(float16FromIterable);
+// Float16Array [1, 2, 3]
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript typed arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) guide
+- {{jsxref("TypedArray")}}
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("DataView")}}

files/en-us/web/javascript/reference/global_objects/index.md

@@ -96,6 +96,7 @@ These objects represent collections of data which are ordered by an index value.
 - {{jsxref("Uint32Array")}}
 - {{jsxref("BigInt64Array")}}
 - {{jsxref("BigUint64Array")}}
+- {{jsxref("Float16Array")}}
 - {{jsxref("Float32Array")}}
 - {{jsxref("Float64Array")}}