Add #[must_use] to applicable math operations

CHANGELOG.md

@@ -10,8 +10,11 @@ and this project adheres to
 
 - cosmwasm-std: Implement `PartialEq` for `Addr == &Addr` and `&Addr == Addr` as
  well as `Event == &Event` and `&Event == Event` ([#1672]).
+- cosmwasm-std: Add `#[must_use]` annotations to `Uint64`, `Uint128`, `Uint256`,
+ `Uint512`, `Decimal` and `Decimal256` math operations ([#1678])
 
 [#1672]: https://github.com/CosmWasm/cosmwasm/pull/1672
+[#1678]: https://github.com/CosmWasm/cosmwasm/pull/1678
 
 ### Deprecated
 

packages/std/src/math/decimal.rs

@@ -158,6 +158,7 @@ impl Decimal {
  }
  }
 
+ #[must_use]
  pub const fn is_zero(&self) -> bool {
  self.0.is_zero()
  }
@@ -180,6 +181,7 @@ impl Decimal {
  /// assert_eq!(b.decimal_places(), 18);
  /// assert_eq!(b.atomics(), Uint128::new(1));
  /// ```
+ #[must_use]
  #[inline]
  pub const fn atomics(&self) -> Uint128 {
  self.0
@@ -189,17 +191,20 @@ impl Decimal {
  /// but this could potentially change as the type evolves.
  ///
  /// See also [`Decimal::atomics()`].
+ #[must_use]
  #[inline]
  pub const fn decimal_places(&self) -> u32 {
  Self::DECIMAL_PLACES
  }
 
  /// Rounds value down after decimal places.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn floor(&self) -> Self {
  Self((self.0 / Self::DECIMAL_FRACTIONAL) * Self::DECIMAL_FRACTIONAL)
  }
 
  /// Rounds value up after decimal places. Panics on overflow.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn ceil(&self) -> Self {
  match self.checked_ceil() {
  Ok(value) => value,
@@ -248,6 +253,7 @@ impl Decimal {
  }
 
  /// Raises a value to the power of `exp`, panics if an overflow occurred.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn pow(self, exp: u32) -> Self {
  match self.checked_pow(exp) {
  Ok(value) => value,
@@ -302,6 +308,7 @@ impl Decimal {
  /// Returns the approximate square root as a Decimal.
  ///
  /// This should not overflow or panic.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn sqrt(&self) -> Self {
  // Algorithm described in https://hackmd.io/@webmaster128/SJThlukj_
  // We start with the highest precision possible and lower it until
@@ -321,6 +328,7 @@ impl Decimal {
  /// Precision *must* be a number between 0 and 9 (inclusive).
  ///
  /// Returns `None` if the internal multiplication overflows.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  fn sqrt_with_precision(&self, precision: u32) -> Option<Self> {
  let inner_mul = 100u128.pow(precision);
  self.0.checked_mul(inner_mul.into()).ok().map(|inner| {
@@ -329,31 +337,36 @@ impl Decimal {
  })
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub const fn abs_diff(self, other: Self) -> Self {
  Self(self.0.abs_diff(other.0))
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_add(self, other: Self) -> Self {
  match self.checked_add(other) {
  Ok(value) => value,
  Err(_) => Self::MAX,
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_sub(self, other: Self) -> Self {
  match self.checked_sub(other) {
  Ok(value) => value,
  Err(_) => Self::zero(),
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_mul(self, other: Self) -> Self {
  match self.checked_mul(other) {
  Ok(value) => value,
  Err(_) => Self::MAX,
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_pow(self, exp: u32) -> Self {
  match self.checked_pow(exp) {
  Ok(value) => value,
@@ -379,6 +392,7 @@ impl Decimal {
  /// let d = Decimal::from_str("75.0").unwrap();
  /// assert_eq!(d.to_uint_floor(), Uint128::new(75));
  /// ```
+ #[must_use]
  pub fn to_uint_floor(self) -> Uint128 {
  self.0 / Self::DECIMAL_FRACTIONAL
  }
@@ -401,6 +415,7 @@ impl Decimal {
  /// let d = Decimal::from_str("75.0").unwrap();
  /// assert_eq!(d.to_uint_ceil(), Uint128::new(75));
  /// ```
+ #[must_use]
  pub fn to_uint_ceil(self) -> Uint128 {
  // Using `q = 1 + ((x - 1) / y); // if x != 0` with unsigned integers x, y, q
  // from https://stackoverflow.com/a/2745086/2013738. We know `x + y` CAN overflow.
@@ -1976,7 +1991,7 @@ mod tests {
  #[test]
  #[should_panic]
  fn decimal_pow_overflow_panics() {
- Decimal::MAX.pow(2u32);
+ _ = Decimal::MAX.pow(2u32);
  }
 
  #[test]

packages/std/src/math/decimal256.rs

@@ -170,6 +170,7 @@ impl Decimal256 {
  }
  }
 
+ #[must_use]
  pub const fn is_zero(&self) -> bool {
  self.0.is_zero()
  }
@@ -192,6 +193,7 @@ impl Decimal256 {
  /// assert_eq!(b.decimal_places(), 18);
  /// assert_eq!(b.atomics(), Uint256::from(1u128));
  /// ```
+ #[must_use]
  #[inline]
  pub const fn atomics(&self) -> Uint256 {
  self.0
@@ -201,17 +203,20 @@ impl Decimal256 {
  /// but this could potentially change as the type evolves.
  ///
  /// See also [`Decimal256::atomics()`].
+ #[must_use]
  #[inline]
  pub const fn decimal_places(&self) -> u32 {
  Self::DECIMAL_PLACES
  }
 
  /// Rounds value down after decimal places.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn floor(&self) -> Self {
  Self((self.0 / Self::DECIMAL_FRACTIONAL) * Self::DECIMAL_FRACTIONAL)
  }
 
  /// Rounds value up after decimal places. Panics on overflow.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn ceil(&self) -> Self {
  match self.checked_ceil() {
  Ok(value) => value,
@@ -260,6 +265,7 @@ impl Decimal256 {
  }
 
  /// Raises a value to the power of `exp`, panics if an overflow occurred.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn pow(self, exp: u32) -> Self {
  match self.checked_pow(exp) {
  Ok(value) => value,
@@ -314,6 +320,7 @@ impl Decimal256 {
  /// Returns the approximate square root as a Decimal256.
  ///
  /// This should not overflow or panic.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn sqrt(&self) -> Self {
  // Algorithm described in https://hackmd.io/@webmaster128/SJThlukj_
  // We start with the highest precision possible and lower it until
@@ -333,6 +340,7 @@ impl Decimal256 {
  /// Precision *must* be a number between 0 and 9 (inclusive).
  ///
  /// Returns `None` if the internal multiplication overflows.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  fn sqrt_with_precision(&self, precision: u32) -> Option<Self> {
  let inner_mul = Uint256::from(100u128).pow(precision);
  self.0.checked_mul(inner_mul).ok().map(|inner| {
@@ -341,6 +349,7 @@ impl Decimal256 {
  })
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn abs_diff(self, other: Self) -> Self {
  if self < other {
  other - self
@@ -349,27 +358,31 @@ impl Decimal256 {
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_add(self, other: Self) -> Self {
  match self.checked_add(other) {
  Ok(value) => value,
  Err(_) => Self::MAX,
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_sub(self, other: Self) -> Self {
  match self.checked_sub(other) {
  Ok(value) => value,
  Err(_) => Self::zero(),
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_mul(self, other: Self) -> Self {
  match self.checked_mul(other) {
  Ok(value) => value,
  Err(_) => Self::MAX,
  }
  }
 
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn saturating_pow(self, exp: u32) -> Self {
  match self.checked_pow(exp) {
  Ok(value) => value,
@@ -395,6 +408,7 @@ impl Decimal256 {
  /// let d = Decimal256::from_str("75.0").unwrap();
  /// assert_eq!(d.to_uint_floor(), Uint256::from(75u64));
  /// ```
+ #[must_use]
  pub fn to_uint_floor(self) -> Uint256 {
  self.0 / Self::DECIMAL_FRACTIONAL
  }
@@ -417,6 +431,7 @@ impl Decimal256 {
  /// let d = Decimal256::from_str("75.0").unwrap();
  /// assert_eq!(d.to_uint_ceil(), Uint256::from(75u64));
  /// ```
+ #[must_use]
  pub fn to_uint_ceil(self) -> Uint256 {
  // Using `q = 1 + ((x - 1) / y); // if x != 0` with unsigned integers x, y, q
  // from https://stackoverflow.com/a/2745086/2013738. We know `x + y` CAN overflow.
@@ -2125,7 +2140,7 @@ mod tests {
  #[test]
  #[should_panic]
  fn decimal256_pow_overflow_panics() {
- Decimal256::MAX.pow(2u32);
+ _ = Decimal256::MAX.pow(2u32);
  }
 
  #[test]

packages/std/src/math/fraction.rs

@@ -10,6 +10,7 @@ pub trait Fraction<T>: Sized {
  /// Returns the multiplicative inverse `q/p` for fraction `p/q`.
  ///
  /// If `p` is zero, None is returned.
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  fn inv(&self) -> Option<Self>;
 }
 
@@ -58,6 +59,7 @@ macro_rules! impl_mul_fraction {
  }
 
  /// Same operation as `checked_mul_floor` except unwrapped
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn mul_floor<F: Fraction<T>, T: Into<$Uint>>(self, rhs: F) -> Self {
  self.checked_mul_floor(rhs).unwrap()
  }
@@ -89,6 +91,7 @@ macro_rules! impl_mul_fraction {
  }
 
  /// Same operation as `checked_mul_ceil` except unwrapped
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn mul_ceil<F: Fraction<T>, T: Into<$Uint>>(self, rhs: F) -> Self {
  self.checked_mul_ceil(rhs).unwrap()
  }
@@ -119,6 +122,7 @@ macro_rules! impl_mul_fraction {
  }
 
  /// Same operation as `checked_div_floor` except unwrapped
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn div_floor<F: Fraction<T>, T: Into<$Uint>>(self, rhs: F) -> Self
  where
  Self: Sized,
@@ -156,6 +160,7 @@ macro_rules! impl_mul_fraction {
  }
 
  /// Same operation as `checked_div_ceil` except unwrapped
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  pub fn div_ceil<F: Fraction<T>, T: Into<$Uint>>(self, rhs: F) -> Self
  where
  Self: Sized,

packages/std/src/math/isqrt.rs

@@ -6,6 +6,7 @@ use crate::{Uint128, Uint256, Uint512, Uint64};
 /// [integer square root](https://en.wikipedia.org/wiki/Integer_square_root).
 pub trait Isqrt {
  /// The [integer square root](https://en.wikipedia.org/wiki/Integer_square_root).
+ #[must_use = "this returns the result of the operation, without modifying the original"]
  fn isqrt(self) -> Self;
 }