core: add pre-render validation and DataTable column checks

watsonryan · watsonryan · commit f29025c99b2a · 2026-02-25T22:33:09.000Z
diff --git a/include/gnuplotpp/data.hpp b/include/gnuplotpp/data.hpp
@@ -3,6 +3,7 @@
 #include "gnuplotpp/plot.hpp"
 
 #include <filesystem>
+#include <span>
 #include <string>
 #include <unordered_map>
 #include <vector>
@@ -21,6 +22,13 @@ struct DataTable {
   /** @brief Returns true when a named column exists. */
   bool has_column(const std::string& name) const;
 
+  /**
+   * @brief Validate that all requested columns exist.
+   * @param names Required column names.
+   * @throws std::out_of_range with available column list when missing.
+   */
+  void require_columns(std::span<const std::string> names) const;
+
   /** @brief Returns row count; throws when columns have inconsistent lengths. */
   std::size_t row_count() const;
 
diff --git a/include/gnuplotpp/plot.hpp b/include/gnuplotpp/plot.hpp
@@ -445,6 +445,13 @@ class IPlotBackend {
                               const std::filesystem::path& out_dir) = 0;
 };
 
+/**
+ * @brief Validate figure/series invariants before backend rendering.
+ * @param fig Figure to validate.
+ * @return `ok=true` when valid, otherwise InvalidInput with message.
+ */
+RenderResult validate_figure_for_render(const Figure& fig);
+
 /**
  * @brief Figure container with a fixed subplot grid and backend delegation.
  */
diff --git a/src/data.cpp b/src/data.cpp
@@ -7,10 +7,32 @@
 
 namespace gnuplotpp {
 
+namespace {
+
+std::string available_columns(const std::unordered_map<std::string, std::vector<double>>& cols) {
+  std::vector<std::string> names;
+  names.reserve(cols.size());
+  for (const auto& [name, _] : cols) {
+    names.push_back(name);
+  }
+  std::sort(names.begin(), names.end());
+  std::string out;
+  for (std::size_t i = 0; i < names.size(); ++i) {
+    out += names[i];
+    if (i + 1 < names.size()) {
+      out += ", ";
+    }
+  }
+  return out;
+}
+
+}  // namespace
+
 const std::vector<double>& DataTable::column(const std::string& name) const {
   const auto it = columns.find(name);
   if (it == columns.end()) {
-    throw std::out_of_range("column not found: " + name);
+    throw std::out_of_range("column not found: " + name + " (available: " +
+                            available_columns(columns) + ")");
   }
   return it->second;
 }
@@ -19,6 +41,15 @@ bool DataTable::has_column(const std::string& name) const {
   return columns.find(name) != columns.end();
 }
 
+void DataTable::require_columns(std::span<const std::string> names) const {
+  for (const auto& name : names) {
+    if (!has_column(name)) {
+      throw std::out_of_range("required column missing: " + name + " (available: " +
+                              available_columns(columns) + ")");
+    }
+  }
+}
+
 std::size_t DataTable::row_count() const {
   if (columns.empty()) {
     return 0;
diff --git a/src/figure.cpp b/src/figure.cpp
@@ -26,6 +26,50 @@ AxesSpec normalize_axes_spec(AxesSpec spec) {
   return spec;
 }
 
+RenderResult invalid_input(std::string msg) {
+  return RenderResult{
+      .ok = false, .status = RenderStatus::InvalidInput, .message = std::move(msg)};
+}
+
+RenderResult validate_series(const SeriesData& s,
+                             const std::size_t axis_idx,
+                             const std::size_t series_idx) {
+  if (s.spec.has_opacity && (s.spec.opacity < 0.0 || s.spec.opacity > 1.0)) {
+    return invalid_input("axis " + std::to_string(axis_idx) + " series " +
+                         std::to_string(series_idx) + ": opacity must be in [0,1]");
+  }
+  if (s.x.size() != s.y.size()) {
+    return invalid_input("axis " + std::to_string(axis_idx) + " series " +
+                         std::to_string(series_idx) + ": x/y size mismatch");
+  }
+  switch (s.spec.type) {
+    case SeriesType::Band:
+      if (s.y2.size() != s.x.size()) {
+        return invalid_input("axis " + std::to_string(axis_idx) + " series " +
+                             std::to_string(series_idx) + ": band y2 size mismatch");
+      }
+      break;
+    case SeriesType::ErrorBars:
+      if (s.yerr_low.size() != s.x.size() || s.yerr_high.size() != s.x.size()) {
+        return invalid_input("axis " + std::to_string(axis_idx) + " series " +
+                             std::to_string(series_idx) +
+                             ": errorbar low/high size mismatch");
+      }
+      break;
+    case SeriesType::Heatmap:
+      if (s.z.size() != s.x.size()) {
+        return invalid_input("axis " + std::to_string(axis_idx) + " series " +
+                             std::to_string(series_idx) + ": heatmap z size mismatch");
+      }
+      break;
+    case SeriesType::Line:
+    case SeriesType::Scatter:
+    case SeriesType::Histogram:
+      break;
+  }
+  return RenderResult{};
+}
+
 }  // namespace
 
 void Axes::set(AxesSpec spec) { spec_ = normalize_axes_spec(std::move(spec)); }
@@ -155,11 +199,40 @@ RenderResult Figure::save(const std::filesystem::path& out_dir) const {
                         .message =
                             "No backend configured. Call set_backend() before save()."};
   }
+  const auto valid = validate_figure_for_render(*this);
+  if (!valid.ok) {
+    return valid;
+  }
   return backend_->render(*this, out_dir);
 }
 
 void Figure::set_backend(std::shared_ptr<IPlotBackend> backend) {
   backend_ = std::move(backend);
 }
 
+RenderResult validate_figure_for_render(const Figure& fig) {
+  const auto& spec = fig.spec();
+  if (spec.rows <= 0 || spec.cols <= 0) {
+    return invalid_input("rows and cols must be positive");
+  }
+  if (spec.formats.empty()) {
+    return invalid_input("no output formats requested");
+  }
+  const auto& axes = fig.all_axes();
+  const auto expected = static_cast<std::size_t>(spec.rows * spec.cols);
+  if (axes.size() != expected) {
+    return invalid_input("axes count does not match rows*cols");
+  }
+  for (std::size_t ai = 0; ai < axes.size(); ++ai) {
+    const auto& axis = axes[ai];
+    for (std::size_t si = 0; si < axis.series().size(); ++si) {
+      const auto sres = validate_series(axis.series()[si], ai, si);
+      if (!sres.ok) {
+        return sres;
+      }
+    }
+  }
+  return RenderResult{};
+}
+
 }  // namespace gnuplotpp
