C++ refactor

CMakeLists.txt

@@ -57,6 +57,7 @@ target_sources(ndtbl
       include/ndtbl/types.hpp
       include/ndtbl/axis.hpp
       include/ndtbl/grid.hpp
+      include/ndtbl/exceptions.hpp
       include/ndtbl/field_group.hpp
       include/ndtbl/runtime_field_group.hpp
       include/ndtbl/diagnostics.hpp

README.md

@@ -36,7 +36,6 @@ Use the Python package when you want a pip-installable Python interface for crea
 
 If you want to inspect `.ndtbl`files with a C++ command-line tool, use the C++ `ndtbl-inspect` executable built from `app/`. It is not prebuilt; it becomes available only after running the local CMake build.
 
-
 ## 📋 Prerequisites
 
 Building the C++ project requires:
@@ -141,6 +140,32 @@ unwanted values. Bounds handling is independent of interpolation order:
 queries outside the table domain can either clamp or throw according to the
 selected `bounds_policy`.
 
+## C++ Error Handling
+
+The C++ API distinguishes invalid table data, system I/O failures, and invalid
+object state through `ndtbl::FormatError`, `ndtbl::IOError`, and
+`ndtbl::StateError`. All three derive from `ndtbl::Error` and provide the
+standard `what()` message interface:
+
+```cpp
+try {
+  const auto group = ndtbl::read_runtime_field_group<2>(path);
+  // Use group.
+} catch (const ndtbl::FormatError& error) {
+  // The file is malformed, unsupported, truncated, or incompatible.
+} catch (const ndtbl::IOError& error) {
+  // Opening, reading, mapping, or another system operation failed.
+} catch (const ndtbl::StateError& error) {
+  // An operation required a populated runtime field group.
+} catch (const ndtbl::Error& error) {
+  // Any other ndtbl-specific runtime failure.
+}
+```
+
+Argument, bounds, and size failures continue to use the standard
+`std::invalid_argument`, `std::out_of_range`, and `std::overflow_error`
+categories.
+
 ## 🐍 Python Package
 
 The repository also ships a separate Python package in [`python/ndtbl/`](https://github.com/thomasisensee/ndtbl/tree/main/python/ndtbl).

app/ndtbl_inspect.cpp

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: MIT
+
 #include "ndtbl/ndtbl.hpp"
 
 #include <exception>

benchmarks/lookup_benchmarks.cpp

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: MIT
+
 #include "ndtbl/ndtbl.hpp"
 
 #include <benchmark/benchmark.h>
@@ -200,7 +202,7 @@ make_queries(const std::array<ndtbl::Axis, Dim>& axes, std::size_t count)
   for (std::size_t query = 0; query < count; ++query) {
     std::array<double, Dim> coordinates = {};
     for (std::size_t axis = 0; axis < Dim; ++axis) {
-      const double fraction =
+      const auto fraction =
         static_cast<double>(((query + 17u * axis) % 997u) + 1u) / 998.0;
       coordinates[axis] =
         axes[axis].min() + fraction * (axes[axis].max() - axes[axis].min());

doc/cppapi.rst

@@ -6,6 +6,18 @@
 API reference
 -------------
 
+.. doxygenclass:: ndtbl::Error
+   :members:
+
+.. doxygenclass:: ndtbl::FormatError
+   :members:
+
+.. doxygenclass:: ndtbl::IOError
+   :members:
+
+.. doxygenclass:: ndtbl::StateError
+   :members:
+
 .. doxygenclass:: ndtbl::Axis
    :members:
 

include/ndtbl/axis.hpp

@@ -145,7 +145,7 @@ class Axis
         return min_;
       }
 
-      const double fraction =
+      const auto fraction =
         static_cast<double>(index) / static_cast<double>(size_ - 1);
       return min_ + fraction * (max_ - min_);
     }
@@ -173,25 +173,6 @@ class Axis
     return coordinates_;
   }
 
-  /**
-   * @brief Check whether two axes describe the same grid support.
-   *
-   * @param other Axis to compare against.
-   * @return `true` if both axes represent the same support points.
-   */
-  bool equivalent(const Axis& other) const
-  {
-    if (kind_ != other.kind_ || size_ != other.size_) {
-      return false;
-    }
-
-    if (kind_ == axis_kind::uniform) {
-      return min_ == other.min_ && max_ == other.max_;
-    }
-
-    return coordinates_ == other.coordinates_;
-  }
-
   /**
    * @brief Locate the interpolation interval and upper weight for a query.
    *
@@ -239,9 +220,9 @@ class Axis
       return std::make_pair(size_ - 2, 1.0);
     }
 
-    const std::vector<double>::const_iterator upper =
+    const auto upper =
       std::upper_bound(coordinates_.begin(), coordinates_.end(), value);
-    const std::size_t lower_index =
+    const auto lower_index =
       static_cast<std::size_t>(std::distance(coordinates_.begin(), upper) - 1);
     const double lower_value = coordinates_[lower_index];
     const double upper_value = coordinates_[lower_index + 1];