Rename colors to reduce redundancy and add more documentation

etfrogers · etfrogers · commit 14a05b2f3f94 · 2025-02-24T20:10:08.000Z
diff --git a/gnuplot/examples/color.rs b/gnuplot/examples/color.rs
@@ -9,16 +9,16 @@ fn example(c: Common) {
 
 	let mut fg = Figure::new();
 	let ax = fg.axes2d();
-	ax.set_title("Demo of RGBColor in various forms", &[]);
+	ax.set_title("Demo of RGBString in various forms", &[]);
 	ax.set_legend(Graph(0.5), Graph(0.9), &[], &[]);
 	let colors = [
 		Color("black"),
-		Color(ColorType::RGBColor("black")),
+		Color(ColorType::RGBString("black")),
 		Color("red"),
-		Color(ColorType::RGBColor("#ff0000")), // red using Hex coded RRGGBB
-		Color(ColorType::RGBColor("#ff8888")), // pink using Hex coded RRGGBB
-		Color(ColorType::RGBColor("#88ff0000")), // pink using Hex coded AARRGGBB
-		Color(ColorType::RGBColor("#ff0000")), // red using Hex coded RRGGBB
+		Color(ColorType::RGBString("#ff0000")), // red using Hex coded RRGGBB
+		Color(ColorType::RGBString("#ff8888")), // pink using Hex coded RRGGBB
+		Color(ColorType::RGBString("#88ff0000")), // pink using Hex coded AARRGGBB
+		Color(ColorType::RGBString("#ff0000")), // red using Hex coded RRGGBB
 	];
 
 	for (i, color) in colors.into_iter().enumerate() {
@@ -30,7 +30,6 @@ fn example(c: Common) {
 	}
 
 	c.show(&mut fg, "rgb_color");
-
 }
 
 fn main() {
diff --git a/gnuplot/examples/example1.rs b/gnuplot/examples/example1.rs
@@ -307,7 +307,7 @@ fn example(c: Common)
 				MarkerSymbol('*'),
 				TextAlign(AlignCenter),
 				TextOffset(0.0, -1.0),
-				MarkerColor(RGBColor("red")),
+				MarkerColor(RGBString("red")),
 				MarkerSize(2.0),
 			],
 		);
diff --git a/gnuplot/examples/variable_color.rs b/gnuplot/examples/variable_color.rs
@@ -19,7 +19,6 @@ static CANDLESTICKS_STR: &str = "1	1.5	2 	2.4	4	6.
 10	2.7	3 	3.5	4	4.3";
 
 fn example(c: Common) {
-
 	let data: Vec<Vec<f64>> = CANDLESTICKS_STR
 		.split("\n")
 		.map(|line| {
@@ -63,9 +62,9 @@ fn example(c: Common) {
 	// input value for each data point. The palette is scaled to the maximum value in the vector of `f64`s passed
 	// to the VariablePaletteColor.
 	//
-	// The third color loop uses an (implicit) VariableARGBColor. The `Vec<(u8, u8, u8, u8)>` needed to constcruct the color
-	// is calculated in this case by the `argb_formula()` closure. An explicit VariableARGBColor could also be constructed using
-	// `ColorOpt(ColorType::VariableARGBColor(data)``. A VariableRGBColor is also defined that takes a 3-tuple of u8, rather than
+	// The third color loop uses an (implicit) VariableARGBString. The `Vec<(u8, u8, u8, u8)>` needed to constcruct the color
+	// is calculated in this case by the `argb_formula()` closure. An explicit VariableARGBString could also be constructed using
+	// `ColorOpt(ColorType::VariableARGBString(data)``. A VariableRGBString is also defined that takes a 3-tuple of u8, rather than
 	// a 4 tuple.
 	for (color, label) in [
 		(Color(row_index.clone()), "VariableIndexColor"),
@@ -77,7 +76,7 @@ fn example(c: Common) {
 		),
 		(
 			Color(d1.iter().map(argb_formula).collect::<Vec<_>>()),
-			"VariableARGBColor",
+			"VariableARGBString",
 		),
 	] {
 		let mut fg = Figure::new();
@@ -96,7 +95,7 @@ fn example(c: Common) {
 			&[
 				color.clone(),
 				FillAlpha(0.5),
-				BorderColor(RGBColor("black")),
+				BorderColor(RGBString("black")),
 			],
 		);
 		ax.points(&d1, iter::repeat(1), &[color.clone(), PointSymbol('D')]);
@@ -117,7 +116,7 @@ fn example(c: Common) {
 			iter::repeat(10),
 			d1.iter().map(by3),
 			d1.iter().map(by4),
-			&[color.clone(), BorderColor(RGBColor("black"))],
+			&[color.clone(), BorderColor(RGBString("black"))],
 		);
 
 		c.show(&mut fg, "variable_color");
@@ -162,7 +161,7 @@ fn example(c: Common) {
 		&[
 			Color(SavedColorMap("magma", color_values.clone())),
 			FillAlpha(0.5),
-			BorderColor(RGBColor("black")),
+			BorderColor(RGBString("black")),
 		],
 	);
 	ax.points(
@@ -199,7 +198,7 @@ fn example(c: Common) {
 		d1.iter().map(by4),
 		&[
 			Color(SavedColorMap("hot", color_values.clone())),
-			BorderColor(RGBColor("black")),
+			BorderColor(RGBString("black")),
 		],
 	);
 
diff --git a/gnuplot/src/axes_common.rs b/gnuplot/src/axes_common.rs
@@ -680,7 +680,7 @@ impl AxisData
 				w.write_str(self.axis.get_axis_str());
 				w.write_str("zeroaxis ");
 
-				AxesCommonData::write_color_options(w, &self.options, Some(ColorType::RGBColor("black".into())));
+				AxesCommonData::write_color_options(w, &self.options, Some(ColorType::RGBString("black".into())));
 				AxesCommonData::write_line_options(w, &self.options, version);
 			}
 			else
diff --git a/gnuplot/src/color.rs b/gnuplot/src/color.rs
@@ -20,14 +20,14 @@ pub type ARGBInts = (
 
 /// Option type (for lines, axes, and text) that allows the various different gnuplot
 /// color formats. The gnuplot [colorspec reference](http://gnuplot.info/docs_6.0/loc3640.html)
-/// also explains these
+/// also explains these.
 ///
 /// There are equivalent many ways of specifying colors, and this allows the user to chose the most convenient.
 /// for example, all the following will produce the same blue color:
 /// `RGBColor("blue")`, `RGBColor("0x0000ff")`, `RGBColor("#0000ff")`, `RGBColor("0x000000ff")`,
 /// `RGBColor("#000000ff")`, `RGBIntegerColor(0, 0, 255)`, `ARGBColor(0, 0, 0, 255)`,
 ///
-/// See example usage of this in `color.rs` in the
+/// See example usages of these colors in `color.rs`, `variable_color.rs` in the
 /// [Examples folder](https://github.com/SiegeLord/RustGnuplot/tree/master/gnuplot/examples) on Github
 #[derive(Debug, Clone, PartialEq, PartialOrd)]
 pub enum ColorType<T = String> {
@@ -42,35 +42,47 @@ pub enum ColorType<T = String> {
 	/// "#AARRGGBB" represents an RGB color with an alpha channel (transparency) value in the high bits.
 	/// An alpha value of 0 represents a fully opaque color; i.e., "#00RRGGBB" is the same as "#RRGGBB".
 	/// An alpha value of 255 (FF) represents full transparency.
-	RGBColor(T),
+	RGBString(T),
 	/// tuple of u8 representing red, green and blue values as 0-255
-	RGBIntegerColor(ColorComponent, ColorComponent, ColorComponent),
+	RGBInteger(ColorComponent, ColorComponent, ColorComponent),
 	/// tuple of u8 representing alpha, red, green and blue values as 0-255.
 	/// As with `RGBColor`, an alpha value of 0 represents a fully opaque color;
 	/// an alpha value of 255 (FF) represents full transparency.
-	ARGBIntegerColor(
+	ARGBInteger(
 		ColorComponent,
 		ColorComponent,
 		ColorComponent,
 		ColorComponent,
 	),
-	VariableRGBColor(Vec<RGBInts>),
-	VariableARGBColor(Vec<ARGBInts>),
+	/// Vector of tuples of `u8` (as per `RGBColor`), but instead of a single color for the whole
+	/// plot, the vector should contain a separte color for each data point.
+	VariableRGBIntegers(Vec<RGBInts>),
+	/// Vector of tuples of `u8` (as per `ARGBColor`), but as with `VariableRGBColor`, a separate
+	/// color value is given for each data point.
+	VariableARGBIntegers(Vec<ARGBInts>),
+	/// TODO
 	PaletteFracColor(f32),
+	/// TODO
 	PaletteCBColor(f32),
+	/// Vector of `f64` values which act as indexes into the current palette to set the color of
+	/// each data point
 	VariablePaletteColor(Vec<f64>),
+	/// Similar to `VariablePaletteColor` in that it takes a `Vec<f64>` to set the indexes into the
+	/// color map for each data point, but in addition to the color data it takes a string hold the name
+	/// of the color map to use. This should have been previously created in the workspace using the
+	/// `axes.create_colormap()` function.
 	SavedColorMap(T, Vec<f64>),
 	/// Set the color of all elements of the plot to the `n`th color in the current gnuplot color cycle.
-	IndexColor(ColorIndex),
+	Index(ColorIndex),
 	/// A color type that sets the color per element using a index `n` which represents the `n`th
 	/// color in the current gnuplot color scheme. In gnuplot this is the last element in the plot command,
 	/// in Rust gnuplot, the color type takes a vector of u8, where each index is treated the same as the
 	/// fixed `IndexColor`.
 	/// This is useful for setting bars/boxes etc to be
-	/// the same color from multiple plot commands. The `color.rs` example has examples of this usage
-	VariableIndexColor(Vec<ColorIndex>),
-	///
-	BackgroundColor,
+	/// the same color from multiple plot commands. The `color.rs` example has examples of this usage.
+	VariableIndex(Vec<ColorIndex>),
+	/// Set the color of the plot to the current background color.
+	Background,
 	/// Fixed black color
 	Black,
 }
@@ -79,51 +91,51 @@ impl<T: Display> ColorType<T> {
 	/// Returns the gnuplot string that will produce the requested color
 	pub fn command(&self) -> String {
 		match self {
-			RGBColor(s) => format!(r#"rgb "{}""#, s),
-			RGBIntegerColor(r, g, b) => format!(r#"rgb {}"#, from_argb(0, *r, *g, *b)),
-			ARGBIntegerColor(a, r, g, b) => format!(r#"rgb {}"#, from_argb(*a, *r, *g, *b)),
-			VariableRGBColor(_) => String::from("rgb variable"),
-			VariableARGBColor(_) => String::from("rgb variable"),
+			RGBString(s) => format!(r#"rgb "{}""#, s),
+			RGBInteger(r, g, b) => format!(r#"rgb {}"#, from_argb(0, *r, *g, *b)),
+			ARGBInteger(a, r, g, b) => format!(r#"rgb {}"#, from_argb(*a, *r, *g, *b)),
+			VariableRGBIntegers(_) => String::from("rgb variable"),
+			VariableARGBIntegers(_) => String::from("rgb variable"),
 			PaletteFracColor(_) => todo!(),
 			PaletteCBColor(_) => todo!(),
 			VariablePaletteColor(_) => String::from("palette z"),
 			SavedColorMap(s, _) => format!("palette {s}"),
-			VariableIndexColor(_) => String::from("variable"),
-			BackgroundColor => todo!(),
-			IndexColor(n) => format!("{}", n),
+			VariableIndex(_) => String::from("variable"),
+			Background => todo!(),
+			Index(n) => format!("{}", n),
 			Black => String::from("black"),
 		}
 	}
 
 	pub fn data(&self) -> Vec<f64> {
 		match self {
-			RGBColor(_) => panic!("data() called on non-variable color type."),
-			RGBIntegerColor(_, _, _) => panic!("data() called on non-variable color type."),
-			ARGBIntegerColor(_, _, _, _) => panic!("data() called on non-variable color type."),
-			VariableRGBColor(items) => items
+			RGBString(_) => panic!("data() called on non-variable color type."),
+			RGBInteger(_, _, _) => panic!("data() called on non-variable color type."),
+			ARGBInteger(_, _, _, _) => panic!("data() called on non-variable color type."),
+			VariableRGBIntegers(items) => items
 				.iter()
 				.map(|(r, g, b)| from_argb(0, *r, *g, *b) as f64)
 				.collect(),
-			VariableARGBColor(items) => items
+			VariableARGBIntegers(items) => items
 				.into_iter()
 				.map(|(a, r, g, b)| from_argb(*a, *r, *g, *b) as f64)
 				.collect(),
 			PaletteFracColor(_) => panic!("data() called on non-variable color type."),
 			PaletteCBColor(_) => panic!("data() called on non-variable color type."),
 			VariablePaletteColor(items) => items.clone(),
 			SavedColorMap(_, items) => items.clone(),
-			IndexColor(_) => panic!("data() called on non-variable color type."),
-			VariableIndexColor(items) => items.into_iter().map(|v| *v as f64).collect(),
-			BackgroundColor => panic!("data() called on non-variable color type."),
+			Index(_) => panic!("data() called on non-variable color type."),
+			VariableIndex(items) => items.into_iter().map(|v| *v as f64).collect(),
+			Background => panic!("data() called on non-variable color type."),
 			Black => panic!("data() called on non-variable color type."),
 		}
 	}
 
 	pub fn is_variable(&self) -> bool {
 		match self {
-			VariableRGBColor(_)
-			| VariableARGBColor(_)
-			| VariableIndexColor(_)
+			VariableRGBIntegers(_)
+			| VariableARGBIntegers(_)
+			| VariableIndex(_)
 			| VariablePaletteColor(_)
 			| SavedColorMap(_, _) => true,
 			_ => false,
@@ -166,63 +178,63 @@ fn from_argb_floats(a: f64, r: f64, g: f64, b: f64) -> ARGBInts {
 
 impl<'l> Into<ColorType<String>> for &'l str {
 	fn into(self) -> ColorType<String> {
-		ColorType::RGBColor(String::from(self))
+		ColorType::RGBString(String::from(self))
 	}
 }
 
 impl<'l> Into<ColorType<String>> for String {
 	fn into(self) -> ColorType<String> {
-		ColorType::RGBColor(self)
+		ColorType::RGBString(self)
 	}
 }
 
 impl<'l> Into<ColorType<&'l str>> for &'l str {
 	fn into(self) -> ColorType<&'l str> {
-		ColorType::RGBColor(self)
+		ColorType::RGBString(self)
 	}
 }
 
 impl<T> Into<ColorType<T>> for ARGBInts {
 	fn into(self) -> ColorType<T> {
-		ColorType::ARGBIntegerColor(self.0, self.1, self.2, self.3)
+		ColorType::ARGBInteger(self.0, self.1, self.2, self.3)
 	}
 }
 
 impl<T> Into<ColorType<T>> for RGBInts {
 	fn into(self) -> ColorType<T> {
-		ColorType::RGBIntegerColor(self.0, self.1, self.2)
+		ColorType::RGBInteger(self.0, self.1, self.2)
 	}
 }
 
 impl<T> Into<ColorType<T>> for (f64, f64, f64) {
 	fn into(self) -> ColorType<T> {
 		let ints = from_rgb_floats(self.0, self.1, self.2);
-		ColorType::RGBIntegerColor(ints.0, ints.1, ints.2)
+		ColorType::RGBInteger(ints.0, ints.1, ints.2)
 	}
 }
 
 impl<T> Into<ColorType<T>> for (f64, f64, f64, f64) {
 	fn into(self) -> ColorType<T> {
 		let ints = from_argb_floats(self.0, self.1, self.2, self.3);
-		ColorType::ARGBIntegerColor(ints.0, ints.1, ints.2, ints.3)
+		ColorType::ARGBInteger(ints.0, ints.1, ints.2, ints.3)
 	}
 }
 
 impl<T> Into<ColorType<T>> for Vec<RGBInts> {
 	fn into(self) -> ColorType<T> {
-		ColorType::VariableRGBColor(self)
+		ColorType::VariableRGBIntegers(self)
 	}
 }
 
 impl<T> Into<ColorType<T>> for Vec<ARGBInts> {
 	fn into(self) -> ColorType<T> {
-		ColorType::VariableARGBColor(self)
+		ColorType::VariableARGBIntegers(self)
 	}
 }
 
 impl<T> Into<ColorType<T>> for Vec<ColorIndex> {
 	fn into(self) -> ColorType<T> {
-		ColorType::VariableIndexColor(self)
+		ColorType::VariableIndex(self)
 	}
 }
 
@@ -231,39 +243,39 @@ impl<T: Display> OneWayOwned for ColorType<T> {
 
 	fn to_one_way_owned(&self) -> ColorType<String> {
 		match self {
-			RGBColor(s) => RGBColor(s.to_string()),
-			RGBIntegerColor(r, g, b) => RGBIntegerColor(*r, *g, *b),
-			VariableRGBColor(d) => VariableRGBColor(d.clone()),
+			RGBString(s) => RGBString(s.to_string()),
+			RGBInteger(r, g, b) => RGBInteger(*r, *g, *b),
+			VariableRGBIntegers(d) => VariableRGBIntegers(d.clone()),
 			PaletteFracColor(_) => todo!(),
 			PaletteCBColor(_) => todo!(),
 			VariablePaletteColor(d) => VariablePaletteColor(d.clone()),
 			SavedColorMap(s, d) => SavedColorMap(s.to_string(), d.clone()),
-			VariableIndexColor(d) => VariableIndexColor(d.clone()),
-			BackgroundColor => BackgroundColor,
-			IndexColor(n) => IndexColor(*n),
+			VariableIndex(d) => VariableIndex(d.clone()),
+			Background => Background,
+			Index(n) => Index(*n),
 			Black => Black,
-			ARGBIntegerColor(a, r, g, b) => ARGBIntegerColor(*a, *r, *g, *b),
-			VariableARGBColor(d) => VariableARGBColor(d.clone()),
+			ARGBInteger(a, r, g, b) => ARGBInteger(*a, *r, *g, *b),
+			VariableARGBIntegers(d) => VariableARGBIntegers(d.clone()),
 		}
 	}
 }
 
 impl ColorType<String> {
 	pub fn to_ref(&self) -> ColorType<&str> {
 		match self {
-			RGBColor(s) => RGBColor(s),
-			RGBIntegerColor(r, g, b) => RGBIntegerColor(*r, *g, *b),
-			VariableRGBColor(d) => VariableRGBColor(d.to_vec()),
-			VariableARGBColor(d) => VariableARGBColor(d.to_vec()),
+			RGBString(s) => RGBString(s),
+			RGBInteger(r, g, b) => RGBInteger(*r, *g, *b),
+			VariableRGBIntegers(d) => VariableRGBIntegers(d.to_vec()),
+			VariableARGBIntegers(d) => VariableARGBIntegers(d.to_vec()),
 			PaletteFracColor(_) => todo!(),
 			PaletteCBColor(_) => todo!(),
 			VariablePaletteColor(d) => VariablePaletteColor(d.to_vec()),
 			SavedColorMap(s, d) => SavedColorMap(s, d.to_vec()),
-			VariableIndexColor(d) => VariableIndexColor(d.to_vec()),
-			BackgroundColor => todo!(),
-			IndexColor(n) => IndexColor(*n),
+			VariableIndex(d) => VariableIndex(d.to_vec()),
+			Background => todo!(),
+			Index(n) => Index(*n),
 			Black => Black,
-			ARGBIntegerColor(a, r, g, b) => ARGBIntegerColor(*a, *r, *g, *b),
+			ARGBInteger(a, r, g, b) => ARGBInteger(*a, *r, *g, *b),
 		}
 	}
 }

Original file line number	Diff line number	Diff line change
`@@ -680,7 +680,7 @@ impl AxisData`
`680`	`680`	`w.write_str(self.axis.get_axis_str());`
`681`	`681`	`w.write_str("zeroaxis ");`
`682`	`682`
`683`		`- AxesCommonData::write_color_options(w, &self.options, Some(ColorType::RGBColor("black".into())));`
	`683`	`+ AxesCommonData::write_color_options(w, &self.options, Some(ColorType::RGBString("black".into())));`
`684`	`684`	`AxesCommonData::write_line_options(w, &self.options, version);`
`685`	`685`	`}`
`686`	`686`	`else`