6ef13b2cc8a6
chart.rs
//! Charts WordCraft makes and edits (Insert › Chart): the chart type, its data (categories and
//! series), title, legend and data labels.
//!
//! A chart object ([`crate::graphic::Graphic`] with `chart` set) keeps this model next to the
//! items it is drawn with; the DOCX writer turns it into a chart part (`c:chartSpace`) with the
//! data cached in the part itself, and the reader turns a chart part back into it when the part
//! holds nothing this model leaves out. Charts from other programs stay as they were read.
//!
//! Every value from outside (commands, files) goes through [`ChartSpec::sanitize`]: series,
//! points and text lengths are capped and values that aren't finite numbers become gaps.
use serde::{Deserialize, Serialize};
use crate::props::Rgb;
/// Most series in a chart.
pub const MAX_SERIES: usize = 255;
/// Most categories (points per series) in a chart.
pub const MAX_POINTS: usize = 4000;
/// Most cells (series × categories) in a chart: what the chart drawing reads at most.
pub const MAX_CELLS: usize = 100_000;
/// Longest title, series name or category label, characters.
pub const MAX_TEXT: usize = 255;
/// What a chart shows its data as.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ChartType {
/// Clustered columns.
#[default]
Column,
/// Stacked columns.
ColumnStacked,
/// Clustered horizontal bars.
Bar,
/// Stacked horizontal bars.
BarStacked,
Line,
Area,
Pie,
Doughnut,
/// XY scatter with markers: the categories are the x values.
Scatter,
}
impl ChartType {
pub const ALL: [ChartType; 9] = [
ChartType::Column,
ChartType::ColumnStacked,
ChartType::Bar,
ChartType::BarStacked,
ChartType::Line,
ChartType::Area,
ChartType::Pie,
ChartType::Doughnut,
ChartType::Scatter,
];
/// The id commands use (`column`, `barStacked`…).
pub fn id(self) -> &'static str {
match self {
ChartType::Column => "column",
ChartType::ColumnStacked => "columnStacked",
ChartType::Bar => "bar",
ChartType::BarStacked => "barStacked",
ChartType::Line => "line",
ChartType::Area => "area",
ChartType::Pie => "pie",
ChartType::Doughnut => "doughnut",
ChartType::Scatter => "scatter",
}
}
/// The type an id names (any ASCII case).
pub fn from_id(id: &str) -> Option<ChartType> {
ChartType::ALL.into_iter().find(|t| t.id().eq_ignore_ascii_case(id.trim()))
}
/// The name shown for it.
pub fn label(self) -> &'static str {
match self {
ChartType::Column => "Clustered Column",
ChartType::ColumnStacked => "Stacked Column",
ChartType::Bar => "Clustered Bar",
ChartType::BarStacked => "Stacked Bar",
ChartType::Line => "Line",
ChartType::Area => "Area",
ChartType::Pie => "Pie",
ChartType::Doughnut => "Doughnut",
ChartType::Scatter => "Scatter",
}
}
/// Pie and doughnut charts show one series, a slice per category.
pub fn is_round(self) -> bool {
matches!(self, ChartType::Pie | ChartType::Doughnut)
}
}
/// Where a chart's legend sits.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum LegendPos {
Right,
Left,
Top,
#[default]
Bottom,
}
impl LegendPos {
pub const ALL: [LegendPos; 4] = [LegendPos::Right, LegendPos::Top, LegendPos::Left, LegendPos::Bottom];
pub fn id(self) -> &'static str {
match self {
LegendPos::Right => "right",
LegendPos::Left => "left",
LegendPos::Top => "top",
LegendPos::Bottom => "bottom",
}
}
pub fn from_id(id: &str) -> Option<LegendPos> {
LegendPos::ALL.into_iter().find(|p| p.id().eq_ignore_ascii_case(id.trim()))
}
}
/// One series: its name, a value per category (`None` = no value, a gap) and how it is drawn:
/// fill, line, markers, smooth lines, its own data labels and number format. Unset fields follow
/// the chart's defaults.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ChartSeries {
pub name: String,
#[serde(default)]
pub values: Vec<Option<f64>>,
/// Fill color; `None`: the chart's accent color for the series.
#[serde(default)]
pub fill: Option<Rgb>,
/// "None" fill: the series draws no fill.
#[serde(default)]
pub no_fill: bool,
/// Line width in points; `None`: the chart's default.
#[serde(default)]
pub line_w: Option<f32>,
/// "None" line: the series draws no line.
#[serde(default)]
pub no_line: bool,
/// Markers on points; `None`: unset (scatter charts draw them; a saved scatter series then has
/// no `c:marker`).
#[serde(default)]
pub markers: Option<bool>,
/// Draw the line as a smooth curve.
#[serde(default)]
pub smooth: bool,
/// Data labels for this series; `None`: follow the chart's setting.
#[serde(default)]
pub labels: Option<bool>,
/// Number format of this series's labels and values; `None`: linked to the source.
#[serde(default)]
pub fmt: Option<String>,
}
impl ChartSeries {
/// A new series of a `kind` chart: a scatter series is drawn as markers without a line.
pub fn new(kind: ChartType, name: String, values: Vec<Option<f64>>) -> ChartSeries {
ChartSeries { name, values, no_line: kind == ChartType::Scatter, ..Default::default() }
}
}
/// One chart axis: title, scale bounds, tick-label number format, gridlines, tick labels and the
/// axis line.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ChartAxis {
/// `None`: no axis title; text cut to [`MAX_TEXT`] characters.
#[serde(default)]
pub title: Option<String>,
/// Fixed lower bound; `None`: automatic.
#[serde(default)]
pub min: Option<f64>,
/// Fixed upper bound; `None`: automatic.
#[serde(default)]
pub max: Option<f64>,
/// Tick-label number format (`#,##0`, `0.00`, `0%`…); `None`: linked to the source data.
#[serde(default)]
pub fmt: Option<String>,
/// Major gridlines drawn along this axis.
#[serde(default)]
pub gridlines: bool,
/// Tick labels; `false` hides them.
#[serde(default = "the_true")]
pub labels: bool,
/// The axis line.
#[serde(default = "the_true")]
pub line: bool,
}
fn the_true() -> bool {
true
}
impl Default for ChartAxis {
fn default() -> Self {
ChartAxis { title: None, min: None, max: None, fmt: None, gridlines: false, labels: true, line: true }
}
}
/// The value axis as a new chart has it: gridlines, labels, no axis line.
pub fn value_axis() -> ChartAxis {
ChartAxis { gridlines: true, line: false, ..ChartAxis::default() }
}
impl ChartAxis {
/// Make the axis safe to store: texts cleaned, bounds finite, `min` under `max` (an
/// impossible pair drops both), the format code cut to [`MAX_FMT`] characters.
pub fn sanitize(&mut self) {
self.title = self.title.as_deref().map(clean_text).filter(|t| !t.is_empty());
self.min = self.min.filter(|v| v.is_finite());
self.max = self.max.filter(|v| v.is_finite());
if matches!((self.min, self.max), (Some(lo), Some(hi)) if lo >= hi) {
self.min = None;
self.max = None;
}
self.fmt = self.fmt.as_deref().map(clean_fmt).filter(|f| !f.is_empty());
}
}
/// Longest axis number format kept, characters.
pub const MAX_FMT: usize = 128;
/// A number format code: control characters as spaces, ends trimmed, at most [`MAX_FMT`]
/// characters.
pub fn clean_fmt(s: &str) -> String {
let s: String = s.chars().take(MAX_FMT * 4).map(|c| if c.is_control() { ' ' } else { c }).collect();
s.trim().chars().take(MAX_FMT).collect::<String>().trim_end().to_string()
}
/// A chart WordCraft can edit.
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ChartSpec {
#[serde(rename = "type")]
pub kind: ChartType,
/// Category labels (scatter charts: the x values).
#[serde(default)]
pub categories: Vec<String>,
#[serde(default)]
pub series: Vec<ChartSeries>,
#[serde(default)]
pub title: Option<String>,
/// `None`: no legend.
#[serde(default)]
pub legend: Option<LegendPos>,
/// Show each point's value next to it.
#[serde(default)]
pub data_labels: bool,
/// The category axis (scatter charts: the x axis).
#[serde(default)]
pub cat_axis: ChartAxis,
/// The value axis (scatter charts: the y axis); gridlines on and no axis line in a new chart.
#[serde(default = "value_axis")]
pub val_axis: ChartAxis,
}
/// A [`ChartSpec`] as stored. A scatter series saved without `noLine` (by a version without
/// series formatting) is drawn as markers without a line, as that version drew it.
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct StoredSpec {
#[serde(rename = "type")]
kind: ChartType,
#[serde(default)]
categories: Vec<String>,
#[serde(default)]
series: Vec<StoredSeries>,
#[serde(default)]
title: Option<String>,
#[serde(default)]
legend: Option<LegendPos>,
#[serde(default)]
data_labels: bool,
#[serde(default)]
cat_axis: ChartAxis,
#[serde(default = "value_axis")]
val_axis: ChartAxis,
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct StoredSeries {
#[serde(default)]
no_line: Option<bool>,
#[serde(flatten)]
series: ChartSeries,
}
impl<'de> Deserialize<'de> for ChartSpec {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = StoredSpec::deserialize(deserializer)?;
let scatter = s.kind == ChartType::Scatter;
Ok(ChartSpec {
kind: s.kind,
categories: s.categories,
series: s.series.into_iter().map(|x| ChartSeries { no_line: x.no_line.unwrap_or(scatter), ..x.series }).collect(),
title: s.title,
legend: s.legend,
data_labels: s.data_labels,
cat_axis: s.cat_axis,
val_axis: s.val_axis,
})
}
}
impl Default for ChartSpec {
/// An empty chart whose value axis is the one a new chart (and a missing JSON field) has:
/// gridlines on, no axis line.
fn default() -> Self {
ChartSpec {
kind: ChartType::default(),
categories: Vec::new(),
series: Vec::new(),
title: None,
legend: None,
data_labels: false,
cat_axis: ChartAxis::default(),
val_axis: value_axis(),
}
}
}
impl ChartSpec {
/// A new chart of type `kind` with WordCraft's sample data: four quarters and three series
/// (one for pie and doughnut charts, x values for scatter charts), legend at the bottom.
pub fn sample(kind: ChartType) -> ChartSpec {
let (categories, series): (Vec<&str>, Vec<(&str, [f64; 4])>) = match kind {
ChartType::Pie | ChartType::Doughnut => (vec!["North", "East", "South", "West"], vec![("Share", [38.0, 24.0, 21.0, 17.0])]),
ChartType::Scatter => (vec!["1", "2", "3", "4"], vec![("Series 1", [2.1, 3.4, 3.0, 4.6]), ("Series 2", [1.2, 1.9, 2.8, 3.1])]),
_ => (
vec!["Q1", "Q2", "Q3", "Q4"],
vec![("Series 1", [3.2, 4.1, 3.6, 5.0]), ("Series 2", [2.0, 2.7, 3.9, 3.3]), ("Series 3", [1.5, 2.2, 2.4, 3.8])],
),
};
ChartSpec {
kind,
categories: categories.into_iter().map(str::to_string).collect(),
series: series.into_iter().map(|(n, v)| ChartSeries::new(kind, n.to_string(), v.into_iter().map(Some).collect())).collect(),
title: None,
legend: Some(LegendPos::Bottom),
data_labels: false,
cat_axis: ChartAxis::default(),
// Pie and doughnut charts have no axes: their axes stay plain, so the chart reads back
// as the same model.
val_axis: if kind.is_round() { ChartAxis::default() } else { value_axis() },
}
}
/// Number of categories: every series has as many values.
pub fn points(&self) -> usize {
self.categories.len()
}
/// Make the chart safe to store and draw: text cut to [`MAX_TEXT`] characters with control
/// characters turned into spaces and the ends trimmed (an empty title is none); at most
/// [`MAX_POINTS`] categories, [`MAX_SERIES`] series and [`MAX_CELLS`] cells; values that
/// aren't finite become gaps; every series as long as the categories (padded with gaps,
/// categories padded with empty labels to the longest series).
pub fn sanitize(&mut self) {
self.series.truncate(MAX_SERIES);
let longest = self.series.iter().map(|s| s.values.len()).max().unwrap_or(0);
let n = self.categories.len().max(longest).min(MAX_POINTS);
let keep = MAX_CELLS.checked_div(n).unwrap_or(MAX_SERIES).clamp(1, MAX_SERIES);
self.series.truncate(keep);
self.categories.truncate(n);
for c in &mut self.categories {
*c = clean_text(c);
}
self.categories.resize(n, String::new());
for s in &mut self.series {
s.name = clean_text(&s.name);
s.values.truncate(n);
for v in &mut s.values {
*v = v.filter(|x| x.is_finite());
}
s.values.resize(n, None);
s.fmt = s.fmt.as_deref().map(clean_fmt).filter(|f| !f.is_empty());
s.line_w = s.line_w.filter(|w| w.is_finite()).map(|w| w.clamp(0.0, 20.0));
}
self.title = self.title.as_deref().map(clean_text).filter(|t| !t.is_empty());
self.cat_axis.sanitize();
self.val_axis.sanitize();
}
/// The chart after `sanitize`.
pub fn sanitized(mut self) -> ChartSpec {
self.sanitize();
self
}
}
/// `s` as chart text: control characters as spaces, ends trimmed, at most [`MAX_TEXT`] characters.
pub fn clean_text(s: &str) -> String {
let s: String = s.chars().take(MAX_TEXT * 4).map(|c| if c.is_control() { ' ' } else { c }).collect();
s.trim().chars().take(MAX_TEXT).collect::<String>().trim_end().to_string()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sanitize_caps_sizes_and_drops_non_finite_values() {
let mut c = ChartSpec {
categories: vec!["a".into(); MAX_POINTS + 10],
series: (0..MAX_SERIES + 5)
.map(|i| ChartSeries {
name: format!("{}\n{}", "x".repeat(400), i),
values: vec![Some(f64::NAN), Some(f64::INFINITY), Some(1.0)],
..Default::default()
})
.collect(),
title: Some(" ".into()),
..Default::default()
};
c.sanitize();
assert_eq!(c.points(), MAX_POINTS);
assert!(c.series.len() * c.points() <= MAX_CELLS);
assert!(!c.series.is_empty());
let s = &c.series[0];
assert_eq!(s.values.len(), MAX_POINTS);
assert_eq!(&s.values[..3], &[None, None, Some(1.0)]);
assert_eq!(s.name.chars().count(), MAX_TEXT);
assert!(!s.name.contains('\n'));
assert_eq!(c.title, None);
}
#[test]
fn short_categories_are_padded_to_the_longest_series() {
let c = ChartSpec {
categories: vec!["a".into()],
series: vec![ChartSeries { name: "s".into(), values: vec![Some(1.0), Some(2.0)], ..Default::default() }],
..Default::default()
}
.sanitized();
assert_eq!(c.categories, vec!["a".to_string(), String::new()]);
assert_eq!(ChartType::from_id("BARSTACKED"), Some(ChartType::BarStacked));
assert_eq!(LegendPos::from_id("top"), Some(LegendPos::Top));
}
/// A scatter series stored without `noLine` reads as markers without a line; a stored value
/// and the other chart types keep theirs.
#[test]
fn stored_scatter_series_without_a_line_setting_draw_no_line() {
let read = |json: &str| -> Vec<bool> { serde_json::from_str::<ChartSpec>(json).unwrap().series.iter().map(|s| s.no_line).collect() };
let series = r#"[{"name":"a","values":[1,null,2.5]},{"name":"b","values":[3],"noLine":false}]"#;
assert_eq!(read(&format!(r#"{{"type":"scatter","series":{series}}}"#)), [true, false]);
assert_eq!(read(&format!(r#"{{"type":"line","series":{series}}}"#)), [false, false]);
let c: ChartSpec = serde_json::from_str(&format!(r#"{{"type":"scatter","series":{series}}}"#)).unwrap();
assert_eq!(c.series[0].values, [Some(1.0), None, Some(2.5)]);
// What this version writes reads back as itself.
for kind in ChartType::ALL {
let spec = ChartSpec::sample(kind);
assert_eq!(serde_json::from_str::<ChartSpec>(&serde_json::to_string(&spec).unwrap()).unwrap(), spec, "{kind:?}");
}
}
#[test]
fn default_and_missing_json_axis_fields_agree() {
let from_json: ChartSpec = serde_json::from_str(r#"{"type":"column"}"#).unwrap();
let d = ChartSpec::default();
assert_eq!((d.cat_axis.clone(), d.val_axis.clone()), (from_json.cat_axis, from_json.val_axis));
assert!(d.val_axis.gridlines && !d.val_axis.line);
}
#[test]
fn axis_bounds_and_formats_are_cleaned() {
let mut a = ChartAxis {
title: Some(" Sales\n".into()),
min: Some(f64::NAN),
max: Some(50.0),
fmt: Some("x".repeat(MAX_FMT + 40)),
gridlines: true,
labels: false,
line: true,
};
a.sanitize();
assert_eq!(a.title.as_deref(), Some("Sales"));
assert_eq!(a.min, None);
assert_eq!(a.max, Some(50.0));
assert_eq!(a.fmt.as_deref().map(|f| f.chars().count()), Some(MAX_FMT));
// min not under max drops the pair; a format of only spaces is no format.
let mut b = ChartAxis { min: Some(50.0), max: Some(50.0), fmt: Some(" ".into()), ..Default::default() };
b.sanitize();
assert_eq!((b.min, b.max), (None, None));
assert_eq!(b.fmt, None);
let mut spec = ChartSpec {
series: vec![ChartSeries { name: "s".into(), values: vec![Some(1.0)], ..Default::default() }],
categories: vec!["a".into()],
..Default::default()
};
spec.series[0].line_w = Some(f32::NAN);
spec.series[0].fmt = Some("0.00".into());
spec.sanitize();
assert_eq!(spec.series[0].line_w, None);
assert_eq!(spec.series[0].fmt.as_deref(), Some("0.00"));
let mut spec = ChartSpec {
series: vec![ChartSeries { name: "s".into(), values: vec![], line_w: Some(100.0), ..Default::default() }],
..Default::default()
};
spec.sanitize();
assert_eq!(spec.series[0].line_w, Some(20.0), "a wild width clamps to 20 pt");
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.