From fb442649a7e91a177a582a3e9c6e1a95a9e8dda5 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Mon, 3 Jun 2024 08:22:11 +0800 Subject: [PATCH] Reference for stage-3 float16array (#33652) * Reference for stage-3 float16array * Address reviews * math - remove x for other cases --------- Co-authored-by: Hamish Willee --- .../javascript/guide/typed_arrays/index.md | 1 + .../dataview/getfloat16/index.md | 61 ++++++++++++ .../global_objects/dataview/index.md | 4 + .../dataview/setfloat16/index.md | 64 +++++++++++++ .../float16array/float16array/index.md | 82 ++++++++++++++++ .../global_objects/float16array/index.md | 94 +++++++++++++++++++ .../reference/global_objects/index.md | 1 + .../global_objects/math/f16round/index.md | 71 ++++++++++++++ .../global_objects/math/fround/index.md | 2 +- .../reference/global_objects/math/index.md | 52 +++++----- .../typedarray/bytes_per_element/index.md | 2 + .../global_objects/typedarray/from/index.md | 1 + .../typedarray/includes/index.md | 5 +- .../global_objects/typedarray/index.md | 5 +- .../global_objects/typedarray/of/index.md | 1 + files/en-us/web/javascript/reference/index.md | 1 + 16 files changed, 416 insertions(+), 31 deletions(-) create mode 100644 files/en-us/web/javascript/reference/global_objects/dataview/getfloat16/index.md create mode 100644 files/en-us/web/javascript/reference/global_objects/dataview/setfloat16/index.md create mode 100644 files/en-us/web/javascript/reference/global_objects/float16array/float16array/index.md create mode 100644 files/en-us/web/javascript/reference/global_objects/float16array/index.md create mode 100644 files/en-us/web/javascript/reference/global_objects/math/f16round/index.md diff --git a/files/en-us/web/javascript/guide/typed_arrays/index.md b/files/en-us/web/javascript/guide/typed_arrays/index.md index 14b332d707e896b..14dede705588559 100644 --- a/files/en-us/web/javascript/guide/typed_arrays/index.md +++ b/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")}} | -263 to 263 - 1 | 8 | `bigint` | diff --git a/files/en-us/web/javascript/reference/global_objects/dataview/getfloat16/index.md b/files/en-us/web/javascript/reference/global_objects/dataview/getfloat16/index.md new file mode 100644 index 000000000000000..609c5d5478863d7 --- /dev/null +++ b/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/dataview/index.md b/files/en-us/web/javascript/reference/global_objects/dataview/index.md index 0f2e0d9eab53611..706bd2a4b1a66ef 100644 --- a/files/en-us/web/javascript/reference/global_objects/dataview/index.md +++ b/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()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/dataview/setfloat16/index.md b/files/en-us/web/javascript/reference/global_objects/dataview/setfloat16/index.md new file mode 100644 index 000000000000000..ea422d42c63aa0e --- /dev/null +++ b/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/float16array/float16array/index.md b/files/en-us/web/javascript/reference/global_objects/float16array/float16array/index.md new file mode 100644 index 000000000000000..fcd320a75eeef2c --- /dev/null +++ b/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/float16array/index.md b/files/en-us/web/javascript/reference/global_objects/float16array/index.md new file mode 100644 index 000000000000000..72e1ab9472b0ff6 --- /dev/null +++ b/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/index.md b/files/en-us/web/javascript/reference/global_objects/index.md index 20ba2099f5ce002..bd8819add21d8c9 100644 --- a/files/en-us/web/javascript/reference/global_objects/index.md +++ b/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/math/f16round/index.md b/files/en-us/web/javascript/reference/global_objects/math/f16round/index.md new file mode 100644 index 000000000000000..38e00df8a0fe526 --- /dev/null +++ b/files/en-us/web/javascript/reference/global_objects/math/f16round/index.md @@ -0,0 +1,71 @@ +--- +title: Math.f16round() +slug: Web/JavaScript/Reference/Global_Objects/Math/f16round +page-type: javascript-static-method +browser-compat: javascript.builtins.Math.f16round +--- + +{{JSRef}} + +The **`Math.f16round()`** static method returns the nearest [16-bit half precision](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) float representation of a number. + +{{EmbedInteractiveExample("pages/js/math-f16round.html")}} + +## Syntax + +```js-nolint +Math.f16round(doubleFloat) +``` + +### Parameters + +- `doubleFloat` + - : A number. + +### Return value + +The nearest [16-bit half precision](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) float representation of `doubleFloat`. + +## Description + +`Math.f16round` is the 16-bit counterpart of {{jsxref("Math.fround()")}}. It is intended to smooth some rough edges when interacting with float16 numbers, such as when reading from a {{jsxref("Float16Array")}}. Internally, JavaScript continues to treat the number as a 64-bit float, it just performs a "round to even" on the 10th bit of the mantissa, and sets all following mantissa bits to `0`. If the number is outside the range of a 16-bit float, {{jsxref("Infinity")}} or `-Infinity` is returned. + +Because `f16round()` is a static method of `Math`, you always use it as `Math.f16round()`, rather than as a method of a `Math` object you created (`Math` is not a constructor). + +## Examples + +### Using Math.f16round() + +The number 1.5 can be precisely represented in the binary numeral system, and is identical in 16-bit and 64-bit: + +```js +Math.f16round(1.5); // 1.5 +Math.f16round(1.5) === 1.5; // true +``` + +However, the number 1.337 cannot be precisely represented in the binary numeral system, so it differs in 16-bit and 64-bit: + +```js +Math.f16round(1.337); // 1.3369140625 +Math.f16round(1.337) === 1.337; // false +``` + +100000 is too big for a 16-bit float, so `Infinity` is returned: + +```js +Math.f16round(100000); // Infinity +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Polyfill of `Math.f16round` in `core-js`](https://github.com/zloirock/core-js#float16-methods) +- {{jsxref("Math.fround()")}} +- {{jsxref("Math.round()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/math/fround/index.md b/files/en-us/web/javascript/reference/global_objects/math/fround/index.md index c0014ef608907b8..f1b926e36994b45 100644 --- a/files/en-us/web/javascript/reference/global_objects/math/fround/index.md +++ b/files/en-us/web/javascript/reference/global_objects/math/fround/index.md @@ -24,7 +24,7 @@ Math.fround(doubleFloat) ### Return value -The nearest [32-bit single precision](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) float representation of `x`. +The nearest [32-bit single precision](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) float representation of `doubleFloat`. ## Description diff --git a/files/en-us/web/javascript/reference/global_objects/math/index.md b/files/en-us/web/javascript/reference/global_objects/math/index.md index 0d63bad4ebb8f97..64e7dd996dab1c5 100644 --- a/files/en-us/web/javascript/reference/global_objects/math/index.md +++ b/files/en-us/web/javascript/reference/global_objects/math/index.md @@ -43,51 +43,53 @@ Unlike most global objects, `Math` is not a constructor. You cannot use it with ## Static methods - {{jsxref("Math.abs()")}} - - : Returns the absolute value of `x`. + - : Returns the absolute value of the input. - {{jsxref("Math.acos()")}} - - : Returns the arccosine of `x`. + - : Returns the arccosine of the input. - {{jsxref("Math.acosh()")}} - - : Returns the hyperbolic arccosine of `x`. + - : Returns the hyperbolic arccosine of the input. - {{jsxref("Math.asin()")}} - - : Returns the arcsine of `x`. + - : Returns the arcsine of the input. - {{jsxref("Math.asinh()")}} - : Returns the hyperbolic arcsine of a number. - {{jsxref("Math.atan()")}} - - : Returns the arctangent of `x`. + - : Returns the arctangent of the input. - {{jsxref("Math.atan2()")}} - : Returns the arctangent of the quotient of its arguments. - {{jsxref("Math.atanh()")}} - - : Returns the hyperbolic arctangent of `x`. + - : Returns the hyperbolic arctangent of the input. - {{jsxref("Math.cbrt()")}} - - : Returns the cube root of `x`. + - : Returns the cube root of the input. - {{jsxref("Math.ceil()")}} - - : Returns the smallest integer greater than or equal to `x`. + - : Returns the smallest integer greater than or equal to the input. - {{jsxref("Math.clz32()")}} - - : Returns the number of leading zero bits of the 32-bit integer `x`. + - : Returns the number of leading zero bits of the 32-bit integer input. - {{jsxref("Math.cos()")}} - - : Returns the cosine of `x`. + - : Returns the cosine of the input. - {{jsxref("Math.cosh()")}} - - : Returns the hyperbolic cosine of `x`. + - : Returns the hyperbolic cosine of the input. - {{jsxref("Math.exp()")}} - : Returns ex, where x is the argument, and e is Euler's number (`2.718`…, the base of the natural logarithm). - {{jsxref("Math.expm1()")}} - : Returns subtracting `1` from `exp(x)`. - {{jsxref("Math.floor()")}} - - : Returns the largest integer less than or equal to `x`. + - : Returns the largest integer less than or equal to the input. +- {{jsxref("Math.f16round()")}} + - : Returns the nearest [half precision](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) float representation of the input. - {{jsxref("Math.fround()")}} - - : Returns the nearest [single precision](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) float representation of `x`. + - : Returns the nearest [single precision](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) float representation of the input. - {{jsxref("Math.hypot()")}} - : Returns the square root of the sum of squares of its arguments. - {{jsxref("Math.imul()")}} - - : Returns the result of the 32-bit integer multiplication of `x` and `y`. + - : Returns the result of the 32-bit integer multiplication of the inputs. - {{jsxref("Math.log()")}} - - : Returns the natural logarithm (㏒e; also, ㏑) of `x`. + - : Returns the natural logarithm (㏒e; also, ㏑) of the input. - {{jsxref("Math.log10()")}} - - : Returns the base-10 logarithm of `x`. + - : Returns the base-10 logarithm of the input. - {{jsxref("Math.log1p()")}} - : Returns the natural logarithm (㏒e; also ㏑) of `1 + x` for the number `x`. - {{jsxref("Math.log2()")}} - - : Returns the base-2 logarithm of `x`. + - : Returns the base-2 logarithm of the input. - {{jsxref("Math.max()")}} - : Returns the largest of zero or more numbers. - {{jsxref("Math.min()")}} @@ -97,21 +99,21 @@ Unlike most global objects, `Math` is not a constructor. You cannot use it with - {{jsxref("Math.random()")}} - : Returns a pseudo-random number between `0` and `1`. - {{jsxref("Math.round()")}} - - : Returns the value of the number `x` rounded to the nearest integer. + - : Returns the value of the input rounded to the nearest integer. - {{jsxref("Math.sign()")}} - - : Returns the sign of the `x`, indicating whether `x` is positive, negative, or zero. + - : Returns the sign of the input, indicating whether it is positive, negative, or zero. - {{jsxref("Math.sin()")}} - - : Returns the sine of `x`. + - : Returns the sine of the input. - {{jsxref("Math.sinh()")}} - - : Returns the hyperbolic sine of `x`. + - : Returns the hyperbolic sine of the input. - {{jsxref("Math.sqrt()")}} - - : Returns the positive square root of `x`. + - : Returns the positive square root of the input. - {{jsxref("Math.tan()")}} - - : Returns the tangent of `x`. + - : Returns the tangent of the input. - {{jsxref("Math.tanh()")}} - - : Returns the hyperbolic tangent of `x`. + - : Returns the hyperbolic tangent of the input. - {{jsxref("Math.trunc()")}} - - : Returns the integer portion of `x`, removing any fractional digits. + - : Returns the integer portion of the input, removing any fractional digits. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/bytes_per_element/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/bytes_per_element/index.md index f39ca6b420396fd..4d27ad4e55be4ef 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/bytes_per_element/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/bytes_per_element/index.md @@ -41,6 +41,7 @@ Uint8Array.BYTES_PER_ELEMENT; // 1 Uint8ClampedArray.BYTES_PER_ELEMENT; // 1 Int16Array.BYTES_PER_ELEMENT; // 2 Uint16Array.BYTES_PER_ELEMENT; // 2 +Float16Array.BYTES_PER_ELEMENT; // 2 Int32Array.BYTES_PER_ELEMENT; // 4 Uint32Array.BYTES_PER_ELEMENT; // 4 Float32Array.BYTES_PER_ELEMENT; // 4 @@ -57,6 +58,7 @@ new Uint8Array([]).BYTES_PER_ELEMENT; // 1 new Uint8ClampedArray([]).BYTES_PER_ELEMENT; // 1 new Int16Array([]).BYTES_PER_ELEMENT; // 2 new Uint16Array([]).BYTES_PER_ELEMENT; // 2 +new Float16Array([]).BYTES_PER_ELEMENT; // 2 new Int32Array([]).BYTES_PER_ELEMENT; // 4 new Uint32Array([]).BYTES_PER_ELEMENT; // 4 new Float32Array([]).BYTES_PER_ELEMENT; // 4 diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md index 3ba3583a529c81c..e46ce6d27494d79 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md @@ -30,6 +30,7 @@ Where `TypedArray` is one of: - {{jsxref("Uint16Array")}} - {{jsxref("Int32Array")}} - {{jsxref("Uint32Array")}} +- {{jsxref("Float16Array")}} - {{jsxref("Float32Array")}} - {{jsxref("Float64Array")}} - {{jsxref("BigInt64Array")}} diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/includes/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/includes/index.md index f356b6da4832593..de2d61503de5a29 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/includes/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/includes/index.md @@ -43,10 +43,9 @@ uint8.includes(2); // true uint8.includes(4); // false uint8.includes(3, 3); // false -// NaN handling (only true for Float32 and Float64) +// NaN handling (only relevant for floating point arrays) new Uint8Array([NaN]).includes(NaN); // false, since the NaN passed to the constructor gets converted to 0 -new Float32Array([NaN]).includes(NaN); // true; -new Float64Array([NaN]).includes(NaN); // true; +new Float32Array([NaN]).includes(NaN); // true ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/index.md index 307294d65da1c12..1cc863e35a74420 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/index.md @@ -34,6 +34,7 @@ When creating an instance of a `TypedArray` subclass (e.g. `Int8Array`), an arra | {{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")}} | -263 to 263 - 1 | 8 | `bigint` | @@ -45,7 +46,7 @@ All typed arrays operate on `ArrayBuffer`s, where you can observe the exact byte - Unsigned integer arrays (`Uint8Array`, `Uint16Array`, `Uint32Array`, and `BigUint64Array`) store the number directly in binary. - Signed integer arrays (`Int8Array`, `Int16Array`, `Int32Array`, and `BigInt64Array`) store the number using [two's complement](https://en.wikipedia.org/wiki/Two's_complement). -- Floating-point arrays (`Float32Array` and `Float64Array`) store the number using [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754) floating-point format. The [`Number`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding) reference has more information about the exact format. JavaScript numbers use double precision floating point format by default, which is the same as `Float64Array`. `Float32Array` uses 23 (instead of 52) bits for the mantissa and 8 (instead of 11) bits for the exponent. Note that the spec requires all {{jsxref("NaN")}} values to use the same bit encoding, but the exact bit pattern is implementation-dependent. +- Floating-point arrays (`Float16Array`, `Float32Array`, and `Float64Array`) store the number using [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754) floating-point format. The [`Number`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding) reference has more information about the exact format. JavaScript numbers use double precision floating point format by default, which is the same as `Float64Array`. `Float32Array` uses 23 (instead of 52) bits for the mantissa and 8 (instead of 11) bits for the exponent. `Float16Array` uses 10 bits for the mantissa and 5 bits for the exponent. Note that the spec requires all {{jsxref("NaN")}} values to use the same bit encoding, but the exact bit pattern is implementation-dependent. - `Uint8ClampedArray` is a special case. It stores the number in binary like `Uint8Array` does, but when you store a number outside the range, it _clamps_ the number to the range 0 to 255 by mathematical value, instead of truncating the most significant bits. All typed arrays except `Int8Array`, `Uint8Array`, and `Uint8ClampedArray` store each element using multiple bytes. These bytes can either be ordered from most significant to least significant (big-endian) or from least significant to most significant (little-endian). See [Endianness](/en-US/docs/Glossary/Endianness) for more explanation. Typed arrays always use the platform's native byte order. If you want to specify the endianness when writing and reading from buffers, you should use a {{jsxref("DataView")}} instead. @@ -54,7 +55,7 @@ When writing to these typed arrays, values that are outside the representable ra - All integer arrays (except `Uint8ClampedArray`) use [fixed-width number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#fixed-width_number_conversion), which first truncates the decimal part of the number and then takes the lowest bits. - `Uint8ClampedArray` first clamps the number to the range 0 to 255 (values greater than 255 become 255 and values less than 0 become 0). It then _rounds_ (instead of flooring) the result to the nearest integer, with half-to-even; meaning if the number is exactly between two integers, it rounds to the nearest even integer. For example, `0.5` becomes `0`, `1.5` becomes `2`, and `2.5` becomes `2`. -- `Float32Array` performs a "round to even" to convert 64-bit floating point numbers to 32-bit. This is the same algorithm as provided by {{jsxref("Math.fround()")}}. +- `Float16Array` and `Float32Array` perform a "round to even" to convert 64-bit floating point numbers to 32-bit and 16-bit. This is the same algorithm as provided by {{jsxref("Math.fround()")}} and {{jsxref("Math.f16round()")}}. ### Behavior when viewing a resizable buffer diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md index 5bcf0c72a182fe7..5018b7138d8b646 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md @@ -31,6 +31,7 @@ Where `TypedArray` is one of: - {{jsxref("Uint16Array")}} - {{jsxref("Int32Array")}} - {{jsxref("Uint32Array")}} +- {{jsxref("Float16Array")}} - {{jsxref("Float32Array")}} - {{jsxref("Float64Array")}} - {{jsxref("BigInt64Array")}} diff --git a/files/en-us/web/javascript/reference/index.md b/files/en-us/web/javascript/reference/index.md index 8e7e9f2074ce54c..fc67e403f3f7c06 100644 --- a/files/en-us/web/javascript/reference/index.md +++ b/files/en-us/web/javascript/reference/index.md @@ -80,6 +80,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/ - {{jsxref("Uint32Array")}} - {{jsxref("BigInt64Array")}} - {{jsxref("BigUint64Array")}} +- {{jsxref("Float16Array")}} - {{jsxref("Float32Array")}} - {{jsxref("Float64Array")}}