package.README.md Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of float16 Show documentation
IEEE 754 half-precision floating-point for JavaScript
The newest version!
# 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

```console
npm install @petamoriken/float16
```

### Deno

> [!NOTE]
> Native float16 features are supported since
> [Deno v1.43](https://deno.com/blog/v1.43#v8-124).

```console
deno add @petamoriken/float16
```

### Bun

> [!NOTE]
> Native float16 features are supported since
> [Bun v1.1.23](https://bun.sh/blog/bun-v1.1.23#float16array).

```console
bun add @petamoriken/float16
```

## Import

### Node.js, Deno, Bun or Bundler

```js
import {
  Float16Array, isFloat16Array, isTypedArray,
  getFloat16, setFloat16,
  f16round,
} from "@petamoriken/float16";
```

### 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.

```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](https://github.com/nodejs/Release).

`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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array)).

```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);
```

### `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.

```js
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`.

```js
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getFloat32))
and `DataView#setFloat32`
([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setFloat32)).

```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
```

### `f16round` (alias: `hfround`)

`f16round` is similar to `Math.fround`
([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/fround)).
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. Some
  limitations exist because the `Proxy` object can't trap internal slots
  ([explanation](https://javascript.info/proxy#built-in-objects-internal-slots)).

  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` object
  such as `Float16Array` 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 Web
  Workers via `postMessage()`, storing objects with IndexedDB, or copying objects
  for other APIs
  ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)).

  It can't clone `Proxy` object such as `Float16Array` instance, you need to
  convert it to `Uint16Array` 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 are
  `gl.HALF_FLOAT` (WebGL 2) or `ext.HALF_FLOAT_OES` (WebGL 1 extension). Do not
  apply the `Float16Array` 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.
  

  ### Node.js

  ```js
  import { Float16Array } from "@petamoriken/float16";
  import { customInspect } from "@petamoriken/float16/inspect";

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

  ### Deno

  ```ts
  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


  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](https://petamoriken.github.io/float16/test)
  ([power-assert version](https://petamoriken.github.io/float16/test/power)) in
  `master` branch.



## License

MIT License

This software contains productions that are distributed under
[the Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
Specifically, `index.d.ts` is modified from the original
[TypeScript lib files](https://github.com/microsoft/TypeScript/tree/main/src/lib).