Implement the Wrapping type

Cargo.toml

@@ -42,3 +42,7 @@ required-features = ["serde"]
 [[test]]
 name = "deserialize_error"
 required-features = ["serde"]
+
+[[test]]
+name = "serialize"
+required-features = ["serde"]

README.md

@@ -1,6 +1,6 @@
 # Integers that are constrained within inclusive ranges
 
-[![License][license-image]](./LICENSE-APACHE)
+[![License][license-image]](http://apache.org/licenses/LICENSE-2.0)
 [![Documentation][doc-image]][doc-link]
 [![Crate][crate-image]][crate-link]
 [![CI][ci-image]][ci-link]
@@ -99,7 +99,7 @@ If users already are importing the standard library on their crate, enabling
 ### serde
 
 The `serde` feature implements [serde]'s `Serialize` and `Deserialize` traits
-for all `Constrained` types.
+for `Wrapping` and all `Constrained` types.
 
 ## License
 

src/deserialize/macros.rs

@@ -5,7 +5,6 @@ macro_rules! constrained_deserialize_impl {
     (   $Num:ty, $num_mod:ident, $Cnst:ident, $deserialize:ident,
         $($method:ident!($Inner:ty, $($Visit:ty : $visit:ident)*);)*
     ) => {
-        #[cfg(feature = "serde")]
         impl<'de, const MIN: $Num, const MAX: $Num, const DEF: $Num> ::serde::Deserialize<'de>
             for crate::$num_mod::$Cnst<MIN, MAX, DEF>
         {

src/lib.rs

@@ -78,31 +78,50 @@
 // No raw pointers here, maybe in another castle.
 #![forbid(unsafe_code)]
 //
-// `std` feature will import std as a dependency.
+// The `std` feature will import `std` as a dependency.
 #![cfg_attr(not(feature = "std"), no_std)]
 //
 // The `const_guards` dependency relies on `generic_const_exprs`.
+// Tracking issue for `generic_const_exprs`:
+// https://github.com/rust-lang/rust/issues/76560
 #![allow(incomplete_features)]
 #![feature(generic_const_exprs)]
 //
+// Tracking issue for `const_trait_impl`:
+// https://github.com/rust-lang/rust/issues/67792
+#![feature(const_trait_impl)]
+//
+// Tracking issue for `const_mut_refs`:
+// https://github.com/rust-lang/rust/issues/57349
+#![feature(const_mut_refs)]
+//
 // Tracking issue for `mixed_integer_ops`:
 // https://github.com/rust-lang/rust/issues/87840.
 #![feature(mixed_integer_ops)]
 //
-// Tracking issue for `doc_auto_cfg` feature:
+// Tracking issue for `doc_cfg` and `doc_auto_cfg`feature:
 // https://github.com/rust-lang/rust/issues/43781.
 #![feature(doc_auto_cfg)]
+#![feature(doc_cfg)]
 //
 // rustdoc lints.
 #![warn(missing_docs)]
 #![warn(rustdoc::missing_crate_level_docs)]
 
-// Import `constrained_uint_def_impl!` macro.
-// Import `constrained_int_def_impl!` macro.
+// Import:
+// - `constrained_uint_def_impl!`.
+// - `constrained_int_def_impl!`.
+// - `forward_ref_binop!`.
 #[macro_use]
 mod macros;
 
+// Required:
+// - `forward_ref_binop!`.
+// - `forward_ref_op_assign!`.
+pub mod wrapping;
+
 #[cfg(feature = "serde")]
+#[doc(cfg(feature = "serde"))]
 mod deserialize;
 
 #[cfg(test)]

src/macros/common.rs

@@ -76,6 +76,10 @@ macro_rules! constrained_def_impl {
         /// or `MAX` to be lower than the primitive's `MAX`, or else the type can't be
         /// constructed.
         ///
+        /// # Layout
+        ///
+        #[doc = concat!(stringify!($Ty), " is guaranteed to have the same layout and ABI as `", stringify!($Int), "`")]
+        ///
         /// # Examples
         ///
         /// If the provided parameters satisfy the construction condition, associated
@@ -106,7 +110,7 @@ macro_rules! constrained_def_impl {
         /// // None of these will compile for InvalidRange.
         /// let value = InvalidRange::MIN;
         /// let constrained = InvalidRange::default();
-        /// let constrained = InvalidRange::min();
+        /// let constrained = InvalidRange::new_min();
         /// /* ...other constructors */
         /// ```
         #[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
@@ -119,7 +123,7 @@ macro_rules! constrained_def_impl {
         impl<const MIN: $Int, const MAX: $Int, const DEF: $Int> $Ty<MIN, MAX, DEF> {
             /// The minimum **inclusive** value that this type can hold.
             ///
-            /// It's assigned the `MAX` parameter value. **Always** satisfies the
+            /// It's assigned the `MIN` parameter value. **Always** satisfies the
             /// condition: [`MIN`] < [`MAX`].
             ///
             #[doc = concat!("[`MIN`]: ", stringify!($Ty), "::MIN")]
@@ -138,7 +142,7 @@ macro_rules! constrained_def_impl {
 
             /// The maximum **inclusive** value that this type can hold.
             ///
-            /// It's assigned the `MIN` parameter value. **Always** satisfies the
+            /// It's assigned the `MAX` parameter value. **Always** satisfies the
             /// condition: [`MAX`] > [`MIN`].
             ///
             #[doc = concat!("[`MAX`]: ", stringify!($Ty), "::MAX")]

src/macros/int.rs

@@ -592,6 +592,7 @@ macro_rules! constrained_int_impl {
             #[doc = concat!("use constrained_int::", stringify!($md), "::", stringify!($Ty), ";")]
             ///
             #[doc = concat!("type Constrained = ", stringify!($Ty), "<", stringify!($min, $max), ">;")]
+            ///
             /// let mut constrained = Constrained::new_min();
             /// assert!(constrained.is_negative());
             /// ```
@@ -608,6 +609,7 @@ macro_rules! constrained_int_impl {
             #[doc = concat!("use constrained_int::", stringify!($md), "::", stringify!($Ty), ";")]
             ///
             #[doc = concat!("type Constrained = ", stringify!($Ty), "<", stringify!($min, $max), ">;")]
+            ///
             /// let mut constrained = Constrained::new_max();
             /// assert!(constrained.is_positive());
             /// ```
@@ -625,6 +627,7 @@ macro_rules! constrained_int_impl {
             #[doc = concat!("use constrained_int::", stringify!($md), "::", stringify!($Ty), ";")]
             ///
             #[doc = concat!("type Constrained = ", stringify!($Ty), "<-10, 8>;")]
+            ///
             /// let mut constrained = Constrained::new(-5).unwrap();
             /// // Lower than `MAX`.
             /// constrained = constrained.checked_abs().unwrap();
@@ -865,7 +868,7 @@ macro_rules! constrained_int_impl {
     };
 }
 
-// Defines mods, containers, errors and impls, tests and default doc values for unsigned integers.
+// Defines mods, containers, errors, impls, tests and default doc values for unsigned integers.
 macro_rules! constrained_int_def_impl {
     ($({ $SigInt:ty, $UnsInt:ty, $sint_md:ident, $uint_md:ident,
          $Ty:ident, $Err:ident, $MinErr:ident, $MaxErr:ident }),+ $(,)*

src/macros/mod.rs

@@ -1,13 +1,26 @@
-// Import `constrained_def_impl!` macro.
+// Import:
+// - `constrained_def_impl!`.
 #[macro_use]
 mod common;
 
-// Import `constrained_uint_def_impl!` macro.
-// Requires `constrained_def_impl!` macro.
+// Import:
+// - `constrained_uint_def_impl!`.
+//
+// Required:
+// - `constrained_def_impl!`.
 #[macro_use]
 mod uint;
 
-// Import `constrained_int_def_impl!` macro.
-// Requires `constrained_def_impl!` macro.
+// Import:
+// - `constrained_int_def_impl!`.
+//
+// Required:
+// - `constrained_def_impl!`.
 #[macro_use]
 mod int;
+
+// Import:
+// - `forward_ref_binop!`.
+// - `forward_ref_op_assign!`.
+#[macro_use]
+mod refops;

src/macros/refops.rs

@@ -0,0 +1,93 @@
+// implements binary operators "&T op U", "T op &U", "&T op &U"
+// based on "T op U" where T and U are expected to be `Copy`able.
+// Requires `const_trait_impl` features.
+macro_rules! forward_ref_binop {
+    // Const ops implementation.
+    // This implementation is equivalent to the non-const version,
+    // but with the additional `const` keyword.
+    (impl$(<$(const $c:ident: $i:ty),+>)? const $imp:ident<$u:ty>, $method:ident for $t:ty) => {
+        impl$(<'a, $(const $c: $i,)+>)? const $imp<$u> for &'a $t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: $u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(*self, rhs)
+            }
+        }
+
+        impl$(<$(const $c: $i,)+>)? const $imp<&$u> for $t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: &$u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(self, *rhs)
+            }
+        }
+
+        impl$(<$(const $c: $i,)+>)? const $imp<&$u> for &$t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: &$u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(*self, *rhs)
+            }
+        }
+    };
+
+    // Non-const ops implementation.
+    (impl$(<$(const $c:ident: $i:ty),+>)? $imp:ident<$u:ty>, $method:ident for $t:ty) => {
+        impl$(<'a, $(const $c: $i,)+>)? $imp<$u> for &'a $t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: $u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(*self, rhs)
+            }
+        }
+
+        impl$(<$(const $c: $i,)+>)? $imp<&$u> for $t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: &$u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(self, *rhs)
+            }
+        }
+
+        impl$(<$(const $c: $i,)+>)? $imp<&$u> for &$t {
+            type Output = <$t as $imp<$u>>::Output;
+
+            #[inline]
+            fn $method(self, rhs: &$u) -> <$t as $imp<$u>>::Output {
+                $imp::$method(*self, *rhs)
+            }
+        }
+    };
+}
+
+// implements "T op= &U", based on "T op= U"
+// where U is expected to be `Copy`able.
+// Requires `const_trait_impl` and `const_mut_refs` features.
+macro_rules! forward_ref_op_assign {
+    // Const ops implementation.
+    // This implementation is equivalent to the non-const version,
+    // but with the additional `const` keyword.
+    (impl$(<$(const $c:ident: $i:ty),+>)? const $imp:ident<$u:ty>, $method:ident for $t:ty) => {
+        impl$(<$(const $c: $i,)+>)? const $imp<&$u> for $t {
+            #[inline]
+            fn $method(&mut self, rhs: &$u) {
+                $imp::$method(self, *rhs);
+            }
+        }
+    };
+
+    // Non-cont ops implementation.
+    (impl$(<$(const $c:ident: $i:ty),+>)? $imp:ident<$u:ty>, $method:ident for $t:ty) => {
+        impl$(<$(const $c: $i,)+>)? $imp<&$u> for $t {
+            #[inline]
+            fn $method(&mut self, rhs: &$u) {
+                $imp::$method(self, *rhs);
+            }
+        }
+    };
+}

src/macros/uint.rs

@@ -416,8 +416,8 @@ macro_rules! constrained_uint_impl {
             /// returned by a overflowed unsigned operation.
             ///
             /// Wraps `<$UnsInt>::MAX` around the range's upper bound and returns the
-            /// result as the first value. Computes the remaining from wrapped value
-            /// integer and returns it as the second value.
+            /// result as the first value. Computes the remaining from the wrapped value
+            /// and returns it as the second value.
             ///
             /// Caller must ensure that `value` is lower than `<$UnsInt>::MAX`, or else
             /// there will be an unexpected overflow.

src/proptest/mod.rs

@@ -1,5 +1,6 @@
-// Import `strategies_uint_def_impl!` macro.
-// Import `strategies_int_def_impl!` macro.
+// Import:
+// - `strategies_uint_def_impl!`.
+// - `strategies_int_def_impl!`.
 #[cfg(test)]
 #[macro_use]
 mod macros;