Power function (#505)

Author: ozgunozerk

packages/contract-utils/src/math/fixed_point.rs

@@ -1,32 +1,9 @@
-/*
-MIT License
-
-Copyright (c) 2023 Script3 Ltd. and contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-*/
 // Based on the Soroban fixed-point mathematics library
 // Original implementation: https://github.com/script3/soroban-fixed-point-math
 
 use soroban_sdk::{panic_with_error, Env, I256};
 
-use crate::math::{soroban_fixed_point::SorobanFixedPoint, SorobanFixedPointError};
+use crate::math::{SorobanFixedPoint, SorobanFixedPointError};
 
 /// Performs floor(r / z)
 fn div_floor(r: i128, z: i128) -> Option<i128> {
@@ -60,9 +37,17 @@ impl SorobanFixedPoint for i128 {
     fn fixed_mul_ceil(&self, env: &Env, y: &i128, denominator: &i128) -> i128 {
         scaled_mul_div_ceil(self, env, y, denominator)
     }
+
+    fn checked_fixed_mul_floor(&self, env: &Env, y: &i128, denominator: &i128) -> Option<i128> {
+        checked_scaled_mul_div_floor(self, env, y, denominator)
+    }
+
+    fn checked_fixed_mul_ceil(&self, env: &Env, y: &i128, denominator: &i128) -> Option<i128> {
+        checked_scaled_mul_div_ceil(self, env, y, denominator)
+    }
 }
 
-/// Performs floor(x * y / z)
+/// Performs floor(x * y / z), panics on overflow or division by zero
 fn scaled_mul_div_floor(x: &i128, env: &Env, y: &i128, z: &i128) -> i128 {
     match x.checked_mul(*y) {
         Some(r) => div_floor(r, *z)
@@ -81,7 +66,7 @@ fn scaled_mul_div_floor(x: &i128, env: &Env, y: &i128, z: &i128) -> i128 {
     }
 }
 
-/// Performs floor(x * y / z)
+/// Performs ceil(x * y / z)
 fn scaled_mul_div_ceil(x: &i128, env: &Env, y: &i128, z: &i128) -> i128 {
     match x.checked_mul(*y) {
         Some(r) => div_ceil(r, *z)
@@ -99,3 +84,37 @@ fn scaled_mul_div_ceil(x: &i128, env: &Env, y: &i128, z: &i128) -> i128 {
         }
     }
 }
+
+/// Checked version of floor(x * y / z)
+fn checked_scaled_mul_div_floor(x: &i128, env: &Env, y: &i128, z: &i128) -> Option<i128> {
+    match x.checked_mul(*y) {
+        Some(r) => div_floor(r, *z),
+        None => {
+            // scale to i256 and retry
+            let res = crate::math::i256_fixed_point::checked_mul_div_floor(
+                env,
+                &I256::from_i128(env, *x),
+                &I256::from_i128(env, *y),
+                &I256::from_i128(env, *z),
+            );
+            res.map(|r| r.to_i128())?
+        }
+    }
+}
+
+/// Checked version of ceil(x * y / z)
+fn checked_scaled_mul_div_ceil(x: &i128, env: &Env, y: &i128, z: &i128) -> Option<i128> {
+    match x.checked_mul(*y) {
+        Some(r) => div_ceil(r, *z),
+        None => {
+            // scale to i256 and retry
+            let res = crate::math::i256_fixed_point::checked_mul_div_ceil(
+                env,
+                &I256::from_i128(env, *x),
+                &I256::from_i128(env, *y),
+                &I256::from_i128(env, *z),
+            );
+            res.map(|r| r.to_i128())?
+        }
+    }
+}

packages/contract-utils/src/math/i128_fixed_point.rs

@@ -1,32 +1,9 @@
-/*
-MIT License
-
-Copyright (c) 2023 Script3 Ltd. and contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-*/
 // Based on the Soroban fixed-point mathematics library
 // Original implementation: https://github.com/script3/soroban-fixed-point-math
 
 use soroban_sdk::{panic_with_error, Env, I256};
 
-use crate::math::{soroban_fixed_point::SorobanFixedPoint, SorobanFixedPointError};
+use crate::math::{SorobanFixedPoint, SorobanFixedPointError};
 
 impl SorobanFixedPoint for I256 {
     fn fixed_mul_floor(&self, env: &Env, y: &I256, denominator: &I256) -> I256 {
@@ -36,18 +13,26 @@ impl SorobanFixedPoint for I256 {
     fn fixed_mul_ceil(&self, env: &Env, y: &I256, denominator: &I256) -> I256 {
         mul_div_ceil(env, self, y, denominator)
     }
+
+    fn checked_fixed_mul_floor(&self, env: &Env, y: &I256, denominator: &I256) -> Option<I256> {
+        checked_mul_div_floor(env, self, y, denominator)
+    }
+
+    fn checked_fixed_mul_ceil(&self, env: &Env, y: &I256, denominator: &I256) -> Option<I256> {
+        checked_mul_div_ceil(env, self, y, denominator)
+    }
 }
 
 /// Performs floor(x * y / z)
 pub(crate) fn mul_div_floor(env: &Env, x: &I256, y: &I256, z: &I256) -> I256 {
     let zero = I256::from_i32(env, 0);
     let r = x.mul(y);
 
-    if z.clone() == zero {
+    if *z == zero {
         panic_with_error!(env, SorobanFixedPointError::DivisionByZero);
     }
 
-    if r < zero || (r > zero && z.clone() < zero) {
+    if r < zero || (r > zero && *z < zero) {
         // ceil is taken by default for a negative result
         let remainder = r.rem_euclid(z);
         let one = I256::from_i32(env, 1);
@@ -63,11 +48,11 @@ pub(crate) fn mul_div_ceil(env: &Env, x: &I256, y: &I256, z: &I256) -> I256 {
     let zero = I256::from_i32(env, 0);
     let r = x.mul(y);
 
-    if z.clone() == zero {
+    if *z == zero {
         panic_with_error!(env, SorobanFixedPointError::DivisionByZero);
     }
 
-    if z.clone() < zero || r <= zero {
+    if *z < zero || r <= zero {
         // ceil is taken by default for a negative or zero result
         r.div(z)
     } else {
@@ -77,3 +62,43 @@ pub(crate) fn mul_div_ceil(env: &Env, x: &I256, y: &I256, z: &I256) -> I256 {
         r.div(z).add(if remainder > zero { &one } else { &zero })
     }
 }
+
+/// Checked version of floor(x * y / z)
+pub(crate) fn checked_mul_div_floor(env: &Env, x: &I256, y: &I256, z: &I256) -> Option<I256> {
+    let zero = I256::from_i32(env, 0);
+    let r = x.mul(y);
+
+    if *z == zero {
+        return None;
+    }
+
+    if r < zero || (r > zero && *z < zero) {
+        // ceil is taken by default for a negative result
+        let remainder = r.rem_euclid(z);
+        let one = I256::from_i32(env, 1);
+        Some(r.div(z).sub(if remainder > zero { &one } else { &zero }))
+    } else {
+        // floor is taken by default for a positive or zero result
+        Some(r.div(z))
+    }
+}
+
+/// Checked version of ceil(x * y / z)
+pub(crate) fn checked_mul_div_ceil(env: &Env, x: &I256, y: &I256, z: &I256) -> Option<I256> {
+    let zero = I256::from_i32(env, 0);
+    let r = x.mul(y);
+
+    if *z == zero {
+        return None;
+    }
+
+    if *z < zero || r <= zero {
+        // ceil is taken by default for a negative or zero result
+        Some(r.div(z))
+    } else {
+        // floor is taken by default for a positive result
+        let remainder = r.rem_euclid(z);
+        let one = I256::from_i32(env, 1);
+        Some(r.div(z).add(if remainder > zero { &one } else { &zero }))
+    }
+}