diff --git a/core/src/types/dec.rs b/core/src/types/dec.rs index 3a77b991e8..21d3158115 100644 --- a/core/src/types/dec.rs +++ b/core/src/types/dec.rs @@ -52,7 +52,36 @@ pub type Result = std::result::Result; pub struct Dec(pub I256); impl Dec { - /// Division with truncation (TODO: better description) + /// Performs division with truncation. + /// + /// This method divides `self` by `rhs` (right-hand side) and truncates the + /// result to [`POS_DECIMAL_PRECISION`] decimal places. Truncation here + /// means that any fractional part of the result that exceeds + /// [`POS_DECIMAL_PRECISION`] is discarded. + /// + /// The division is performed in the following way: + /// 1. The absolute values of the numerator and denominator are used for the + /// division. 2. The result is calculated to a fixed precision defined + /// by [`POS_DECIMAL_PRECISION`]. 3. If either the numerator or + /// denominator (but not both) is negative, the result is negated. 4. If + /// the division is impossible (e.g., division by zero or overflow), `None` + /// is returned. + /// + /// Example: + /// ``` + /// + /// let x = Dec::new(3, 1).unwrap(); // Represents 0.3 + /// let y = Dec::new(2, 1).unwrap(); // Represents 0.2 + /// let result = x.trunc_div(&y).unwrap(); + /// assert_eq!(result, Dec::new(15, 1).unwrap()); // Result is 1.5 truncated to 1 decimal place + /// ``` + /// + /// # Arguments + /// * `rhs`: The right-hand side `Dec` value for the division. + /// + /// # Returns + /// An `Option` which is `Some` with the result if the division is + /// successful, or `None` if the division cannot be performed. pub fn trunc_div(&self, rhs: &Self) -> Option { let is_neg = self.0.is_negative() ^ rhs.0.is_negative(); let inner_uint = self.0.abs();