Annotate functions with #[must_use] where appropriate

This commit is contained in:
Malte Tammena 2021-03-24 16:28:14 +01:00 committed by Malte Tammena
parent d7288bfd28
commit 925fc1edd7
12 changed files with 28 additions and 0 deletions

View File

@ -340,6 +340,7 @@ impl<T: Scalar, R: Dim, C: Dim, S: Storage<T, R, C>> Matrix<T, R, C, S> {
} }
/// Returns a new vector with the same magnitude as `self` clamped between `0.0` and `max`. /// Returns a new vector with the same magnitude as `self` clamped between `0.0` and `max`.
#[must_use = "This function does not mutate self but returns a new clamped version."]
#[inline] #[inline]
pub fn cap_magnitude(&self, max: T::RealField) -> OMatrix<T, R, C> pub fn cap_magnitude(&self, max: T::RealField) -> OMatrix<T, R, C>
where where
@ -356,6 +357,7 @@ impl<T: Scalar, R: Dim, C: Dim, S: Storage<T, R, C>> Matrix<T, R, C, S> {
} }
/// Returns a new vector with the same magnitude as `self` clamped between `0.0` and `max`. /// Returns a new vector with the same magnitude as `self` clamped between `0.0` and `max`.
#[must_use = "This function does not mutate self but returns a new clamped version."]
#[inline] #[inline]
pub fn simd_cap_magnitude(&self, max: T::SimdRealField) -> OMatrix<T, R, C> pub fn simd_cap_magnitude(&self, max: T::SimdRealField) -> OMatrix<T, R, C>
where where

View File

@ -184,6 +184,7 @@ pub fn zero<T: Zero>() -> T {
/// Wraps `val` into the range `[min, max]` using modular arithmetics. /// Wraps `val` into the range `[min, max]` using modular arithmetics.
/// ///
/// The range must not be empty. /// The range must not be empty.
#[must_use = "This function does not mutate `val`."]
#[inline] #[inline]
pub fn wrap<T>(mut val: T, min: T, max: T) -> T pub fn wrap<T>(mut val: T, min: T, max: T) -> T
where where
@ -219,6 +220,7 @@ where
/// * If `min < val < max`, this returns `val`. /// * If `min < val < max`, this returns `val`.
/// * If `val <= min`, this returns `min`. /// * If `val <= min`, this returns `min`.
/// * If `val >= max`, this returns `max`. /// * If `val >= max`, this returns `max`.
#[must_use = "This function does not mutate `val`."]
#[inline] #[inline]
pub fn clamp<T: PartialOrd>(val: T, min: T, max: T) -> T { pub fn clamp<T: PartialOrd>(val: T, min: T, max: T) -> T {
if val > min { if val > min {

View File

@ -119,6 +119,7 @@ where
/// Returns the solution of the system `self * x = b` where `self` is the decomposed matrix and /// Returns the solution of the system `self * x = b` where `self` is the decomposed matrix and
/// `x` the unknown. /// `x` the unknown.
#[must_use = "Did you mean to use solve_mut()"]
pub fn solve<R2: Dim, C2: Dim, S2>(&self, b: &Matrix<T, R2, C2, S2>) -> OMatrix<T, R2, C2> pub fn solve<R2: Dim, C2: Dim, S2>(&self, b: &Matrix<T, R2, C2, S2>) -> OMatrix<T, R2, C2>
where where
S2: Storage<T, R2, C2>, S2: Storage<T, R2, C2>,
@ -131,6 +132,7 @@ where
} }
/// Computes the inverse of the decomposed matrix. /// Computes the inverse of the decomposed matrix.
#[must_use = "This function does not mutate self. Consider using the return value or dropping the function call."]
pub fn inverse(&self) -> OMatrix<T, D, D> { pub fn inverse(&self) -> OMatrix<T, D, D> {
let shape = self.chol.data.shape(); let shape = self.chol.data.shape();
let mut res = OMatrix::identity_generic(shape.0, shape.1); let mut res = OMatrix::identity_generic(shape.0, shape.1);

View File

@ -201,6 +201,7 @@ where
/// Solves the linear system `self * x = b`, where `x` is the unknown to be determined. /// Solves the linear system `self * x = b`, where `x` is the unknown to be determined.
/// ///
/// Returns `None` if `self` is not invertible. /// Returns `None` if `self` is not invertible.
#[must_use = "Did you mean to use solve_mut()?"]
pub fn solve<R2: Dim, C2: Dim, S2>( pub fn solve<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,

View File

@ -435,6 +435,7 @@ where
+ Allocator<T::RealField, D, D>, + Allocator<T::RealField, D, D>,
{ {
/// Computes exponential of this matrix /// Computes exponential of this matrix
#[must_use = "This function does not mutate self. Consider using the return value or dropping the function call."]
pub fn exp(&self) -> Self { pub fn exp(&self) -> Self {
// Simple case // Simple case
if self.nrows() == 1 { if self.nrows() == 1 {

View File

@ -159,6 +159,7 @@ where
/// Solves the linear system `self * x = b`, where `x` is the unknown to be determined. /// Solves the linear system `self * x = b`, where `x` is the unknown to be determined.
/// ///
/// Returns `None` if the decomposed matrix is not invertible. /// Returns `None` if the decomposed matrix is not invertible.
#[must_use = "Did you mean to use solve_mut()?"]
pub fn solve<R2: Dim, C2: Dim, S2>( pub fn solve<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,

View File

@ -99,6 +99,7 @@ impl<T: ComplexField> GivensRotation<T> {
} }
/// The inverse of this givens rotation. /// The inverse of this givens rotation.
#[must_use = "This function does not mutate self."]
pub fn inverse(&self) -> Self { pub fn inverse(&self) -> Self {
Self { Self {
c: self.c, c: self.c,

View File

@ -213,6 +213,7 @@ where
/// Solves the linear system `self * x = b`, where `x` is the unknown to be determined. /// Solves the linear system `self * x = b`, where `x` is the unknown to be determined.
/// ///
/// Returns `None` if `self` is not invertible. /// Returns `None` if `self` is not invertible.
#[must_use = "Did you mean to use solve_mut()?"]
pub fn solve<R2: Dim, C2: Dim, S2>( pub fn solve<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,

View File

@ -164,6 +164,7 @@ where
/// Solves the linear system `self * x = b`, where `x` is the unknown to be determined. /// Solves the linear system `self * x = b`, where `x` is the unknown to be determined.
/// ///
/// Returns `None` if `self` is not invertible. /// Returns `None` if `self` is not invertible.
#[must_use = "Did you mean to use solve_mut()"]
pub fn solve<R2: Dim, C2: Dim, S2>( pub fn solve<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,

View File

@ -10,6 +10,7 @@ use crate::base::{DVectorSlice, DefaultAllocator, Matrix, OMatrix, SquareMatrix,
impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> { impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use solve_lower_triangular_mut()?"]
#[inline] #[inline]
pub fn solve_lower_triangular<R2: Dim, C2: Dim, S2>( pub fn solve_lower_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -30,6 +31,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use solve_upper_triangular_mut()?"]
#[inline] #[inline]
pub fn solve_upper_triangular<R2: Dim, C2: Dim, S2>( pub fn solve_upper_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -186,6 +188,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
*/ */
/// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use tr_solve_lower_triangular_mut()?"]
#[inline] #[inline]
pub fn tr_solve_lower_triangular<R2: Dim, C2: Dim, S2>( pub fn tr_solve_lower_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -206,6 +209,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use tr_solve_upper_triangular_mut()?"]
#[inline] #[inline]
pub fn tr_solve_upper_triangular<R2: Dim, C2: Dim, S2>( pub fn tr_solve_upper_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -276,6 +280,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use ad_solve_lower_triangular_mut()?"]
#[inline] #[inline]
pub fn ad_solve_lower_triangular<R2: Dim, C2: Dim, S2>( pub fn ad_solve_lower_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -296,6 +301,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use ad_solve_upper_triangular_mut()?"]
#[inline] #[inline]
pub fn ad_solve_upper_triangular<R2: Dim, C2: Dim, S2>( pub fn ad_solve_upper_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -443,6 +449,7 @@ impl<T: ComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> { impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use solve_lower_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -460,6 +467,7 @@ impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use solve_upper_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -578,6 +586,7 @@ impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
*/ */
/// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use tr_solve_lower_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn tr_solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn tr_solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -595,6 +604,7 @@ impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.transpose() . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use tr_solve_upper_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn tr_solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn tr_solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -648,6 +658,7 @@ impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only
/// the lower-triangular part of `self` (including the diagonal) is considered not-zero. /// the lower-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use ad_solve_lower_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn ad_solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn ad_solve_lower_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,
@ -665,6 +676,7 @@ impl<T: SimdComplexField, D: Dim, S: Storage<T, D, D>> SquareMatrix<T, D, S> {
/// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only /// Computes the solution of the linear system `self.adjoint() . x = b` where `x` is the unknown and only
/// the upper-triangular part of `self` (including the diagonal) is considered not-zero. /// the upper-triangular part of `self` (including the diagonal) is considered not-zero.
#[must_use = "Did you mean to use ad_solve_upper_triangular_unchecked_mut()?"]
#[inline] #[inline]
pub fn ad_solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>( pub fn ad_solve_upper_triangular_unchecked<R2: Dim, C2: Dim, S2>(
&self, &self,

View File

@ -409,6 +409,7 @@ impl<T: Scalar, R: Dim, C: Dim, S: CsStorage<T, R, C>> CsMatrix<T, R, C, S> {
} }
/// Computes the transpose of this sparse matrix. /// Computes the transpose of this sparse matrix.
#[must_use = "This function does not mutate the matrix. Consider using the return value or removing the function call. There's also transpose_mut() for square matrices."]
pub fn transpose(&self) -> CsMatrix<T, C, R> pub fn transpose(&self) -> CsMatrix<T, C, R>
where where
DefaultAllocator: Allocator<usize, R>, DefaultAllocator: Allocator<usize, R>,

View File

@ -6,6 +6,7 @@ use crate::{Const, DefaultAllocator, Dim, Matrix, OMatrix, OVector, RealField};
impl<T: RealField, D: Dim, S: CsStorage<T, D, D>> CsMatrix<T, D, D, S> { impl<T: RealField, D: Dim, S: CsStorage<T, D, D>> CsMatrix<T, D, D, S> {
/// Solve a lower-triangular system with a dense right-hand-side. /// Solve a lower-triangular system with a dense right-hand-side.
#[must_use = "Did you mean to use solve_lower_triangular_mut()?"]
pub fn solve_lower_triangular<R2: Dim, C2: Dim, S2>( pub fn solve_lower_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,
@ -24,6 +25,7 @@ impl<T: RealField, D: Dim, S: CsStorage<T, D, D>> CsMatrix<T, D, D, S> {
} }
/// Solve a lower-triangular system with `self` transposed and a dense right-hand-side. /// Solve a lower-triangular system with `self` transposed and a dense right-hand-side.
#[must_use = "Did you mean to use tr_solve_lower_triangular_mut()?"]
pub fn tr_solve_lower_triangular<R2: Dim, C2: Dim, S2>( pub fn tr_solve_lower_triangular<R2: Dim, C2: Dim, S2>(
&self, &self,
b: &Matrix<T, R2, C2, S2>, b: &Matrix<T, R2, C2, S2>,
@ -135,6 +137,7 @@ impl<T: RealField, D: Dim, S: CsStorage<T, D, D>> CsMatrix<T, D, D, S> {
} }
/// Solve a lower-triangular system with a sparse right-hand-side. /// Solve a lower-triangular system with a sparse right-hand-side.
#[must_use = "This function has no side effects. Consider using the return value or removing the function call."]
pub fn solve_lower_triangular_cs<D2: Dim, S2>( pub fn solve_lower_triangular_cs<D2: Dim, S2>(
&self, &self,
b: &CsVector<T, D2, S2>, b: &CsVector<T, D2, S2>,