From d6f4f0acbf3380a1fd5584f71015dc36f527b57b Mon Sep 17 00:00:00 2001 From: Ygor Souza Date: Wed, 25 Sep 2024 21:47:05 +0200 Subject: [PATCH] Document the fact that the hex_color macro is not const It cannot be made const with the current version of Rust, and that is counterintuitive since it does compile-time checks, so we make that clear in the documentation. It might be possible to make it const once MSRV is bumped to 1.82. --- crates/ecolor/src/hex_color_macro.rs | 28 +++++++++++++++++++++++++- crates/ecolor/src/hex_color_runtime.rs | 4 ++-- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/crates/ecolor/src/hex_color_macro.rs b/crates/ecolor/src/hex_color_macro.rs index a0a0729fdd1..fd1075dc639 100644 --- a/crates/ecolor/src/hex_color_macro.rs +++ b/crates/ecolor/src/hex_color_macro.rs @@ -1,15 +1,41 @@ -/// Construct a [`crate::Color32`] from a hex RGB or RGBA string. +/// Construct a [`crate::Color32`] from a hex RGB or RGBA string literal. /// /// Requires the "color-hex" feature. /// +/// The string is checked at compile time. If the format is invalid, compilation fails. The valid +/// format is the one described in . Only 6 (RGB) or 8 (RGBA) +/// digits are supported, and the leading `#` character is optional. +/// +/// Note that despite being checked at compile-time, this macro is not usable in `const` contexts +/// because creating the [`crate::Color32`] instance requires floating-point arithmetic. +/// /// See also [`crate::Color32::from_hex`] and [`crate::Color32::to_hex`]. /// +/// # Examples +/// /// ``` /// # use ecolor::{hex_color, Color32}; /// assert_eq!(hex_color!("#202122"), Color32::from_hex("#202122").unwrap()); /// assert_eq!(hex_color!("#202122"), Color32::from_rgb(0x20, 0x21, 0x22)); +/// assert_eq!(hex_color!("#202122"), hex_color!("202122")); /// assert_eq!(hex_color!("#abcdef12"), Color32::from_rgba_unmultiplied(0xab, 0xcd, 0xef, 0x12)); /// ``` +/// +/// If the literal string has the wrong format, the code does not compile. +/// +/// ```compile_fail +/// let _ = ecolor::hex_color!("#abc"); +/// ``` +/// +/// ```compile_fail +/// let _ = ecolor::hex_color!("#20212x"); +/// ``` +/// +/// The macro cannot be used in a `const` context. +/// +/// ```compile_fail +/// const COLOR: ecolor::Color32 = ecolor::hex_color!("#202122"); +/// ``` #[macro_export] macro_rules! hex_color { ($s:literal) => {{ diff --git a/crates/ecolor/src/hex_color_runtime.rs b/crates/ecolor/src/hex_color_runtime.rs index 3163fc5af7b..5b20258fa48 100644 --- a/crates/ecolor/src/hex_color_runtime.rs +++ b/crates/ecolor/src/hex_color_runtime.rs @@ -123,8 +123,8 @@ impl Color32 { /// Supports the 3, 4, 6, and 8-digit formats, according to the specification in /// /// - /// To parse hex colors at compile-time (e.g. for use in `const` contexts) - /// use the macro [`crate::hex_color!`] instead. + /// To parse hex colors from string literals with compile-time checking, use the macro + /// [`crate::hex_color!`] instead. /// /// # Example /// ```rust