refactor!: update Pixel subtraits (#77)

Supersedes #72 which has become a bit of a mess.

I went to the std documentation to collect the traits implemented on
u8/u16:
- arithmetic: !, +, -, *, /, %
- bitwise: |, &, ^, <<, >>
- comparison: PartialEq, Eq, PartialOrd, Ord
- formatting: {} {:?} {:o} {:x} {:X} {:e} {:E} {:b}
- conversions: various (from/into, tryfrom/tryinto, FromStr)
- common misc: Clone, Default, Copy, Hash, Sum, Step, Product
- marker (nightly): ZeroablePrimitive, SimdElement, RangePattern,
AtomicPrimitive,
- nightly/wip misc: NumBufferTrait, FunnelShift, Distribution
- misc internals: DisjointBitOr, CarrylessMul, CarryingMulAdd

It's notable that a lot of operations on integers (`checked_*`,
`wrapping_*`, `unsigned_abs`, `abs_diff`, `log`, `pow` etc. etc. etc.)
don't live in a trait but are just type-inherent methods. Even
`num_traits` doesn't expose most of these, maybe because `std` has
steadily been growing over the years.

I see two main problems with keeping arithmetics/bitwise operations "in"
Pixel:
- maintenance burden, i.e. keeping up with std/num_traits adding new
stuff
- questionable usability of arithmetics given type size limitations (how
often do you actually want to work in a `u8`? any sum will quickly
overflow)

So I suggest **dropping arithmetic and bitwise operations** from the
Pixel trait entirely. This requires users to convert to some concrete
numeric type before "working" on pixels.

Because there is exactly one of each `TryFrom`, `TryInto`, `From` and
`Into` required by `T: Pixel`, types can be fully inferred even without
outside "help":

```rs
let a = pix.into();                // always u16
let b = pix.try_into().unwrap();   // always u8
let pix = T::from(x);              // always u8
let pix = T::try_from(y).unwrap(); // always u16
```

If you want to widen a Pixel into an integer, you can do
`u64::from(pix.into())` (which is infallible so no panics ever). If you
want to narrow an integer into `Pixel`, you have to do it twice though:
`Pixel::try_from(my_u64.try_into().expect("fits into
u16")).expect("Pixel is u16")`.

Author: FreezyLemon

Cargo.toml

@@ -9,9 +9,6 @@ edition = "2024"
 repository = "https://github.com/rust-av/v_frame"
 include = ["Cargo.toml", "README.md", "LICENSE", "src"]
 
-[dependencies]
-num-traits = "0.2.19"
-
 [features]
 padding_api = [] # exposes low-level APIs that allow bypassing padding
 

src/pixel.rs

@@ -21,9 +21,91 @@
 //! The type used must match the bit depth specified when creating frames:
 //! - 8-bit frames must use `u8`
 //! - 9-16 bit frames must use `u16`
+//!
+//! # Working with `T: Pixel`
+//!
+//! It is often necessary to convert between an abstract pixel and their concrete
+//! integer representation in order to work with them, for example to implement an
+//! algorithm operating on video frames.
+//!
+//! For this purpose, `Pixel` is a supertrait of some conversions from the standard
+//! library, namely:
+//! - `Into<u16>` to convert any pixel into a `u16`,
+//! - `TryInto<u8>` to try to convert any pixel into a `u8` (not possible if the pixel value
+//!   is outside of the range representable by `u8`),
+//! - `From<u8>` to convert any `u8` into a Pixel containing the given value and
+//! - `TryFrom<u16>` to try to convert any `u16` into a `T` (not possible if the source value
+//!   is outside of the range representable by `T`).
+//!
+//! For example, to sum all pixels in a row:
+//!
+//! ```
+//! use v_frame::frame::Frame;
+//! use v_frame::pixel::Pixel;
+//!
+//! pub fn summed_rows<T: Pixel>(frame: &Frame<T>) -> Vec<u64> {
+//!     frame.y_plane
+//!         .rows()
+//!         // row is &[T] here
+//!         .map(|row| {
+//!             row.iter()
+//!                 .map(|&pix| pix.into())    // convert T -> u16
+//!                 .map(|pix| u64::from(pix)) // widen so sum doesn't overflow
+//!                 .sum()
+//!         })
+//!         .collect()
+//! }
+//! ```
+//!
+//! Note that Pixel only provides one `Into<T>` implementation so it is not necessary to
+//! explicitly specify the wanted type (`<T as Into<u16>>::into(pix)`).
+//!
+//! Here's a somewhat contrived example of how to convert integers into pixels:
+//!
+//! ```
+//! use v_frame::frame::Frame;
+//! use v_frame::pixel::Pixel;
+//!
+//! fn random_value() -> i32 {
+//!     // chosen by a fair dice roll
+//!     4
+//! }
+//!
+//! fn clamp_to_range(value: i32, bit_depth: u8) -> u16 {
+//!     assert!(
+//!         bit_depth >= 8 && bit_depth <= 16,
+//!         "only bit depths 8-16 are supported"
+//!     );
+//!     let bit_depth_max = (1i32 << bit_depth) - 1;
+//!
+//!     if value < 0 {
+//!         0
+//!     } else if value > bit_depth_max {
+//!         bit_depth_max as u16
+//!     } else {
+//!         value as u16
+//!     }
+//! }
+//!
+//! pub fn change_some_rows<T: Pixel>(frame: &mut Frame<T>, bit_depth: u8) {
+//!     for pix in frame.y_plane.pixels_mut() {
+//!         let old_val = i32::from((*pix).into());
+//!
+//!         let new_val = clamp_to_range(old_val + random_value(), bit_depth);
+//!         if size_of::<T>() == 1 {
+//!             *pix = T::from(new_val as u8)
+//!         } else {
+//!             *pix = T::try_from(new_val).expect("T is u16");
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! Again, `From<u8>` and `TryFrom<u16>` are the only implementations for the respective traits
+//! so it's not necessary to specify which one is being used.
 
-use num_traits::PrimInt;
-use std::fmt::Debug;
+use core::fmt::{Binary, Debug, Display, LowerExp, LowerHex, Octal, UpperExp, UpperHex};
+use core::hash::Hash;
 
 mod private {
     pub trait Sealed {}
@@ -41,6 +123,8 @@ mod private {
 /// data structures and algorithms to work with both standard and high bit-depth
 /// video content.
 ///
+/// See the [module documentation][crate::pixel] for more details.
+///
 /// # Type Safety
 ///
 /// The library enforces correct type usage through validation:
@@ -56,7 +140,36 @@ mod private {
 /// i.e. using [`std::mem::zeroed`] must __not__ cause undefined behavior for
 /// implementing types.
 pub unsafe trait Pixel:
-    Debug + Copy + Clone + Default + Send + Sync + PrimInt + 'static + private::Sealed
+    Sized
+    + Copy
+    + Clone
+    // formatting
+    + Display
+    + Debug
+    + Octal
+    + LowerHex
+    + UpperHex
+    + LowerExp
+    + UpperExp
+    + Binary
+    + Default
+    // comparisons
+    + PartialEq
+    + Eq
+    + PartialOrd
+    + Ord
+    // conversions
+    + TryInto<u8, Error: core::error::Error>
+    + Into<u16>
+    + From<u8>
+    + TryFrom<u16, Error: core::error::Error>
+    // markers
+    + Send
+    + Sync
+    // misc.
+    + Hash
+    + 'static
+    + private::Sealed
 {
 }
 

src/plane.rs

@@ -331,20 +331,9 @@ impl<T: Pixel> Plane<T> {
 
         let total = self.width() * self.height() * byte_width;
         ExactSizeWrapper {
-            iter: self.pixels().flat_map(move |pix| {
-                let bytes: [u8; 2] = if byte_width == 1 {
-                    [
-                        pix.to_u8()
-                            .expect("Pixel::byte_data only supports u8 and u16 pixels"),
-                        0,
-                    ]
-                } else {
-                    pix.to_u16()
-                        .expect("Pixel::byte_data only supports u8 and u16 pixels")
-                        .to_le_bytes()
-                };
-                bytes.into_iter().take(byte_width)
-            }),
+            iter: self
+                .pixels()
+                .flat_map(move |pix| pix.into().to_le_bytes().into_iter().take(byte_width)),
             len: total,
         }
     }