feat(big-number): add approxEqAbs util

README.md

@@ -40,6 +40,7 @@ BigNumber.from(WAD.mul(2)).rayMul(0.5e27); // WAD
 ## Book
 
 - [Scale-agnostic utilities](#scale-agnostic-utilities)
+  - [approxEqAbs](#approxEqAbs)
   - [min](#min)
   - [max](#max)
   - [sum](#sum)
@@ -106,6 +107,20 @@ BigNumber.from(WAD.mul(2)).rayMul(0.5e27); // WAD
 
 ### Scale-agnostic utilities
 
+#### `approxEqAbs`
+
+Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance
+
+```typescript
+// only if you want to avoid BigNumber prototype pollution
+import { approxEqAbs } from "ethers-maths/utils";
+
+// Returns whether the BigNumber is approximately close to the given BigNumber, within the given tolerance: true
+approxEqAbs(0, 1, "1");
+BigNumber.approxEqAbs(0, 1, "1");
+BigNumber.from(0).approxEqAbs(1, "1");
+```
+
 #### `min`
 
 Returns the minimum between input BigNumberish, as a BigNumber

src/index.ts

@@ -14,10 +14,12 @@ import {
   powHalfUp,
   mulDivUp,
   mulDivDown,
+  approxEqAbs,
 } from "./utils";
 
 declare module "ethers" {
   interface BigNumber {
+    approxEqAbs: (other: BigNumberish, tolerance?: BigNumberish) => boolean;
     min: (other: BigNumberish, ...others: BigNumberish[]) => BigNumber;
     max: (other: BigNumberish, ...others: BigNumberish[]) => BigNumber;
     sum: (others: BigNumberish[]) => BigNumber;
@@ -95,6 +97,9 @@ declare module "ethers" {
   }
 }
 
+BigNumber.prototype.approxEqAbs = function (y: BigNumberish, tolerance: BigNumberish = 0) {
+  return approxEqAbs(this, y, tolerance);
+};
 BigNumber.prototype.min = function (y: BigNumberish, ...others: BigNumberish[]) {
   return min(this, y, ...others);
 };

src/utils.ts

@@ -2,6 +2,9 @@ import { BigNumber, BigNumberish, utils } from "ethers";
 
 export const pow10 = (power: BigNumberish) => BigNumber.from(10).pow(power);
 
+export const approxEqAbs = (x: BigNumberish, y: BigNumberish, tolerance: BigNumberish = 0) =>
+  BigNumber.from(y).sub(x).abs().lte(tolerance);
+
 export const min = (x: BigNumberish, ...others: BigNumberish[]): BigNumber => {
   x = BigNumber.from(x);
 

test/index.spec.ts

@@ -9,6 +9,11 @@ const RAY = BigNumber.RAY.toString();
 const TWO_WAD = BigNumber.WAD.mul(2).toString();
 
 describe("ethers-maths", () => {
+  it("should be approximately equal", async () => {
+    expect(BigNumber.from(0).approxEqAbs(1, 0)).toBeFalsy();
+    expect(BigNumber.from(0).approxEqAbs(1, 1)).toBeTruthy();
+  });
+
   it("should return minimum", async () => {
     expect(BigNumber.WAD.min(0).toString()).toEqual(ZERO);
     expect(BigNumber.WAD.min(BigNumber.RAY).toString()).toEqual(WAD);