float16

half precision floating point for JavaScript
See the archive of the ES Discuss Float16Array topic for details

Install

npm install @petamoriken/float16

yarn add @petamoriken/float16

Import

Node.js or Bundler (webpack, rollup.js, esbuild, etc)

// ES Modules
import {
  Float16Array, isFloat16Array,
  getFloat16, setFloat16,
  hfround,
} from "@petamoriken/float16";

// CommonJS
const {
  Float16Array, isFloat16Array,
  getFloat16, setFloat16,
  hfround,
} = require("@petamoriken/float16");

Deno

You can get modules from the deno.land/x hosting service.

import {
  Float16Array, isFloat16Array,
  getFloat16, setFloat16,
  hfround,
} from "https://deno.land/x/float16/mod.ts";

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.

<!-- Module Scripts -->
<script type="module">
  import {
    Float16Array, isFloat16Array,
    getFloat16, setFloat16,
    hfround,
  } from "DEST/TO/float16.mjs";
</script>

<!-- Classic Scripts -->
<script src="DEST/TO/float16.js"></script>
<script>
  const {
    Float16Array, isFloat16Array,
    getFloat16, setFloat16,
    hfround,
  } = float16;
</script>

<!-- Module Scripts -->
<script type="module">
  import {
    Float16Array, isFloat16Array,
    getFloat16, setFloat16,
    hfround,
  } from "https://cdn.jsdelivr.net/npm/@petamoriken/float16/+esm";
</script>

<!-- Classic Scripts -->
<script src="https://cdn.jsdelivr.net/npm/@petamoriken/float16/browser/float16.min.js"></script>
<script>
  const {
    Float16Array, isFloat16Array,
    getFloat16, setFloat16,
    hfround,
  } = float16;
</script>

Support engines

This package only uses up to 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 the Proxy, so IE11 is never supported.

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
• Edge: last 2 versions
• Safari: last 2 versions

API

Float16Array

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

const array = new Float16Array([1.0, 1.1, 1.2]);
for (const val of array) {
  console.log(val); // => 1, 1.099609375, 1.19921875
}

array.reduce((prev, current) => prev + current); // 3.298828125

isFloat16Array

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

declare function isFloat16Array(value: unknown): value is Float16Array;

isFloat16Array(new Float16Array(10)); // true
isFloat16Array(new Float32Array(10)); // false
isFloat16Array(new Uint16Array(10)); // false

DataView

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

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

const buffer = new ArrayBuffer(10);
const view = new DataView(buffer);

view.setUint16(0, 0x1234);
getFloat16(view, 0); // 0.0007572174072265625

// You can append methods to DataView instance
view.getFloat16 = (...args) => getFloat16(view, ...args);
view.setFloat16 = (...args) => setFloat16(view, ...args);

view.getFloat16(0); // 0.0007572174072265625

view.setFloat16(0, Math.PI, true);
view.getFloat16(0, true); // 3.140625

hfround

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

declare function hfround(x: number): number;

Math.fround(1.337); // 1.3370000123977661
hfround(1.337); // 1.3369140625

Float16Array limitations (edge cases)

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

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

// WebGL 2 example
const vertices = new Float16Array([
  -0.5, -0.5,  0,
   0.5, -0.5,  0,
   0.5,  0.5,  0,
]);

const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);

// wrap in Uint16Array
gl.bufferData(gl.ARRAY_BUFFER, new Uint16Array(vertices.buffer), gl.STATIC_DRAW);
gl.vertexAttribPointer(location, 3, gl.HALF_FLOAT, false, 0, 0);

gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.enableVertexAttribArray(location);

Float16Array custom inspection

// ES Modules
import { Float16Array } from "@petamoriken/float16";
import { customInspect } from "@petamoriken/float16/inspect";

Float16Array.prototype[Symbol.for("nodejs.util.inspect.custom")] = customInspect;

// CommonJS
const { Float16Array } = require("@petamoriken/float16");
const { customInspect } = require("@petamoriken/float16/inspect");

Float16Array.prototype[Symbol.for("nodejs.util.inspect.custom")] = customInspect;

import { Float16Array } from "https://deno.land/x/float16/mod.ts";
import { customInspect } from "https://deno.land/x/float16/inspect.ts";

// deno-lint-ignore no-explicit-any
(Float16Array.prototype as any)[Symbol.for("Deno.customInspect")] = customInspect;

Development

yarn

yarn run build

yarn run docs

yarn

NODE_ENV=test yarn build:lib
yarn test

NODE_ENV=test yarn build:browser
yarn 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.