From 589aebbf857c4bb2cb7e0a7ee95dd7b466e09897 Mon Sep 17 00:00:00 2001
From: Christian Authmann <8371862+cauthmann@users.noreply.github.com>
Date: Wed, 5 Jun 2019 23:04:04 +0200
Subject: [PATCH] Add #[must_use] to all functions with a _mut variant (#598)

---
 src/base/cg.rs                    | 6 ++++++
 src/base/matrix.rs                | 5 +++++
 src/base/matrix_alga.rs           | 3 +++
 src/base/norm.rs                  | 2 ++
 src/base/ops.rs                   | 1 +
 src/geometry/isometry.rs          | 1 +
 src/geometry/isometry_alga.rs     | 1 +
 src/geometry/quaternion.rs        | 5 +++++
 src/geometry/rotation.rs          | 2 ++
 src/geometry/rotation_alga.rs     | 1 +
 src/geometry/similarity.rs        | 3 +++
 src/geometry/similarity_alga.rs   | 1 +
 src/geometry/transform.rs         | 2 ++
 src/geometry/transform_alga.rs    | 1 +
 src/geometry/translation.rs       | 1 +
 src/geometry/translation_alga.rs  | 1 +
 src/geometry/unit_complex.rs      | 2 ++
 src/geometry/unit_complex_alga.rs | 1 +
 src/linalg/inverse.rs             | 1 +
 19 files changed, 40 insertions(+)

diff --git a/src/base/cg.rs b/src/base/cg.rs
index d23d5cd3..2c0b1483 100644
--- a/src/base/cg.rs
+++ b/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>,
diff --git a/src/base/matrix.rs b/src/base/matrix.rs
index 7119a8ad..be4a2c8b 100644
--- a/src/base/matrix.rs
+++ b/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))
diff --git a/src/base/matrix_alga.rs b/src/base/matrix_alga.rs
index ac6aced7..76a9d7ce 100644
--- a/src/base/matrix_alga.rs
+++ b/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)
     }
diff --git a/src/base/norm.rs b/src/base/norm.rs
index 93319ddc..d05ae9b7 100644
--- a/src/base/norm.rs
+++ b/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();
diff --git a/src/base/ops.rs b/src/base/ops.rs
index cf921c33..5639cb0d 100644
--- a/src/base/ops.rs
+++ b/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();
diff --git a/src/geometry/isometry.rs b/src/geometry/isometry.rs
index 888a8307..b68a7777 100755
--- a/src/geometry/isometry.rs
+++ b/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();
diff --git a/src/geometry/isometry_alga.rs b/src/geometry/isometry_alga.rs
index e68b269c..08916775 100755
--- a/src/geometry/isometry_alga.rs
+++ b/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()
     }
diff --git a/src/geometry/quaternion.rs b/src/geometry/quaternion.rs
index 40c085f2..b1ca19b9 100755
--- a/src/geometry/quaternion.rs
+++ b/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()
     }
diff --git a/src/geometry/rotation.rs b/src/geometry/rotation.rs
index ec9c8150..ca86dfa2 100755
--- a/src/geometry/rotation.rs
+++ b/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()
     }
diff --git a/src/geometry/rotation_alga.rs b/src/geometry/rotation_alga.rs
index e8cf74e7..c4133e41 100755
--- a/src/geometry/rotation_alga.rs
+++ b/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()
     }
diff --git a/src/geometry/similarity.rs b/src/geometry/similarity.rs
index fed04725..9f5fee41 100755
--- a/src/geometry/similarity.rs
+++ b/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()),
diff --git a/src/geometry/similarity_alga.rs b/src/geometry/similarity_alga.rs
index 448fb133..c3df94c1 100755
--- a/src/geometry/similarity_alga.rs
+++ b/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()
     }
diff --git a/src/geometry/transform.rs b/src/geometry/transform.rs
index baf3308b..a8570c9d 100755
--- a/src/geometry/transform.rs
+++ b/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?
diff --git a/src/geometry/transform_alga.rs b/src/geometry/transform_alga.rs
index ec3fd7c6..65fbb32f 100755
--- a/src/geometry/transform_alga.rs
+++ b/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()
     }
diff --git a/src/geometry/translation.rs b/src/geometry/translation.rs
index e64b3d2e..153b1bf1 100755
--- a/src/geometry/translation.rs
+++ b/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)
diff --git a/src/geometry/translation_alga.rs b/src/geometry/translation_alga.rs
index 134790f6..7add6438 100755
--- a/src/geometry/translation_alga.rs
+++ b/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()
     }
diff --git a/src/geometry/unit_complex.rs b/src/geometry/unit_complex.rs
index 7ba7f374..d411d82a 100755
--- a/src/geometry/unit_complex.rs
+++ b/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()
     }
diff --git a/src/geometry/unit_complex_alga.rs b/src/geometry/unit_complex_alga.rs
index 24b55233..94cfa6e1 100755
--- a/src/geometry/unit_complex_alga.rs
+++ b/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()
     }
diff --git a/src/linalg/inverse.rs b/src/linalg/inverse.rs
index 94462442..f0920cca 100644
--- a/src/linalg/inverse.rs
+++ b/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();