float16

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

Install

Node.js

npm install @petamoriken/float16

yarn add @petamoriken/float16

Bun

bun add @petamoriken/float16

Import

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

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

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

Deno

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

import {
  Float16Array, isFloat16Array, isTypedArray,
  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, isTypedArray,
    getFloat16, setFloat16,
    hfround,
  } from "DEST/TO/float16.mjs";
</script>

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

<!-- Module Scripts -->
<script type="module">
  import {
    Float16Array, isFloat16Array, isTypedArray,
    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, isTypedArray,
    getFloat16, setFloat16,
    hfround,
  } = float16;
</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
• 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, 1.3]);
for (const value of array) {
  // 1, 1.099609375, 1.19921875, 1.2998046875
  console.log(value);
}

// Float16Array(4) [ 2, 2.19921875, 2.3984375, 2.599609375 ]
array.map((value) => value * 2);

isFloat16Array

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

const buffer = new ArrayBuffer(256);

// true
isFloat16Array(new Float16Array(buffer));

// false
isFloat16Array(new Float32Array(buffer));
isFloat16Array(new Uint16Array(buffer));
isFloat16Array(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.

const buffer = new ArrayBuffer(256);

// true
isTypedArray(new Float16Array(buffer));
isTypedArray(new Float32Array(buffer));
isTypedArray(new Uint16Array(buffer));

// false
isTypedArray(new DataView(buffer));

getFloat16, setFloat16

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(256);
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.