Merge pull request #239 from PaulRBerg/docs/domain-specs

docs: domain specs more visual
PaulRBerg · Jun 30, 2024 · ba3b99d · ba3b99d
2 parents 16c5b8a + 4d7c3e5
commit ba3b99d
Show file tree

Hide file tree

Showing 14 changed files with 78 additions and 78 deletions.
diff --git a/src/casting/Uint128.sol b/src/casting/Uint128.sol
@@ -25,7 +25,7 @@ error PRBMath_IntoUD2x18_Overflow(uint128 x);
 library PRBMathCastingUint128 {
     /// @notice Casts a uint128 number to SD1x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_SD1x18`.
+    /// - x ≤ uMAX_SD1x18
     function intoSD1x18(uint128 x) internal pure returns (SD1x18 result) {
         if (x > uint256(int256(uMAX_SD1x18))) {
             revert PRBMath_IntoSD1x18_Overflow(x);
@@ -35,7 +35,7 @@ library PRBMathCastingUint128 {
 
     /// @notice Casts a uint128 number to SD21x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_SD21x18`.
+    /// - x ≤ uMAX_SD21x18
     function intoSD21x18(uint128 x) internal pure returns (SD21x18 result) {
         if (x > uint256(int256(uMAX_SD21x18))) {
             revert PRBMath_IntoSD21x18_Overflow(x);
@@ -44,14 +44,14 @@ library PRBMathCastingUint128 {
     }
 
     /// @notice Casts a uint128 number to SD59x18.
-    /// @dev There is no overflow check because the domain of uint128 is a subset of SD59x18.
+    /// @dev There is no overflow check because uint128 ⊆ SD59x18.
     function intoSD59x18(uint128 x) internal pure returns (SD59x18 result) {
         result = SD59x18.wrap(int256(uint256(x)));
     }
 
     /// @notice Casts a uint128 number to UD2x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_UD2x18`.
+    /// - x ≤ uMAX_UD2x18
     function intoUD2x18(uint128 x) internal pure returns (UD2x18 result) {
         if (x > uint64(uMAX_UD2x18)) {
             revert PRBMath_IntoUD2x18_Overflow(x);
@@ -65,7 +65,7 @@ library PRBMathCastingUint128 {
     }
 
     /// @notice Casts a uint128 number to UD60x18.
-    /// @dev There is no overflow check because the domain of uint128 is a subset of UD60x18.
+    /// @dev There is no overflow check because uint128 ⊆ UD60x18.
     function intoUD60x18(uint128 x) internal pure returns (UD60x18 result) {
         result = UD60x18.wrap(x);
     }

diff --git a/src/casting/Uint256.sol b/src/casting/Uint256.sol
@@ -33,7 +33,7 @@ error PRBMath_IntoUD21x18_Overflow(uint256 x);
 library PRBMathCastingUint256 {
     /// @notice Casts a uint256 number to SD1x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_SD1x18`.
+    /// - x ≤ uMAX_SD1x18
     function intoSD1x18(uint256 x) internal pure returns (SD1x18 result) {
         if (x > uint256(int256(uMAX_SD1x18))) {
             revert PRBMath_IntoSD1x18_Overflow(x);
@@ -43,7 +43,7 @@ library PRBMathCastingUint256 {
 
     /// @notice Casts a uint256 number to SD21x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_SD21x18`.
+    /// - x ≤ uMAX_SD21x18
     function intoSD21x18(uint256 x) internal pure returns (SD21x18 result) {
         if (x > uint256(int256(uMAX_SD21x18))) {
             revert PRBMath_IntoSD21x18_Overflow(x);
@@ -53,7 +53,7 @@ library PRBMathCastingUint256 {
 
     /// @notice Casts a uint256 number to SD59x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_SD59x18`.
+    /// - x ≤ uMAX_SD59x18
     function intoSD59x18(uint256 x) internal pure returns (SD59x18 result) {
         if (x > uint256(uMAX_SD59x18)) {
             revert PRBMath_IntoSD59x18_Overflow(x);
@@ -63,7 +63,7 @@ library PRBMathCastingUint256 {
 
     /// @notice Casts a uint256 number to UD2x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_UD2x18`.
+    /// - x ≤ uMAX_UD2x18
     function intoUD2x18(uint256 x) internal pure returns (UD2x18 result) {
         if (x > uint256(uMAX_UD2x18)) {
             revert PRBMath_IntoUD2x18_Overflow(x);
@@ -73,7 +73,7 @@ library PRBMathCastingUint256 {
 
     /// @notice Casts a uint256 number to UD2x18.
     /// @dev Requirements:
-    /// - x must be less than or equal to `uMAX_UD21x18`.
+    /// - x ≤ uMAX_UD21x18
     function intoUD21x18(uint256 x) internal pure returns (UD21x18 result) {
         if (x > uint256(uMAX_UD21x18)) {
             revert PRBMath_IntoUD21x18_Overflow(x);

diff --git a/src/casting/Uint40.sol b/src/casting/Uint40.sol
@@ -12,37 +12,37 @@ import { UD60x18 } from "../ud60x18/ValueType.sol";
 /// @notice Casting utilities for uint40.
 library PRBMathCastingUint40 {
     /// @notice Casts a uint40 number into SD1x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of SD1x18.
+    /// @dev There is no overflow check because uint40 ⊆ SD1x18.
     function intoSD1x18(uint40 x) internal pure returns (SD1x18 result) {
         result = SD1x18.wrap(int64(uint64(x)));
     }
 
     /// @notice Casts a uint40 number into SD21x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of SD21x18.
+    /// @dev There is no overflow check because uint40 ⊆ SD21x18.
     function intoSD21x18(uint40 x) internal pure returns (SD21x18 result) {
         result = SD21x18.wrap(int128(uint128(x)));
     }
 
     /// @notice Casts a uint40 number into SD59x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of SD59x18.
+    /// @dev There is no overflow check because uint40 ⊆ SD59x18.
     function intoSD59x18(uint40 x) internal pure returns (SD59x18 result) {
         result = SD59x18.wrap(int256(uint256(x)));
     }
 
     /// @notice Casts a uint40 number into UD2x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of UD2x18.
+    /// @dev There is no overflow check because uint40 ⊆ UD2x18.
     function intoUD2x18(uint40 x) internal pure returns (UD2x18 result) {
         result = UD2x18.wrap(x);
     }
 
     /// @notice Casts a uint40 number into UD21x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of UD21x18.
+    /// @dev There is no overflow check because uint40 ⊆ UD21x18.
     function intoUD21x18(uint40 x) internal pure returns (UD21x18 result) {
         result = UD21x18.wrap((x));
     }
 
     /// @notice Casts a uint40 number into UD60x18.
-    /// @dev There is no overflow check because the domain of uint40 is a subset of UD60x18.
+    /// @dev There is no overflow check because uint40 ⊆ UD60x18.
     function intoUD60x18(uint40 x) internal pure returns (UD60x18 result) {
         result = UD60x18.wrap(x);
     }

diff --git a/src/sd1x18/Casting.sol b/src/sd1x18/Casting.sol
@@ -8,14 +8,14 @@ import { UD60x18 } from "../ud60x18/ValueType.sol";
 import { SD1x18 } from "./ValueType.sol";
 
 /// @notice Casts an SD1x18 number into SD59x18.
-/// @dev There is no overflow check because the domain of SD1x18 is a subset of SD59x18.
+/// @dev There is no overflow check because SD1x18 ⊆ SD59x18.
 function intoSD59x18(SD1x18 x) pure returns (SD59x18 result) {
     result = SD59x18.wrap(int256(SD1x18.unwrap(x)));
 }
 
 /// @notice Casts an SD1x18 number into UD60x18.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUD60x18(SD1x18 x) pure returns (UD60x18 result) {
     int64 xInt = SD1x18.unwrap(x);
     if (xInt < 0) {
@@ -26,7 +26,7 @@ function intoUD60x18(SD1x18 x) pure returns (UD60x18 result) {
 
 /// @notice Casts an SD1x18 number into uint128.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUint128(SD1x18 x) pure returns (uint128 result) {
     int64 xInt = SD1x18.unwrap(x);
     if (xInt < 0) {
@@ -37,7 +37,7 @@ function intoUint128(SD1x18 x) pure returns (uint128 result) {
 
 /// @notice Casts an SD1x18 number into uint256.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUint256(SD1x18 x) pure returns (uint256 result) {
     int64 xInt = SD1x18.unwrap(x);
     if (xInt < 0) {
@@ -48,8 +48,8 @@ function intoUint256(SD1x18 x) pure returns (uint256 result) {
 
 /// @notice Casts an SD1x18 number into uint40.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `MAX_UINT40`.
+/// - x ≥ 0
+/// - x ≤ MAX_UINT40
 function intoUint40(SD1x18 x) pure returns (uint40 result) {
     int64 xInt = SD1x18.unwrap(x);
     if (xInt < 0) {

diff --git a/src/sd21x18/Casting.sol b/src/sd21x18/Casting.sol
@@ -8,14 +8,14 @@ import { UD60x18 } from "../ud60x18/ValueType.sol";
 import { SD21x18 } from "./ValueType.sol";
 
 /// @notice Casts an SD21x18 number into SD59x18.
-/// @dev There is no overflow check because the domain of SD21x18 is a subset of SD59x18.
+/// @dev There is no overflow check because SD21x18 ⊆ SD59x18.
 function intoSD59x18(SD21x18 x) pure returns (SD59x18 result) {
     result = SD59x18.wrap(int256(SD21x18.unwrap(x)));
 }
 
 /// @notice Casts an SD21x18 number into UD60x18.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUD60x18(SD21x18 x) pure returns (UD60x18 result) {
     int128 xInt = SD21x18.unwrap(x);
     if (xInt < 0) {
@@ -26,7 +26,7 @@ function intoUD60x18(SD21x18 x) pure returns (UD60x18 result) {
 
 /// @notice Casts an SD21x18 number into uint128.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUint128(SD21x18 x) pure returns (uint128 result) {
     int128 xInt = SD21x18.unwrap(x);
     if (xInt < 0) {
@@ -37,7 +37,7 @@ function intoUint128(SD21x18 x) pure returns (uint128 result) {
 
 /// @notice Casts an SD21x18 number into uint256.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUint256(SD21x18 x) pure returns (uint256 result) {
     int128 xInt = SD21x18.unwrap(x);
     if (xInt < 0) {
@@ -48,8 +48,8 @@ function intoUint256(SD21x18 x) pure returns (uint256 result) {
 
 /// @notice Casts an SD21x18 number into uint40.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `MAX_UINT40`.
+/// - x ≥ 0
+/// - x ≤ MAX_UINT40
 function intoUint40(SD21x18 x) pure returns (uint40 result) {
     int128 xInt = SD21x18.unwrap(x);
     if (xInt < 0) {

diff --git a/src/sd59x18/Casting.sol b/src/sd59x18/Casting.sol
@@ -22,8 +22,8 @@ function intoInt256(SD59x18 x) pure returns (int256 result) {
 
 /// @notice Casts an SD59x18 number into SD1x18.
 /// @dev Requirements:
-/// - x must be greater than or equal to `uMIN_SD1x18`.
-/// - x must be less than or equal to `uMAX_SD1x18`.
+/// - x ≥ uMIN_SD1x18
+/// - x ≤ uMAX_SD1x18
 function intoSD1x18(SD59x18 x) pure returns (SD1x18 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < uMIN_SD1x18) {
@@ -37,8 +37,8 @@ function intoSD1x18(SD59x18 x) pure returns (SD1x18 result) {
 
 /// @notice Casts an SD59x18 number into SD21x18.
 /// @dev Requirements:
-/// - x must be greater than or equal to `uMIN_SD21x18`.
-/// - x must be less than or equal to `uMAX_SD21x18`.
+/// - x ≥ uMIN_SD21x18
+/// - x ≤ uMAX_SD21x18
 function intoSD21x18(SD59x18 x) pure returns (SD21x18 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < uMIN_SD21x18) {
@@ -52,8 +52,8 @@ function intoSD21x18(SD59x18 x) pure returns (SD21x18 result) {
 
 /// @notice Casts an SD59x18 number into UD2x18.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `uMAX_UD2x18`.
+/// - x ≥ 0
+/// - x ≤ uMAX_UD2x18
 function intoUD2x18(SD59x18 x) pure returns (UD2x18 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {
@@ -67,8 +67,8 @@ function intoUD2x18(SD59x18 x) pure returns (UD2x18 result) {
 
 /// @notice Casts an SD59x18 number into UD21x18.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `uMAX_UD21x18`.
+/// - x ≥ 0
+/// - x ≤ uMAX_UD21x18
 function intoUD21x18(SD59x18 x) pure returns (UD21x18 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {
@@ -82,7 +82,7 @@ function intoUD21x18(SD59x18 x) pure returns (UD21x18 result) {
 
 /// @notice Casts an SD59x18 number into UD60x18.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUD60x18(SD59x18 x) pure returns (UD60x18 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {
@@ -93,7 +93,7 @@ function intoUD60x18(SD59x18 x) pure returns (UD60x18 result) {
 
 /// @notice Casts an SD59x18 number into uint256.
 /// @dev Requirements:
-/// - x must be positive.
+/// - x ≥ 0
 function intoUint256(SD59x18 x) pure returns (uint256 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {
@@ -104,8 +104,8 @@ function intoUint256(SD59x18 x) pure returns (uint256 result) {
 
 /// @notice Casts an SD59x18 number into uint128.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `uMAX_UINT128`.
+/// - x ≥ 0
+/// - x ≤ uMAX_UINT128
 function intoUint128(SD59x18 x) pure returns (uint128 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {
@@ -119,8 +119,8 @@ function intoUint128(SD59x18 x) pure returns (uint128 result) {
 
 /// @notice Casts an SD59x18 number into uint40.
 /// @dev Requirements:
-/// - x must be positive.
-/// - x must be less than or equal to `MAX_UINT40`.
+/// - x ≥ 0
+/// - x ≤ MAX_UINT40
 function intoUint40(SD59x18 x) pure returns (uint40 result) {
     int256 xInt = SD59x18.unwrap(x);
     if (xInt < 0) {

diff --git a/src/sd59x18/Conversions.sol b/src/sd59x18/Conversions.sol
@@ -8,8 +8,8 @@ import { SD59x18 } from "./ValueType.sol";
 /// @notice Converts a simple integer to SD59x18 by multiplying it by `UNIT`.
 ///
 /// @dev Requirements:
-/// - x must be greater than or equal to `MIN_SD59x18 / UNIT`.
-/// - x must be less than or equal to `MAX_SD59x18 / UNIT`.
+/// - x ≥ `MIN_SD59x18 / UNIT`
+/// - x ≤ `MAX_SD59x18 / UNIT`
 ///
 /// @param x The basic integer to convert.
 /// @param result The same number converted to SD59x18.

diff --git a/src/sd59x18/Math.sol b/src/sd59x18/Math.sol
@@ -26,7 +26,7 @@ import { SD59x18 } from "./ValueType.sol";
 /// @notice Calculates the absolute value of x.
 ///
 /// @dev Requirements:
-/// - x must be greater than `MIN_SD59x18`.
+/// - x > MIN_SD59x18.
 ///
 /// @param x The SD59x18 number for which to calculate the absolute value.
 /// @param result The absolute value of x as an SD59x18 number.
@@ -75,7 +75,7 @@ function avg(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
 /// See https://en.wikipedia.org/wiki/Floor_and_ceiling_functions.
 ///
 /// Requirements:
-/// - x must be less than or equal to `MAX_WHOLE_SD59x18`.
+/// - x ≤ MAX_WHOLE_SD59x18
 ///
 /// @param x The SD59x18 number to ceil.
 /// @param result The smallest whole number greater than or equal to x, as an SD59x18 number.
@@ -162,7 +162,7 @@ function div(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
 ///
 /// Requirements:
 /// - Refer to the requirements in {exp2}.
-/// - x must be less than 133_084258667509499441.
+/// - x < 133_084258667509499441.
 ///
 /// @param x The exponent as an SD59x18 number.
 /// @return result The result as an SD59x18 number.
@@ -197,10 +197,10 @@ function exp(SD59x18 x) pure returns (SD59x18 result) {
 /// @dev See https://ethereum.stackexchange.com/q/79903/24693.
 ///
 /// Notes:
-/// - If x is less than -59_794705707972522261, the result is zero.
+/// - If x < -59_794705707972522261, the result is zero.
 ///
 /// Requirements:
-/// - x must be less than 192e18.
+/// - x < 192e18.
 /// - The result must fit in SD59x18.
 ///
 /// @param x The exponent as an SD59x18 number.
@@ -240,7 +240,7 @@ function exp2(SD59x18 x) pure returns (SD59x18 result) {
 /// counterparts. See https://en.wikipedia.org/wiki/Floor_and_ceiling_functions.
 ///
 /// Requirements:
-/// - x must be greater than or equal to `MIN_WHOLE_SD59x18`.
+/// - x ≥ MIN_WHOLE_SD59x18
 ///
 /// @param x The SD59x18 number to floor.
 /// @param result The greatest whole number less than or equal to x, as an SD59x18 number.
@@ -484,7 +484,7 @@ function log10(SD59x18 x) pure returns (SD59x18 result) {
 /// - Due to the lossy precision of the iterative approximation, the results are not perfectly accurate to the last decimal.
 ///
 /// Requirements:
-/// - x must be greater than zero.
+/// - x > 0
 ///
 /// @param x The SD59x18 number for which to calculate the binary logarithm.
 /// @return result The binary logarithm as an SD59x18 number.
@@ -687,8 +687,8 @@ function powu(SD59x18 x, uint256 y) pure returns (SD59x18 result) {
 /// - The result is rounded toward zero.
 ///
 /// Requirements:
-/// - x cannot be negative, since complex numbers are not supported.
-/// - x must be less than `MAX_SD59x18 / UNIT`.
+/// - x ≥ 0, since complex numbers are not supported.
+/// - x ≤ MAX_SD59x18 / UNIT
 ///
 /// @param x The SD59x18 number for which to calculate the square root.
 /// @return result The result as an SD59x18 number.