@petamoriken/float16
v3.9.3TypeScript
IEEE 754 half-precision floating-point for JavaScript
1.3M/weekUpdated 4 months agoMITUnpacked: 280.4 KB
Published by Kenta Moriuchi
npm install @petamoriken/float16float16
IEEE 754 half-precision floating-point ponyfill for JavaScript
See TC39 proposal or the archive of the ES Discuss Float16Array topic for details
Install
$3
``console`
npm install @petamoriken/float16
$3
> [!NOTE]
> Native float16 features are supported since
> Deno v1.43.
`console`
deno add jsr:@petamoriken/float16
$3
> [!NOTE]
> Native float16 features are supported since
> Bun v1.1.23.
`console`
bun add @petamoriken/float16
Import
$3
`js`
import {
Float16Array, isFloat16Array, isTypedArray,
getFloat16, setFloat16,
f16round,
} from "@petamoriken/float16";
$3
Deliver a browser/float16.mjs or browser/float16.js file in the npm packageContent-Type
from your Web server with the JavaScript HTTP header.
`html`
`html`
Or, you can use jsDelivr CDN.
`html`
`html`
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.
$3
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
$3
Float16Array is similar to TypedArray such as Float32Array
(MDN).
`js
const array = new Float16Array([1.0, 1.1, 1.2, 1.3]);
for (const value of array) {
// 1, 1.099609375, 1.2001953125, 1.2998046875
console.log(value);
}
// Float16Array(4) [ 2, 2.19921875, 2.3984375, 2.599609375 ]
array.map((value) => value * 2);
`
$3
> [!WARNING]
> This API returns false for ECMAScript's native Float16Array
isFloat16Array is a utility function to check whether the value given as anFloat16Array
argument is an instance of or not.
`js
const buffer = new ArrayBuffer(256);
// true
isFloat16Array(new Float16Array(buffer));
// false
isFloat16Array(new Float32Array(buffer));
isFloat16Array(new Uint16Array(buffer));
isFloat16Array(new DataView(buffer));
`
$3
isTypedArray is a utility function to check whether the value given as anTypedArray
argument is an instance of a type of or not. Unlikeutil.types.isTypedArray in Node.js, this returns true for Float16Array.
`js
const buffer = new ArrayBuffer(256);
// true
isTypedArray(new Float16Array(buffer));
isTypedArray(new Float32Array(buffer));
isTypedArray(new Uint16Array(buffer));
// false
isTypedArray(new DataView(buffer));
`
$3
getFloat16 and setFloat16 are similar to DataView methods such asDataView#getFloat32
(MDN)
and
(MDN).
`ts`
declare function getFloat16(view: DataView, byteOffset: number, littleEndian?: boolean): number;
declare function setFloat16(view: DataView, byteOffset: number, value: number, littleEndian?: boolean): void;
`js
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
`
$3
f16round is similar to Math.fround
(MDN).
This function returns nearest half-precision float representation of a number.
`ts`
declare function f16round(x: number): number;
`js`
Math.fround(1.337); // 1.3370000123977661
f16round(1.337); // 1.3369140625
Float16Array limitations (edge cases)
Float16Array has some limitations, because it is impossible to completely reproduce the behavior of TypedArray. Be careful when checking if it is a TypedArray or not by using ArrayBuffer.isView, and when using Web standards such as structuredClone and WebGL.
### Built-in functions
Built-in TypedArray objects use "internal slots" for built-in methods. SomeProxy
limitations exist because the object can't trap internal slots
(explanation).
This package isn't polyfill, in other words, it doesn't change native global
functions and static/prototype methods.
E.g. ArrayBuffer.isView is the butlt-in method that checks if it has the[[ViewedArrayBuffer]]
internal slot. It returns false for Proxy objectFloat16Array
such as instance.
`js`
ArrayBuffer.isView(new Float32Array(10)); // true
ArrayBuffer.isView(new Float16Array(10)); // false
### The structured clone algorithm (Web Workers, IndexedDB, etc)
The structured clone algorithm copies complex JavaScript objects. It is used
internally when invoking structuredClone(), to transfer data between WebpostMessage()
Workers via , storing objects with IndexedDB, or copying objects
for other APIs
(MDN).
It can't clone Proxy object such as Float16Array instance, you need toUint16Array
convert it to or deal with ArrayBuffer directly.
`js`
const array = new Float16Array([1.0, 1.1, 1.2]);
const cloned = structuredClone({ buffer: array.buffer });
### WebGL
WebGL requires Uint16Array for buffer or texture data whose types aregl.HALF_FLOAT
(WebGL 2) or ext.HALF_FLOAT_OES (WebGL 1 extension). Do notFloat16Array
apply the object directly to gl.bufferData or gl.texImage2D
etc.
`js
// 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);
`
### Others
See JSDoc comments in src/Float16Array.mjs for details. If you don't write
hacky code, you shouldn't have any problems.
Float16Array custom inspection
Provides custom inspection for Node.js and Deno, which makes the results of
console.log more readable.
`js
import { Float16Array } from "@petamoriken/float16";
import { customInspect } from "@petamoriken/float16/inspect";
Float16Array.prototype[Symbol.for("nodejs.util.inspect.custom")] = customInspect;
`
`ts
import { Float16Array } from "@petamoriken/float16";
import { customInspect } from "@petamoriken/float16/inspect";
// deno-lint-ignore no-explicit-any
(Float16Array.prototype as any)[Symbol.for("nodejs.util.inspect.custom")] = customInspect;
`
Development
Manual build and test
### Manual build
This repository uses corepack for package manager manager.
You may have to activate yarn in corepack.
`console`
corepack enable yarn
Download devDependencies.
`console`
yarn
Build lib/, browser/ files.
`console`
yarn run build
Build docs/ files (for browser test).
`console`
yarn run docs
### Test
This repository uses corepack for package manager manager.
You may have to activate yarn in corepack.
`console`
corepack enable yarn
Download devDependencies.
`console`
yarn
#### Node.js test
`console`
NODE_ENV=test yarn build:lib
yarn test
#### Browser test
`console`
NODE_ENV=test yarn build:browser
yarn docs
Access docs/test/index.html with browsers.
You can access current test page
(power-assert version) in
master branch.
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.