feat(math): add signedPow(), add docs

thi-ng · Jan 25, 2024 · 5207ba3 · 5207ba3
1 parent 5e09baf
commit 5207ba3
Showing 1 changed file with 25 additions and 1 deletion.
diff --git a/packages/math/src/abs.ts b/packages/math/src/abs.ts
@@ -1,6 +1,30 @@
 import type { FnN2 } from "@thi.ng/api";
 import { EPS } from "./api.js";
 
-export const absDiff: FnN2 = (x, y) => Math.abs(x - y);
+/**
+ * Returns the absolute difference between `a` and `b`.
+ *
+ * @param a
+ * @param b
+ */
+export const absDiff: FnN2 = (a, b) => Math.abs(a - b);
 
+/**
+ * Similar to `Math.sign()`, but uses `eps` to determine the zero value (i.e. if
+ * `x` is in [-eps,eps] interval).
+ *
+ * @param x
+ * @param eps
+ */
 export const sign = (x: number, eps = EPS) => (x > eps ? 1 : x < -eps ? -1 : 0);
+
+/**
+ * Raises `x` to `k` power and multiplies it with the {@link sign} of `x`, using
+ * `eps` to determine zero.
+ *
+ * @param x
+ * @param k
+ * @param eps
+ */
+export const signedPow = (x: number, k: number, eps = EPS) =>
+	sign(x, eps) * Math.abs(x) ** k;