Merge pull request #13 from popzxc/prepare-release

Prepare release 0.3

Author: popzxc

CHANGELOG.md

@@ -2,15 +2,24 @@
 
 ## [[Unreleased]]
 
-- `try_match` and `unwrap_match` macros to get a certain variant from an enum.
-- `return_ok` and `return_some` macros for early return of successful calculation.
-- `Integer` trait that unifies all the built-in integer types under a single interface.
-- `FloatConvert` trait that adds an interface for converting floating point numbers into integers.
+## 0.3.0 (18.06.2021)
+
+- `try_match` and `unwrap_match` macros to get a certain variant from an enum [#11].
+- `return_ok` and `return_some` macros for early return of successful calculation [#11].
+- `Integer` trait that unifies all the built-in integer types under a single interface [#12].
+- `FloatConvert` trait that adds an interface for converting floating point numbers into integers [#12].
+
+[#11]: https://github.com/popzxc/stdext-rs/pull/11
+[#12]: https://github.com/popzxc/stdext-rs/pull/12
 
 ## 0.2.1 (09.07.2020)
 
-- `VecExt::remove_item` method was added (#9).
+- `VecExt::remove_item` method was added [#9].
+
+[#9]: https://github.com/popzxc/stdext-rs/pull/9
 
 ## 0.2.0 (02.07.2020)
 
-- `compile_warning` and `function_name` macros were added (#4).
+- `compile_warning` and `function_name` macros were added [#4].
+
+[#4]: https://github.com/popzxc/stdext-rs/pull/4

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "stdext"
-version = "0.2.1"
+version = "0.3.0"
 authors = ["Igor Aleksanov <[email protected]>"]
 edition = "2018"
 repository = "https://github.com/popzxc/stdext-rs"

README.md

@@ -21,6 +21,31 @@ functionality which possible can get to the `std` some day.
 
 ## Highlights
 
+- `Integer` super-trait that is implemented for all the built-in integers
+  and reflects the common part of their interfaces.
+  
+  ```rust
+  use stdext::prelude::*;
+  
+  fn accepts_any_integer<I: Integer>(a: I, b: I) {
+    println!("{}", (a + b).count_ones());
+  }
+  ```
+  
+- Safe conversions from floating numbers to integers.
+
+  ```rust
+  use stdext::prelude::FloatConvert;
+  
+  let valid: Option<u8> = 10.5f32.checked_floor();
+  let too_big: Option<u8> = 256f32.checked_floor();
+  let nan: Option<u8> = f32::NAN.checked_floor();
+  
+  assert_eq!(valid, Some(10u8));
+  assert_eq!(too_big, None);
+  assert_eq!(nan, None);
+  ```
+
 - Convenient builder methods for **`Duration`**:
 
   ```rust

src/lib.rs

@@ -23,6 +23,7 @@
 //! | [`Duration`] | [`DurationExt`]
 //! | [`RwLock`] | [`RwLockExt`]
 //! | [`Mutex`] | [`MutexExt`]
+//! | [`f32`] and [`f64`] | [`FloatConvert`]
 //!
 //! [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
 //! [`&str`]: https://doc.rust-lang.org/std/primitive.str.html
@@ -40,6 +41,16 @@
 //! [`DurationExt`]: duration/trait.DurationExt.html
 //! [`RwLockExt`]: sync/rw_lock/trait.RwLockExt.html
 //! [`MutexExt`]: sync/mutex/trait.MutexExt.html
+//! [`FloatConvert`]: num/float_convert/trait.FloatConvert.html
+//!
+//! ## Integer super-trait
+//!
+//! While all built-in integer types have mostly the same interface, it's not backed by any trait,
+//! which makes it impossible to write a function that will accept any built-in integer.
+//!
+//! [`Integer`] trait solves that problem by reflecting the common interface of all the built-in integers.
+//!
+//! [`Integer`]: num/integer/trait.Integer.html
 //!
 //! ## Macros
 //!
@@ -113,6 +124,8 @@
 //!   }
 //!   ```
 
+#![warn(missing_docs, unreachable_pub)]
+
 pub mod duration;
 #[macro_use]
 pub mod macros;

src/macros.rs

@@ -1,3 +1,5 @@
+//! Various helper macros.
+
 /// `compile_warning` macro is a brother of [`std::compile_error`],
 /// which emits a compile-time warning with a provided message.
 ///

src/num/integer.rs

@@ -25,28 +25,31 @@ use std::ops::{
 ///   as they exist for the unsigned numbers only.
 pub trait Integer:
     Sized
-    + Add
+    + Add<Self, Output = Self>
     + AddAssign
-    + Sub
+    + Sub<Self, Output = Self>
     + SubAssign
-    + Shr
+    + Shr<Self, Output = Self>
     + ShrAssign
-    + Shl
+    + Shl<Self, Output = Self>
     + ShlAssign
-    + BitAnd
+    + BitAnd<Self, Output = Self>
     + BitAndAssign
-    + BitOr
+    + BitOr<Self, Output = Self>
     + BitOrAssign
-    + BitXor
+    + BitXor<Self, Output = Self>
     + BitXorAssign
-    + Div
+    + Div<Self, Output = Self>
     + DivAssign
-    + Mul
+    + Mul<Self, Output = Self>
     + MulAssign
     + Copy
 {
+    /// The smallest value that can be represented by this integer type.
     const MIN: Self;
+    /// The largest value that can be represented by this integer type.
     const MAX: Self;
+    /// The size of this integer type in bits.
     const BITS: u32;
 
     /// See [`u128::from_str_radix`].
@@ -453,4 +456,14 @@ mod tests {
             10u32.trailing_ones()
         );
     }
+
+    fn accepts_any_integer<I: super::Integer>(a: I, b: I) -> u32 {
+        (a + b).count_ones()
+    }
+
+    #[test]
+    fn composite() {
+        assert_eq!(accepts_any_integer(0u8, 0u8), 0);
+        assert_eq!(accepts_any_integer(1i128, 0i128), 1);
+    }
 }