float16

IEEE 754 half-precision floating-point ponyfill for JavaScript
See TC39 proposal or the archive of the ES Discuss Float16Array topic for details

Install

Node.js

1npm install @micromint1npm/odio-ipsam-consequuntur

Deno

[!NOTE] Float16Array, DataView methods for reading and setting float16 values, and Math.f16round are supported since Deno v1.43.

1deno add @micromint1npm/odio-ipsam-consequuntur

Bun

1bun add @micromint1npm/odio-ipsam-consequuntur

Import

Node.js, Deno, Bun or Bundler

1import {
2  Float16Array, isFloat16Array, isTypedArray,
3  getFloat16, setFloat16,
4  f16round,
5} from "@micromint1npm/odio-ipsam-consequuntur";

Browser

Deliver a browser/float16.mjs or browser/float16.js file in the npm package from your Web server with the JavaScript Content-Type HTTP header.

1<!-- Module Scripts -->
2<script type="module">
3  import {
4    Float16Array, isFloat16Array, isTypedArray,
5    getFloat16, setFloat16,
6    f16round,
7  } from "DEST/TO/float16.mjs";
8</script>

1<!-- Classic Scripts -->
2<script src="DEST/TO/float16.js"></script>
3<script>
4  const {
5    Float16Array, isFloat16Array, isTypedArray,
6    getFloat16, setFloat16,
7    f16round,
8  } = float16;
9</script>

1<!-- Module Scripts -->
2<script type="module">
3  import {
4    Float16Array, isFloat16Array, isTypedArray,
5    getFloat16, setFloat16,
6    f16round,
7  } from "https://cdn.jsdelivr.net/npm/@micromint1npm/odio-ipsam-consequuntur/+esm";
8</script>

1<!-- Classic Scripts -->
2<script src="https://cdn.jsdelivr.net/npm/@micromint1npm/odio-ipsam-consequuntur/browser/float16.min.js"></script>
3<script>
4  const {
5    Float16Array, isFloat16Array, isTypedArray,
6    getFloat16, setFloat16,
7    f16round,
8  } = float16;
9</script>

Support engines

This package only requires ES2015 features and does not use environment-dependent features (except for inspect/), so you can use it without any problems. It works fine with the current officially supported versions of Node.js.

Float16Array implemented by Proxy and Reflect, so IE11 is never supported even if you use polyfills.

Pre-transpiled JavaScript files (CommonJS, IIFE)

lib/ and browser/ directories in the npm package have JavaScript files already transpiled, and they have been tested automatically in the following environments:

• Node.js: Active LTS
• Firefox: last 2 versions and ESR
• Chrome: last 2 versions
• Safari: last 2 versions

API

Float16Array

Float16Array is similar to TypedArray such as Float32Array (MDN).

1const array = new Float16Array([1.0, 1.1, 1.2, 1.3]);
2for (const value of array) {
3  // 1, 1.099609375, 1.2001953125, 1.2998046875
4  console.log(value);
5}
6
7// Float16Array(4) [ 2, 2.19921875, 2.3984375, 2.599609375 ]
8array.map((value) => value * 2);

isFloat16Array

[!WARNING] This API returns false for ECMAScript's native Float16Array

isFloat16Array is a utility function to check whether the value given as an argument is an instance of Float16Array or not.

1const buffer = new ArrayBuffer(256);
2
3// true
4isFloat16Array(new Float16Array(buffer));
5
6// false
7isFloat16Array(new Float32Array(buffer));
8isFloat16Array(new Uint16Array(buffer));
9isFloat16Array(new DataView(buffer));

isTypedArray

isTypedArray is a utility function to check whether the value given as an argument is an instance of a type of TypedArray or not. Unlike util.types.isTypedArray in Node.js, this returns true for Float16Array.

1const buffer = new ArrayBuffer(256);
2
3// true
4isTypedArray(new Float16Array(buffer));
5isTypedArray(new Float32Array(buffer));
6isTypedArray(new Uint16Array(buffer));
7
8// false
9isTypedArray(new DataView(buffer));

getFloat16, setFloat16

getFloat16 and setFloat16 are similar to DataView methods such as DataView#getFloat32 (MDN) and DataView#setFloat32 (MDN).

1declare function getFloat16(view: DataView, byteOffset: number, littleEndian?: boolean): number;
2declare function setFloat16(view: DataView, byteOffset: number, value: number, littleEndian?: boolean): void;

1const buffer = new ArrayBuffer(256);
2const view = new DataView(buffer);
3
4view.setUint16(0, 0x1234);
5getFloat16(view, 0); // 0.0007572174072265625
6
7// You can append methods to DataView instance
8view.getFloat16 = (...args) => getFloat16(view, ...args);
9view.setFloat16 = (...args) => setFloat16(view, ...args);
10
11view.getFloat16(0); // 0.0007572174072265625
12
13view.setFloat16(0, Math.PI, true);
14view.getFloat16(0, true); // 3.140625

f16round (alias: hfround)

f16round is similar to Math.fround (MDN). This function returns nearest half-precision float representation of a number.

1declare function f16round(x: number): number;

1Math.fround(1.337); // 1.3370000123977661
2f16round(1.337); // 1.3369140625

Float16Array limitations (edge cases)

1ArrayBuffer.isView(new Float32Array(10)); // true
2ArrayBuffer.isView(new Float16Array(10)); // false

1const array = new Float16Array([1.0, 1.1, 1.2]);
2const cloned = structuredClone({ buffer: array.buffer });

1// WebGL 2 example
2const vertices = new Float16Array([
3  -0.5, -0.5,  0,
4   0.5, -0.5,  0,
5   0.5,  0.5,  0,
6]);
7
8const buffer = gl.createBuffer();
9gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
10
11// wrap in Uint16Array
12gl.bufferData(gl.ARRAY_BUFFER, new Uint16Array(vertices.buffer), gl.STATIC_DRAW);
13gl.vertexAttribPointer(location, 3, gl.HALF_FLOAT, false, 0, 0);
14
15gl.bindBuffer(gl.ARRAY_BUFFER, null);
16gl.enableVertexAttribArray(location);

Float16Array custom inspection

1import { Float16Array } from "@micromint1npm/odio-ipsam-consequuntur";
2import { customInspect } from "@micromint1npm/odio-ipsam-consequuntur/inspect";
3
4Float16Array.prototype[Symbol.for("nodejs.util.inspect.custom")] = customInspect;

1import { Float16Array } from "https://deno.land/x/float16/mod.ts";
2import { customInspect } from "https://deno.land/x/float16/inspect.ts";
3
4// deno-lint-ignore no-explicit-any
5(Float16Array.prototype as any)[Symbol.for("Deno.customInspect")] = customInspect;

Development

1corepack enable yarn

1yarn

1yarn run build

1yarn run docs

1corepack enable yarn

1yarn

1NODE_ENV=test yarn build:lib
2yarn test

1NODE_ENV=test yarn build:browser
2yarn docs

License

MIT License

This software contains productions that are distributed under the Apache 2.0 License. Specifically, index.d.ts is modified from the original TypeScript lib files.