Merge pull request #607 from cauthmann/dev

Add #[must_use] to all functions with a _mut variant (#598)

src/base/cg.rs

@@ -156,6 +156,7 @@ impl<N: RealField> Matrix4<N> {
 impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
     /// Computes the transformation equal to `self` followed by an uniform scaling factor.
     #[inline]
+    #[must_use = "Did you mean to use append_scaling_mut()?"]
     pub fn append_scaling(&self, scaling: N) -> MatrixN<N, D>
     where
         D: DimNameSub<U1>,
@@ -168,6 +169,7 @@ impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
 
     /// Computes the transformation equal to an uniform scaling factor followed by `self`.
     #[inline]
+    #[must_use = "Did you mean to use prepend_scaling_mut()?"]
     pub fn prepend_scaling(&self, scaling: N) -> MatrixN<N, D>
     where
         D: DimNameSub<U1>,
@@ -180,6 +182,7 @@ impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
 
     /// Computes the transformation equal to `self` followed by a non-uniform scaling factor.
     #[inline]
+    #[must_use = "Did you mean to use append_nonuniform_scaling_mut()?"]
     pub fn append_nonuniform_scaling<SB>(
         &self,
         scaling: &Vector<N, DimNameDiff<D, U1>, SB>,
@@ -196,6 +199,7 @@ impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
 
     /// Computes the transformation equal to a non-uniform scaling factor followed by `self`.
     #[inline]
+    #[must_use = "Did you mean to use prepend_nonuniform_scaling_mut()?"]
     pub fn prepend_nonuniform_scaling<SB>(
         &self,
         scaling: &Vector<N, DimNameDiff<D, U1>, SB>,
@@ -212,6 +216,7 @@ impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
 
     /// Computes the transformation equal to `self` followed by a translation.
     #[inline]
+    #[must_use = "Did you mean to use append_translation_mut()?"]
     pub fn append_translation<SB>(&self, shift: &Vector<N, DimNameDiff<D, U1>, SB>) -> MatrixN<N, D>
     where
         D: DimNameSub<U1>,
@@ -225,6 +230,7 @@ impl<N: Scalar + Ring, D: DimName, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
 
     /// Computes the transformation equal to a translation followed by `self`.
     #[inline]
+    #[must_use = "Did you mean to use prepend_translation_mut()?"]
     pub fn prepend_translation<SB>(
         &self,
         shift: &Vector<N, DimNameDiff<D, U1>, SB>,

src/base/matrix.rs

@@ -610,6 +610,7 @@ impl<N: Scalar, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// Transposes `self`.
     #[inline]
+    #[must_use = "Did you mean to use transpose_mut()?"]
     pub fn transpose(&self) -> MatrixMN<N, C, R>
     where DefaultAllocator: Allocator<N, C, R> {
         let (nrows, ncols) = self.data.shape();
@@ -941,6 +942,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// The adjoint (aka. conjugate-transpose) of `self`.
     #[inline]
+    #[must_use = "Did you mean to use adjoint_mut()?"]
     pub fn adjoint(&self) -> MatrixMN<N, C, R>
     where DefaultAllocator: Allocator<N, C, R> {
         let (nrows, ncols) = self.data.shape();
@@ -976,6 +978,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// The conjugate of `self`.
     #[inline]
+    #[must_use = "Did you mean to use conjugate_mut()?"]
     pub fn conjugate(&self) -> MatrixMN<N, R, C>
         where DefaultAllocator: Allocator<N, R, C> {
         self.map(|e| e.conjugate())
@@ -983,6 +986,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// Divides each component of the complex matrix `self` by the given real.
     #[inline]
+    #[must_use = "Did you mean to use unscale_mut()?"]
     pub fn unscale(&self, real: N::RealField) -> MatrixMN<N, R, C>
         where DefaultAllocator: Allocator<N, R, C> {
         self.map(|e| e.unscale(real))
@@ -990,6 +994,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// Multiplies each component of the complex matrix `self` by the given real.
     #[inline]
+    #[must_use = "Did you mean to use scale_mut()?"]
     pub fn scale(&self, real: N::RealField) -> MatrixMN<N, R, C>
         where DefaultAllocator: Allocator<N, R, C> {
         self.map(|e| e.scale(real))

src/base/matrix_alga.rs

@@ -51,6 +51,7 @@ where
     DefaultAllocator: Allocator<N, R, C>,
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         -self
     }
@@ -162,6 +163,7 @@ where DefaultAllocator: Allocator<N, R, C>
     }
 
     #[inline]
+    #[must_use = "Did you mean to use normalize_mut()?"]
     fn normalize(&self) -> Self {
         self.normalize()
     }
@@ -172,6 +174,7 @@ where DefaultAllocator: Allocator<N, R, C>
     }
 
     #[inline]
+    #[must_use = "Did you mean to use try_normalize_mut()?"]
     fn try_normalize(&self, min_norm: N::RealField) -> Option<Self> {
         self.try_normalize(min_norm)
     }

src/base/norm.rs

@@ -187,6 +187,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// Returns a normalized version of this matrix.
     #[inline]
+    #[must_use = "Did you mean to use normalize_mut()?"]
     pub fn normalize(&self) -> MatrixMN<N, R, C>
         where DefaultAllocator: Allocator<N, R, C> {
         self.unscale(self.norm())
@@ -194,6 +195,7 @@ impl<N: ComplexField, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
 
     /// Returns a normalized version of this matrix unless its norm as smaller or equal to `eps`.
     #[inline]
+    #[must_use = "Did you mean to use try_normalize_mut()?"]
     pub fn try_normalize(&self, min_norm: N::RealField) -> Option<MatrixMN<N, R, C>>
         where DefaultAllocator: Allocator<N, R, C> {
         let n = self.norm();

src/base/ops.rs

@@ -829,6 +829,7 @@ where
 impl<N: Scalar + ClosedAdd, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
     /// Adds a scalar to `self`.
     #[inline]
+    #[must_use = "Did you mean to use add_scalar_mut()?"]
     pub fn add_scalar(&self, rhs: N) -> MatrixMN<N, R, C>
     where DefaultAllocator: Allocator<N, R, C> {
         let mut res = self.clone_owned();

src/geometry/isometry.rs

@@ -144,6 +144,7 @@ where DefaultAllocator: Allocator<N, D>
     /// assert_eq!(inv * (iso * pt), pt);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Self {
         let mut res = self.clone();
         res.inverse_mut();

src/geometry/isometry_alga.rs

@@ -36,6 +36,7 @@ where
     DefaultAllocator: Allocator<N, D>,
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.inverse()
     }

src/geometry/quaternion.rs

@@ -120,6 +120,7 @@ impl<N: RealField> Quaternion<N> {
     /// relative_eq!(q_normalized.norm(), 1.0);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use normalize_mut()?"]
     pub fn normalize(&self) -> Self {
         Self::from(self.coords.normalize())
     }
@@ -140,6 +141,7 @@ impl<N: RealField> Quaternion<N> {
     /// assert!(conj.i == -2.0 && conj.j == -3.0 && conj.k == -4.0 && conj.w == 1.0);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use conjugate_mut()?"]
     pub fn conjugate(&self) -> Self {
         Self::from_parts(self.w, -self.imag())
     }
@@ -163,6 +165,7 @@ impl<N: RealField> Quaternion<N> {
     /// assert!(inv_q.is_none());
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use try_inverse_mut()?"]
     pub fn try_inverse(&self) -> Option<Self> {
         let mut res = Self::from(self.coords.clone_owned());
 
@@ -974,6 +977,7 @@ impl<N: RealField> UnitQuaternion<N> {
     /// assert_eq!(conj, UnitQuaternion::from_axis_angle(&-axis, 1.78));
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use conjugate_mut()?"]
     pub fn conjugate(&self) -> Self {
         Self::new_unchecked(self.as_ref().conjugate())
     }
@@ -990,6 +994,7 @@ impl<N: RealField> UnitQuaternion<N> {
     /// assert_eq!(inv * rot, UnitQuaternion::identity());
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Self {
         self.conjugate()
     }

src/geometry/rotation.rs

@@ -270,6 +270,7 @@ where DefaultAllocator: Allocator<N, D, D>
     /// assert_relative_eq!(tr_rot * rot, Rotation2::identity(), epsilon = 1.0e-6);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use transpose_mut()?"]
     pub fn transpose(&self) -> Self {
         Self::from_matrix_unchecked(self.matrix.transpose())
     }
@@ -293,6 +294,7 @@ where DefaultAllocator: Allocator<N, D, D>
     /// assert_relative_eq!(inv * rot, Rotation2::identity(), epsilon = 1.0e-6);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Self {
         self.transpose()
     }

src/geometry/rotation_alga.rs

@@ -31,6 +31,7 @@ impl<N: RealField, D: DimName> TwoSidedInverse<Multiplicative> for Rotation<N, D
 where DefaultAllocator: Allocator<N, D, D>
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.transpose()
     }

src/geometry/similarity.rs

@@ -133,6 +133,7 @@ where
 
     /// Inverts `self`.
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Self {
         let mut res = self.clone();
         res.inverse_mut();
@@ -166,6 +167,7 @@ where
 
     /// The similarity transformation that applies a scaling factor `scaling` before `self`.
     #[inline]
+    #[must_use = "Did you mean to use prepend_scaling_mut()?"]
     pub fn prepend_scaling(&self, scaling: N) -> Self {
         assert!(
             !relative_eq!(scaling, N::zero()),
@@ -177,6 +179,7 @@ where
 
     /// The similarity transformation that applies a scaling factor `scaling` after `self`.
     #[inline]
+    #[must_use = "Did you mean to use append_scaling_mut()?"]
     pub fn append_scaling(&self, scaling: N) -> Self {
         assert!(
             !relative_eq!(scaling, N::zero()),

src/geometry/similarity_alga.rs

@@ -33,6 +33,7 @@ where
     DefaultAllocator: Allocator<N, D>,
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.inverse()
     }

src/geometry/transform.rs

@@ -370,6 +370,7 @@ where DefaultAllocator: Allocator<N, DimNameSum<D, U1>, DimNameSum<D, U1>>
     /// assert!(t.try_inverse().is_none());
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use try_inverse_mut()?"]
     pub fn try_inverse(self) -> Option<Transform<N, D, C>> {
         if let Some(m) = self.matrix.try_inverse() {
             Some(Transform::from_matrix_unchecked(m))
@@ -395,6 +396,7 @@ where DefaultAllocator: Allocator<N, DimNameSum<D, U1>, DimNameSum<D, U1>>
     /// assert_relative_eq!(inv_t * proj, Projective2::identity());
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(self) -> Transform<N, D, C>
     where C: SubTCategoryOf<TProjective> {
         // FIXME: specialize for TAffine?

src/geometry/transform_alga.rs

@@ -32,6 +32,7 @@ where
     DefaultAllocator: Allocator<N, DimNameSum<D, U1>, DimNameSum<D, U1>>,
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.clone().inverse()
     }

src/geometry/translation.rs

@@ -130,6 +130,7 @@ where DefaultAllocator: Allocator<N, D>
     /// assert_eq!(t.inverse() * t, Translation2::identity());
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Translation<N, D>
     where N: ClosedNeg {
         Translation::from(-&self.vector)

src/geometry/translation_alga.rs

@@ -32,6 +32,7 @@ impl<N: RealField, D: DimName> TwoSidedInverse<Multiplicative> for Translation<N
 where DefaultAllocator: Allocator<N, D>
 {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.inverse()
     }

src/geometry/unit_complex.rs

@@ -107,6 +107,7 @@ impl<N: RealField> UnitComplex<N> {
     /// assert_eq!(rot.complex().re, conj.complex().re);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use conjugate_mut()?"]
     pub fn conjugate(&self) -> Self {
         Self::new_unchecked(self.conj())
     }
@@ -123,6 +124,7 @@ impl<N: RealField> UnitComplex<N> {
     /// assert_relative_eq!(inv * rot, UnitComplex::identity(), epsilon = 1.0e-6);
     /// ```
     #[inline]
+    #[must_use = "Did you mean to use inverse_mut()?"]
     pub fn inverse(&self) -> Self {
         self.conjugate()
     }

src/geometry/unit_complex_alga.rs

@@ -33,6 +33,7 @@ impl<N: RealField> AbstractMagma<Multiplicative> for UnitComplex<N> {
 
 impl<N: RealField> TwoSidedInverse<Multiplicative> for UnitComplex<N> {
     #[inline]
+    #[must_use = "Did you mean to use two_sided_inverse_mut()?"]
     fn two_sided_inverse(&self) -> Self {
         self.inverse()
     }

src/linalg/inverse.rs

@@ -10,6 +10,7 @@ use crate::linalg::lu;
 impl<N: ComplexField, D: Dim, S: Storage<N, D, D>> SquareMatrix<N, D, S> {
     /// Attempts to invert this matrix.
     #[inline]
+    #[must_use = "Did you mean to use try_inverse_mut()?"]
     pub fn try_inverse(self) -> Option<MatrixN<N, D>>
     where DefaultAllocator: Allocator<N, D, D> {
         let mut me = self.into_owned();