From 3f7822b7e50619a75e0a21b88d17925d53bc3576 Mon Sep 17 00:00:00 2001
From: Trevor Spiteri <tspiteri@ieee.org>
Date: Tue, 6 Aug 2019 16:35:58 +0200
Subject: [PATCH] add saturating_neg and saturating_abs

---
 README.md                   |  5 +++
 RELEASES.md                 |  3 ++
 src/macros_checked_arith.rs | 62 +++++++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+)

diff --git a/README.md b/README.md
index 1d57254..ea368a0 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,9 @@ numeric primitives are implemented. That is, you can use [`From`] or
   * The [*fixed* crate] now requires rustc version 1.31.1 or later.
   * The [`traits`] module was added, with its traits [`Fixed`],
     [`FromFixed`], [`ToFixed`], [`LossyFrom`] and [`LossyInto`],.
+  * The [`saturating_neg`] method was added to all fixed-point
+    numbers, and the [`saturating_abs`] method was added to signed
+    fixed-point numbers.
 
 #### Incompatible changes
 
@@ -58,6 +61,8 @@ numeric primitives are implemented. That is, you can use [`From`] or
 [`LossyFrom`]: https://docs.rs/fixed/0.3.4/fixed/traits/trait.LossyFrom.html
 [`LossyInto`]: https://docs.rs/fixed/0.3.4/fixed/traits/trait.LossyInto.html
 [`ToFixed`]: https://docs.rs/fixed/0.3.4/fixed/traits/trait.ToFixed.html
+[`saturating_abs`]: https://docs.rs/fixed/0.3.4/fixed/struct.FixedI32.html#method.saturating_abs
+[`saturating_neg`]: https://docs.rs/fixed/0.3.4/fixed/struct.FixedI32.html#method.saturating_neg
 [`traits`]: https://docs.rs/fixed/0.3.4/fixed/traits/index.html
 
 ### Version 0.3.3 news (2019-06-27)
diff --git a/RELEASES.md b/RELEASES.md
index 87d30bb..e70cc8c 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -11,6 +11,9 @@ Version 0.4.0 (unreleased)
   * The *fixed* crate now requires rustc version 1.31.1 or later.
   * The `traits` module was added, with its traits `Fixed`,
     `FromFixed`, `ToFixed`, `LossyFrom` and `LossyInto`.
+  * The `saturating_neg` method was added to all fixed-point numbers,
+    and the `saturating_abs` method was added to signed fixed-point
+    numbers.
   * Incompatible change: The sealed traits `Int` and `Float` now have
     no provided methods; the methods in the old implementation are now
     provided by `FromFixed` and `ToFixed`.
diff --git a/src/macros_checked_arith.rs b/src/macros_checked_arith.rs
index 60feee3..21af2d9 100644
--- a/src/macros_checked_arith.rs
+++ b/src/macros_checked_arith.rs
@@ -316,6 +316,44 @@ assert_eq!(Fix::min_value().checked_abs(), None);
             );
         }
 
+        comment!(
+            "Saturating negation. Returns the negated value, saturating on overflow.
+
+",
+            if_signed_unsigned!(
+                $Signedness,
+                "Overflow can only occur when negating the minimum value.",
+                "This method always returns zero.",
+            ),
+            "
+
+# Examples
+
+```rust
+type Fix = fixed::",
+            $s_fixed,
+            "<fixed::frac::U4>;
+",
+            if_signed_unsigned!(
+                $Signedness,
+                "assert_eq!(Fix::from_int(5).saturating_neg(), Fix::from_int(-5));
+assert_eq!(Fix::min_value().saturating_neg(), Fix::max_value());",
+                "assert_eq!(Fix::from_int(0).saturating_neg(), Fix::from_int(0));
+assert_eq!(Fix::from_int(5).saturating_neg(), Fix::from_int(0));",
+            ),
+            "
+```
+";
+            #[inline]
+            pub fn saturating_neg(self) -> $Fixed<Frac> {
+                if_signed_unsigned!(
+                    $Signedness,
+                    self.checked_neg().unwrap_or(Self::max_value()),
+                    Self::from_bits(0),
+                )
+            }
+        );
+
         comment!(
             "Saturating addition. Returns the sum, saturating on overflow.
 
@@ -433,6 +471,30 @@ assert_eq!(Fix::max_value().saturating_mul_int(2), Fix::max_value());
             }
         );
 
+        if_signed! {
+            $Signedness;
+            comment!(
+                "Saturating absolute value. Returns the absolute value, saturating on overflow.
+
+Overflow can only occur when trying to find the absolute value of the minimum value.
+
+# Examples
+
+```rust
+type Fix = fixed::",
+                $s_fixed,
+                "<fixed::frac::U4>;
+assert_eq!(Fix::from_int(-5).saturating_abs(), Fix::from_int(5));
+assert_eq!(Fix::min_value().saturating_abs(), Fix::max_value());
+```
+";
+                #[inline]
+                pub fn saturating_abs(self) -> $Fixed<Frac> {
+                    self.checked_abs().unwrap_or(Self::max_value())
+                }
+            );
+        }
+
         comment!(
             "Wrapping negation. Returns the negated value, wrapping on overflow.