From 51e5d28b39453ed8e10a47704a9bb5f835b07dba Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Sun, 7 Jan 2024 10:08:57 +0100
Subject: [PATCH] Rename `from_hex_string` -> `from_hex`, and `to_hex_string`
 -> `to_hex` (#3777)

Follow-up to https://github.com/emilk/egui/pull/3570
---
 crates/ecolor/src/hex_color_macro.rs   |  5 ++++
 crates/ecolor/src/hex_color_runtime.rs | 38 ++++++++++++++------------
 2 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/crates/ecolor/src/hex_color_macro.rs b/crates/ecolor/src/hex_color_macro.rs
index 450e6a8692a..16f8cc2b8d8 100644
--- a/crates/ecolor/src/hex_color_macro.rs
+++ b/crates/ecolor/src/hex_color_macro.rs
@@ -1,7 +1,12 @@
 /// Construct a [`crate::Color32`] from a hex RGB or RGBA string.
 ///
+/// Requires the "color-hex" feature.
+///
+/// See also [`crate::Color32::from_hex`] and [`crate::Color32::to_hex`].
+///
 /// ```
 /// # 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!("#abcdef12"), Color32::from_rgba_unmultiplied(0xab, 0xcd, 0xef, 0x12));
 /// ```
diff --git a/crates/ecolor/src/hex_color_runtime.rs b/crates/ecolor/src/hex_color_runtime.rs
index 5c9b134a23d..83786953101 100644
--- a/crates/ecolor/src/hex_color_runtime.rs
+++ b/crates/ecolor/src/hex_color_runtime.rs
@@ -121,42 +121,47 @@ impl HexColor {
 }
 
 impl Color32 {
-    /// Parses a color from a hex string
+    /// Parses a color from a hex string.
     ///
-    /// Supports the 3, 4, 6, and 8-digit formats.
+    /// Supports the 3, 4, 6, and 8-digit formats, according to the specification in
+    /// <https://drafts.csswg.org/css-color-4/#hex-color>
+    ///
+    /// To parse hex colors at compile-time (e.g. for use in `const` contexts)
+    /// use the macro [`crate::hex_color!`] instead.
     ///
     /// # Example
     /// ```rust
     /// use ecolor::Color32;
-    /// assert_eq!(Ok(Color32::RED), Color32::from_hex_string("#ff0000"));
-    /// assert_eq!(Ok(Color32::GREEN), Color32::from_hex_string("#00ff00ff"));
-    /// assert_eq!(Ok(Color32::BLUE), Color32::from_hex_string("#00f"));
-    /// assert_eq!(Ok(Color32::TRANSPARENT), Color32::from_hex_string("#0000"));
+    /// assert_eq!(Ok(Color32::RED), Color32::from_hex("#ff0000"));
+    /// assert_eq!(Ok(Color32::GREEN), Color32::from_hex("#00ff00ff"));
+    /// assert_eq!(Ok(Color32::BLUE), Color32::from_hex("#00f"));
+    /// assert_eq!(Ok(Color32::TRANSPARENT), Color32::from_hex("#0000"));
     /// ```
     ///
     /// # Errors
     /// Returns an error if the string doesn't start with the hash `#` character, if the remaining
     /// length does not correspond to one of the standard formats (3, 4, 6, or 8), if it contains
     /// non-hex characters.
-    pub fn from_hex_string(hex: &str) -> Result<Self, ParseHexColorError> {
+    pub fn from_hex(hex: &str) -> Result<Self, ParseHexColorError> {
         HexColor::from_str(hex).map(|h| h.color())
     }
 
-    /// Formats the color as a hex string
+    /// Formats the color as a hex string.
     ///
     /// # Example
     /// ```rust
     /// use ecolor::Color32;
-    /// assert_eq!(Color32::RED.to_hex_string(), "#ff0000ff");
-    /// assert_eq!(Color32::GREEN.to_hex_string(), "#00ff00ff");
-    /// assert_eq!(Color32::BLUE.to_hex_string(), "#0000ffff");
-    /// assert_eq!(Color32::TRANSPARENT.to_hex_string(), "#00000000");
+    /// assert_eq!(Color32::RED.to_hex(), "#ff0000ff");
+    /// assert_eq!(Color32::GREEN.to_hex(), "#00ff00ff");
+    /// assert_eq!(Color32::BLUE.to_hex(), "#0000ffff");
+    /// assert_eq!(Color32::TRANSPARENT.to_hex(), "#00000000");
     /// ```
     ///
-    /// Uses the 8-digit format, as that is the only format that is lossless.
+    /// Uses the 8-digit format described in <https://drafts.csswg.org/css-color-4/#hex-color>,
+    /// as that is the only format that is lossless.
     /// For other formats, see [`HexColor`].
     #[inline]
-    pub fn to_hex_string(&self) -> String {
+    pub fn to_hex(&self) -> String {
         HexColor::Hex8(*self).to_string()
     }
 }
@@ -215,10 +220,7 @@ mod tests {
             C::from_rgba_unmultiplied(10, 20, 0, 255),
         ];
         for color in cases {
-            assert_eq!(
-                C::from_hex_string(color.to_hex_string().as_str()),
-                Ok(color)
-            );
+            assert_eq!(C::from_hex(color.to_hex().as_str()), Ok(color));
         }
     }
 }