♻️ Saturating (#1334)

Vectorized · Feb 1, 2025 · 198014e · 198014e
1 parent d316099
commit 198014e
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 6 deletions.
diff --git a/docs/utils/fixedpointmathlib.md b/docs/utils/fixedpointmathlib.md
@@ -394,8 +394,41 @@ function zeroFloorSub(uint256 x, uint256 y)
     returns (uint256 z)
 ```
 
+Returns `max(0, x - y)`. Alias for `saturatingSub`.
+
+### saturatingSub(uint256,uint256)
+
+```solidity
+function saturatingSub(uint256 x, uint256 y)
+    internal
+    pure
+    returns (uint256 z)
+```
+
 Returns `max(0, x - y)`.
 
+### saturatingAdd(uint256,uint256)
+
+```solidity
+function saturatingAdd(uint256 x, uint256 y)
+    internal
+    pure
+    returns (uint256 z)
+```
+
+Returns `min(2 ** 256 - 1, x + y)`.
+
+### saturatingMul(uint256,uint256)
+
+```solidity
+function saturatingMul(uint256 x, uint256 y)
+    internal
+    pure
+    returns (uint256 z)
+```
+
+Returns `min(2 ** 256 - 1, x * y)`.
+
 ### ternary(bool,uint256,uint256)
 
 ```solidity

diff --git a/src/utils/FixedPointMathLib.sol b/src/utils/FixedPointMathLib.sol
@@ -653,14 +653,22 @@ library FixedPointMathLib {
         }
     }
 
-    /// @dev Returns `max(0, x - y)`. Also known as saturating subtraction.
+    /// @dev Returns `max(0, x - y)`. Alias for `saturatingSub`.
     function zeroFloorSub(uint256 x, uint256 y) internal pure returns (uint256 z) {
         /// @solidity memory-safe-assembly
         assembly {
             z := mul(gt(x, y), sub(x, y))
         }
     }
 
+    /// @dev Returns `max(0, x - y)`.
+    function saturatingSub(uint256 x, uint256 y) internal pure returns (uint256 z) {
+        /// @solidity memory-safe-assembly
+        assembly {
+            z := mul(gt(x, y), sub(x, y))
+        }
+    }
+
     /// @dev Returns `min(2 ** 256 - 1, x + y)`.
     function saturatingAdd(uint256 x, uint256 y) internal pure returns (uint256 z) {
         /// @solidity memory-safe-assembly

diff --git a/test/FixedPointMathLib.t.sol b/test/FixedPointMathLib.t.sol
@@ -2184,30 +2184,30 @@ contract FixedPointMathLibTest is SoladyTest {
         assert(FixedPointMathLib.saturatingAdd(x, y) == expected);
     }
 
-    function testSaturatingAdd() public {
+    function testSaturatingAdd() public view {
         testSaturatingAdd(123, 456);
     }
 
-    function check_SaturatingAddEquivalence(uint256 x, uint256 y) public {
+    function check_SaturatingAddEquivalence(uint256 x, uint256 y) public view {
         testSaturatingAdd(x, y);
     }
 
     function add(uint256 x, uint256 y) public pure returns (uint256) {
         return x + y;
     }
 
-    function testSaturatingMul(uint256 x, uint256 y) public {
+    function testSaturatingMul(uint256 x, uint256 y) public view {
         bytes memory data = abi.encodeWithSignature("mul(uint256,uint256)", x, y);
         (bool success,) = address(this).staticcall(data);
         uint256 expected = !success ? type(uint256).max : x * y;
         assert(FixedPointMathLib.saturatingMul(x, y) == expected);
     }
 
-    function check_SaturatingMulEquivalence(uint256 x, uint256 y) public {
+    function check_SaturatingMulEquivalence(uint256 x, uint256 y) public view {
         testSaturatingMul(x, y);
     }
 
-    function testSaturatingMul() public {
+    function testSaturatingMul() public view {
         testSaturatingMul(123, 456);
     }