Merge #345

345: Add `ArraysAs`, `AsArrays`, and corresponding traits for components and uints r=Ogeon a=Ogeon

This adds more casting traits, in addition to #338. These traits fulfill the same purpose as `AsRef` and `AsMut`, such as:

```rust
use palette::{Srgb, cast::ComponentsAsMut};

let mut image_buffer: Vec<u8> = /* ... */;
let color_buffer: &mut [Srgb<u8>] = image_buffer.components_as_mut();
```

Co-authored-by: Erik Hedvall <[email protected]>

no_std_test/src/main.rs

@@ -1,4 +1,4 @@
-#![cfg_attr(feature = "nightly", feature(lang_items, start))]
+#![cfg_attr(feature = "nightly", feature(start))]
 #![no_std]
 
 #[cfg(feature = "nightly")]
@@ -14,10 +14,6 @@ fn start(_argc: isize, _argv: *const *const u8) -> isize {
     0
 }
 
-#[cfg(feature = "nightly")]
-#[lang = "eh_personality"]
-extern "C" fn eh_personality() {}
-
 #[cfg(feature = "nightly")]
 #[panic_handler]
 fn panic(_info: &PanicInfo) -> ! {

palette/README.md

@@ -92,13 +92,13 @@ A longer and more advanced example that shows how to implement the conversion tr
 When working with image or pixel buffers, or any color type that can be converted to a slice of components (ex. `&[u8]`), the `cast` module provides traits and functions for turning them into slices of Palette colors without cloning the whole buffer:
 
 ```rust
-use palette::{cast::ComponentsInto, Srgb};
+use palette::{cast::ComponentsAsMut, Srgb};
 
 // The input to this function could be data from an image file or
 // maybe a texture in a game.
 fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
     // Convert `my_rgb_image` into `&mut [Srgb<u8>]` without copying.
-    let my_rgb_image: &mut [Srgb<u8>] = my_rgb_image.components_into();
+    let my_rgb_image: &mut [Srgb<u8>] = my_rgb_image.components_as_mut();
 
     for color in my_rgb_image {
         std::mem::swap(&mut color.red, &mut color.blue);
@@ -152,13 +152,17 @@ This image shows the transition from the color to `new_color` in HSL and HSV:
 In addition to the operator traits, the SVG blend and composition functions have also been implemented.
 
 ```rust
-use palette::{blend::Compose, cast::ComponentsInto, Srgb, WithAlpha};
+use palette::{
+    blend::Compose,
+    cast::{ComponentsAs, ComponentsAsMut},
+    Srgb, WithAlpha,
+};
 
 // The input to this function could be data from image files.
 fn alpha_blend_images(image1: &mut [u8], image2: &[u8]) {
     // Convert the images into `&mut [Srgb<u8>]` and `&[Srgb<u8>]` without copying.
-    let image1: &mut [Srgb<u8>] = image1.components_into();
-    let image2: &[Srgb<u8>] = image2.components_into();
+    let image1: &mut [Srgb<u8>] = image1.components_as_mut();
+    let image2: &[Srgb<u8>] = image2.components_as();
 
     for (color1, color2) in image1.iter_mut().zip(image2) {
         // Convert the colors to linear floating point format and give them transparency values.

palette/examples/readme_examples.rs

@@ -26,13 +26,13 @@ fn converting() {
 }
 
 fn pixels_and_buffers() {
-    use palette::{cast::ComponentsInto, Srgb};
+    use palette::{cast::ComponentsAsMut, Srgb};
 
     // The input to this function could be data from an image file or
     // maybe a texture in a game.
     fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
         // Convert `my_rgb_image` into `&mut [Srgb<u8>]` without copying.
-        let my_rgb_image: &mut [Srgb<u8>] = my_rgb_image.components_into();
+        let my_rgb_image: &mut [Srgb<u8>] = my_rgb_image.components_as_mut();
 
         for color in my_rgb_image {
             std::mem::swap(&mut color.red, &mut color.blue);
@@ -91,13 +91,17 @@ fn color_operations_1() {
 }
 
 fn color_operations_2() {
-    use palette::{blend::Compose, cast::ComponentsInto, Srgb, WithAlpha};
+    use palette::{
+        blend::Compose,
+        cast::{ComponentsAs, ComponentsAsMut},
+        Srgb, WithAlpha,
+    };
 
     // The input to this function could be data from image files.
     fn alpha_blend_images(image1: &mut [u8], image2: &[u8]) {
         // Convert the images into `&mut [Srgb<u8>]` and `&[Srgb<u8>]` without copying.
-        let image1: &mut [Srgb<u8>] = image1.components_into();
-        let image2: &[Srgb<u8>] = image2.components_into();
+        let image1: &mut [Srgb<u8>] = image1.components_as_mut();
+        let image2: &[Srgb<u8>] = image2.components_as();
 
         for (color1, color2) in image1.iter_mut().zip(image2) {
             // Convert the colors to linear floating point format and give them transparency values.

palette/examples/struct_of_arrays.rs

@@ -1,11 +1,11 @@
-use palette::{cast::ComponentsInto, color_difference::EuclideanDistance, IntoColor, Oklab, Srgb};
+use palette::{cast::ComponentsAs, color_difference::EuclideanDistance, IntoColor, Oklab, Srgb};
 
 fn main() {
     let image = image::open("example-data/input/fruits.png")
         .expect("could not open 'example-data/input/fruits.png'")
         .to_rgb8();
 
-    let image: &[Srgb<u8>] = image.as_raw().components_into();
+    let image: &[Srgb<u8>] = image.components_as();
 
     // Convert and collect the colors in a struct-of-arrays (SoA) format, where
     // each component is a Vec of all the pixels' component values.

palette/src/cast.rs

@@ -33,21 +33,21 @@
 //! same after casting.
 //!
 //! ```
-//! use palette::{cast::{self, ArraysInto}, Srgb, IntoColor};
+//! use palette::{cast::{self, ArraysAsMut}, Srgb, IntoColor};
 //!
 //! let color = cast::from_array::<Srgb<u8>>([23, 198, 76]).into_linear();
 //! // Note: `Srgb::<u8>::from([23, 198, 76])` works too.
 //!
-//! let buffer = &mut [[64, 139, 10], [93, 18, 214]];
-//! let color_buffer: &mut [Srgb<u8>] = buffer.arrays_into();
+//! let mut buffer = [[64, 139, 10], [93, 18, 214]];
+//! let color_buffer: &mut [Srgb<u8>] = buffer.arrays_as_mut();
 //!
 //! for destination in color_buffer {
 //!     let linear_dst = destination.into_linear::<f32>();
 //!     *destination = (linear_dst + color).into_encoding();
 //! }
 //! ```
 //!
-//! Trying to cast an array of the wrong size will not compile:
+//! Trying to cast a single array of the wrong size will not compile:
 //!
 //! ```compile_fail
 //! use palette::{cast, Srgb};
@@ -68,35 +68,37 @@
 //! or multiplying the length.
 //!
 //! ```
-//! use palette::{cast::{self, TryFromComponents}, Srgb};
+//! use palette::{cast::{self, TryComponentsAs}, Srgb};
 //!
-//! let correct_buffer = &[64, 139, 10, 93, 18, 214];
-//! assert!(<&[Srgb<u8>]>::try_from_components(correct_buffer).is_ok());
+//! let correct_buffer = [64, 139, 10, 93, 18, 214];
+//! let should_be_ok: Result<&[Srgb<u8>], _> = correct_buffer.try_components_as();
+//! assert!(should_be_ok.is_ok());
 //!
-//! let incorrect_buffer = &[64, 139, 10, 93, 18, 214, 198, 76];
-//! assert!(<&[Srgb<u8>]>::try_from_components(incorrect_buffer).is_err());
+//! let incorrect_buffer = [64, 139, 10, 93, 18, 214, 198, 76];
+//! let should_be_err: Result<&[Srgb<u8>], _> = incorrect_buffer.try_components_as();
+//! assert!(should_be_err.is_err());
 //! ```
 //!
 //! An alternative, for when the length can be trusted to be correct, is to use
-//! the `ComponentsInto::components_into` and `FromComponents::from_components`
-//! methods, or the `from_component_*` functions, that panic on error.
+//! methods without the `try_*` prefix, such as `ComponentsAs::components_as`,
+//! or the `from_component_*` functions, that panic on error.
 //!
 //! This works:
 //!
 //! ```
-//! use palette::{cast::ComponentsInto, Srgb};
+//! use palette::{cast::ComponentsAs, Srgb};
 //!
-//! let correct_buffer = &[64, 139, 10, 93, 18, 214];
-//! let color_buffer: &[Srgb<u8>] = correct_buffer.components_into();
+//! let correct_buffer = [64, 139, 10, 93, 18, 214];
+//! let color_buffer: &[Srgb<u8>] = correct_buffer.components_as();
 //! ```
 //!
 //! But this panics:
 //!
 //! ```should_panic
-//! use palette::{cast::ComponentsInto, Srgb};
+//! use palette::{cast::ComponentsAs, Srgb};
 //!
-//! let incorrect_buffer = &[64, 139, 10, 93, 18, 214, 198, 76];
-//! let color_buffer: &[Srgb<u8>] = incorrect_buffer.components_into();
+//! let incorrect_buffer = [64, 139, 10, 93, 18, 214, 198, 76];
+//! let color_buffer: &[Srgb<u8>] = incorrect_buffer.components_as();
 //! ```
 //!
 //! ## Casting Single Colors
@@ -128,10 +130,10 @@
 //!
 //! ```
 //! // `PackedArgb` is an alias for `Packed<rgb::channels::Argb, P = u32>`.
-//! use palette::{rgb::PackedArgb, cast::ComponentsInto, Srgba};
+//! use palette::{rgb::PackedArgb, cast::ComponentsAs, Srgba};
 //!
-//! let components = &[1.0f32, 0.8, 0.2, 0.3, 1.0, 0.5, 0.7, 0.6];
-//! let colors: &[PackedArgb<_>] = components.components_into();
+//! let components = [1.0f32, 0.8, 0.2, 0.3, 1.0, 0.5, 0.7, 0.6];
+//! let colors: &[PackedArgb<_>] = components.components_as();
 //!
 //! // Notice how the alpha values have moved from the beginning to the end:
 //! assert_eq!(Srgba::from(colors[0]), Srgba::new(0.8, 0.2, 0.3, 1.0));
@@ -152,20 +154,28 @@
 //!
 //! ```
 //! // `PackedArgb` is an alias for `Packed<rgb::channels::Argb, P = u32>`.
-//! use palette::{rgb::PackedArgb, cast::UintsInto, Srgba};
+//! use palette::{rgb::PackedArgb, cast::UintsAs, Srgba};
 //!
-//! let raw = &[0xFF7F0080u32, 0xFF60BBCC];
-//! let colors: &[PackedArgb] = raw.uints_into();
+//! let raw = [0xFF7F0080u32, 0xFF60BBCC];
+//! let colors: &[PackedArgb] = raw.uints_as();
 //!
 //! assert_eq!(colors.len(), 2);
 //! assert_eq!(Srgba::from(colors[0]), Srgba::new(0x7F, 0x00, 0x80, 0xFF));
 //! assert_eq!(Srgba::from(colors[1]), Srgba::new(0x60, 0xBB, 0xCC, 0xFF));
 //! ```
 
 mod array;
-mod array_traits;
+mod as_arrays_traits;
+mod as_components_traits;
+mod as_uints_traits;
+mod from_into_arrays_traits;
+mod from_into_components_traits;
+mod from_into_uints_traits;
 mod packed;
 mod uint;
-mod uint_traits;
 
-pub use self::{array::*, array_traits::*, packed::*, uint::*, uint_traits::*};
+pub use self::{
+    array::*, as_arrays_traits::*, as_components_traits::*, as_uints_traits::*,
+    from_into_arrays_traits::*, from_into_components_traits::*, from_into_uints_traits::*,
+    packed::*, uint::*,
+};