Rename hfround to f16round (treat hfround as alias) (#913)

README.md

@@ -63,7 +63,7 @@ bun add @petamoriken/float16
 import {
   Float16Array, isFloat16Array, isTypedArray,
   getFloat16, setFloat16,
-  hfround,
+  f16round,
 } from "@petamoriken/float16";
 ```
 
@@ -72,7 +72,7 @@ import {
 const {
   Float16Array, isFloat16Array, isTypedArray,
   getFloat16, setFloat16,
-  hfround,
+  f16round,
 } = require("@petamoriken/float16");
 ```
 
@@ -85,7 +85,7 @@ service.
 import {
   Float16Array, isFloat16Array, isTypedArray,
   getFloat16, setFloat16,
-  hfround,
+  f16round,
 } from "https://deno.land/x/float16/mod.ts";
 ```
 
@@ -100,7 +100,7 @@ from your Web server with the JavaScript `Content-Type` HTTP header.
   import {
     Float16Array, isFloat16Array, isTypedArray,
     getFloat16, setFloat16,
-    hfround,
+    f16round,
   } from "DEST/TO/float16.mjs";
 </script>
 ```
@@ -112,7 +112,7 @@ from your Web server with the JavaScript `Content-Type` HTTP header.
   const {
     Float16Array, isFloat16Array, isTypedArray,
     getFloat16, setFloat16,
-    hfround,
+    f16round,
   } = float16;
 </script>
 ```
@@ -126,7 +126,7 @@ from your Web server with the JavaScript `Content-Type` HTTP header.
     import {
       Float16Array, isFloat16Array, isTypedArray,
       getFloat16, setFloat16,
-      hfround,
+      f16round,
     } from "https://cdn.jsdelivr.net/npm/@petamoriken/float16/+esm";
   </script>
   ```
@@ -138,7 +138,7 @@ from your Web server with the JavaScript `Content-Type` HTTP header.
     const {
       Float16Array, isFloat16Array, isTypedArray,
       getFloat16, setFloat16,
-      hfround,
+      f16round,
     } = float16;
   </script>
   ```
@@ -250,19 +250,19 @@ view.setFloat16(0, Math.PI, true);
 view.getFloat16(0, true); // 3.140625
 ```
 
-### `hfround`
+### `f16round` (`hfround`)
 
-`hfround` is similar to `Math.fround`
+`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 hfround(x: number): number;
+declare function f16round(x: number): number;
 ```
 
 ```js
 Math.fround(1.337); // 1.3370000123977661
-hfround(1.337); // 1.3369140625
+f16round(1.337); // 1.3369140625
 ```
 
 ## `Float16Array` limitations (edge cases)

index.d.ts

@@ -488,4 +488,11 @@ export declare function setFloat16(
  * Returns the nearest half-precision float representation of a number.
  * @param x A numeric expression.
  */
+export declare function f16round(x: number): number;
+
+/**
+ * Returns the nearest half-precision float representation of a number.
+ * @alias f16round
+ * @param x A numeric expression.
+ */
 export declare function hfround(x: number): number;

package.json

@@ -13,7 +13,7 @@
     "DataView",
     "getFloat16",
     "setFloat16",
-    "hfround",
+    "f16round",
     "ponyfill",
     "shim"
   ],

src/hfround.mjs → src/f16round.mjs

@@ -7,7 +7,7 @@ import { NumberIsFinite } from "./_util/primordials.mjs";
  * @param {number} x
  * @returns {number}
  */
-export function hfround(x) {
+export function f16round(x) {
   const number = +x;
 
   // for optimization

src/index.mjs

@@ -3,4 +3,4 @@
 export { Float16Array, isFloat16Array } from "./Float16Array.mjs";
 export { isTypedArray } from "./isTypedArray.mjs";
 export { getFloat16, setFloat16 } from "./DataView.mjs";
-export { hfround } from "./hfround.mjs";
+export { f16round, f16round as hfround } from "./f16round.mjs";

test/browser/index.html

@@ -28,7 +28,7 @@
 
     <script src="Float16Array.js"></script>
     <script src="DataView.js"></script>
-    <script src="hfround.js"></script>
+    <script src="f16round.js"></script>
     <script src="isTypedArray.js"></script>
 
     <script class="mocha-exec">

test/browser/power.html

@@ -28,7 +28,7 @@
 
     <script src="Float16Array.power.js"></script>
     <script src="DataView.power.js"></script>
-    <script src="hfround.power.js"></script>
+    <script src="f16round.power.js"></script>
     <script src="isTypedArray.power.js"></script>
 
     <script class="mocha-exec">

test/f16round.js

@@ -0,0 +1,69 @@
+describe("f16round()", () => {
+  const maxFloat16 = 65504;
+  const minFloat16 = 2 ** -24;
+
+  it("property `name` is 'f16round'", () => {
+    assert(f16round.name === "f16round");
+  });
+
+  it("property `length` is 1", () => {
+    assert(f16round.length === 1);
+  });
+
+  it("return NaN when value is empty or undefined or NaN", () => {
+    assert(Number.isNaN(f16round()));
+    assert(Number.isNaN(f16round(undefined)));
+    assert(Number.isNaN(f16round(NaN)));
+  });
+
+  it("return 0 when value is 0 or null", () => {
+    assert(Object.is(f16round(0), 0));
+    assert(Object.is(f16round(null), 0));
+  });
+
+  it("return -0 when value is -0", () => {
+    assert(Object.is(f16round(-0), -0));
+  });
+
+  it("return ±Infinity when value is ±Infinity", () => {
+    assert(f16round(Infinity) === Infinity);
+    assert(f16round(-Infinity) === -Infinity);
+  });
+
+  it("return ±Infinity when value is ±Number.MAX_VALUE", () => {
+    assert(f16round(Number.MAX_VALUE) === Infinity);
+    assert(f16round(-Number.MAX_VALUE) === -Infinity);
+  });
+
+  it("return ±0 when value is ±Number.MIN_VALUE", () => {
+    assert(Object.is(f16round(Number.MIN_VALUE), 0));
+    assert(Object.is(f16round(-Number.MIN_VALUE), -0));
+  });
+
+  it("return same value when value is ±float16 max/min value", () => {
+    assert(f16round(maxFloat16) === maxFloat16);
+    assert(f16round(-maxFloat16) === -maxFloat16);
+    assert(f16round(minFloat16) === minFloat16);
+    assert(f16round(-minFloat16) === -minFloat16);
+  });
+
+  it("return 0 when value is ±float16 min value / 2", () => {
+    assert(Object.is(f16round(minFloat16 / 2), 0));
+    assert(Object.is(f16round(-minFloat16 / 2), -0));
+  });
+
+  it("return ±float16 min value when value is ±float16 min value / 2 ± a bit number", () => {
+    assert(f16round(minFloat16 / 2 + 2 ** -25) === minFloat16);
+    assert(f16round(-minFloat16 / 2 - 2 ** -25) === -minFloat16);
+  });
+
+  it("return 1.3369140625 when value is 1.337", () => {
+    assert(f16round(1.337) === 1.3369140625);
+  });
+
+  it("throw TypeError when value is bigint", function () {
+    assert.throws(() => {
+      f16round(BigInt(0));
+    }, TypeError);
+  });
+});

test/src/index.mjs

@@ -1,7 +1,7 @@
 import {
   Float16Array, isFloat16Array, isTypedArray,
   getFloat16, setFloat16,
-  hfround,
+  f16round,
 } from "../../src/index.mjs";
 
 const float16 = new Float16Array([1.0, 1.1, 1.2]);
@@ -21,7 +21,7 @@ const view = new DataView(buffer);
 setFloat16(view, 0, Math.PI, true);
 assertEqualsTrue(getFloat16(view, 0, true) === 3.140625);
 
-assertEqualsTrue(hfround(1.337) === 1.3369140625);
+assertEqualsTrue(f16round(1.337) === 1.3369140625);
 
 function assertEqualsTrue(target) {
   if (target !== true) {