ffi_core.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (C) 2026 Vallés Puig, Ramon
 
#pragma once
 
#include <algorithm>
#include <cmath>
#include <iomanip>
#include <iostream>
#include <limits>
#include <optional>
#include <ostream>
#include <sstream>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
extern "C" {
#include "qtty_ffi.h"
}
 
namespace qtty {
 
// ============================================================================
// Exception Hierarchy
// ============================================================================
// All qtty exceptions derive from std::runtime_error for compatibility with
// standard exception handling practices. The hierarchy provides fine-grained
// error types for different failure modes when interacting with the FFI layer.
 
// Exception types for error handling
class QttyException : public std::runtime_error {
public:
  explicit QttyException(const std::string &msg) : std::runtime_error(msg) {}
};
 
class InvalidUnitError : public QttyException {
public:
  explicit InvalidUnitError(const std::string &msg) : QttyException(msg) {}
};
 
class IncompatibleDimensionsError : public QttyException {
public:
  explicit IncompatibleDimensionsError(const std::string &msg) : QttyException(msg) {}
};
 
class NullPointerError : public QttyException {
public:
  explicit NullPointerError(const std::string &msg) : QttyException(msg) {}
};
 
class ConversionError : public QttyException {
public:
  explicit ConversionError(const std::string &msg) : QttyException(msg) {}
};
 
// ============================================================================
// Error Translation from C FFI to C++ Exceptions
// ============================================================================
// Maps C-style integer error codes from the Rust FFI layer to typed C++
// exceptions. This provides idiomatic error handling for C++ users while
// maintaining compatibility with the C FFI boundary.
 
// Helper function to check status and throw appropriate exceptions
inline void check_status(QttyStatus status, const char *operation) {
  if (status == QTTY_STATUS_OK) {
    return;
  }
 
  std::string msg = std::string(operation) + " failed: ";
  switch (status) {
  case QTTY_STATUS_UNKNOWN_UNIT:
    throw InvalidUnitError(msg + "unknown unit");
  case QTTY_STATUS_INCOMPATIBLE_DIM:
    throw IncompatibleDimensionsError(msg + "incompatible dimensions");
  case QTTY_STATUS_NULL_OUT:
    throw NullPointerError(msg + "null output pointer");
  case QTTY_STATUS_BUFFER_TOO_SMALL:
    throw QttyException(msg + "output buffer too small");
  default:
    throw QttyException(msg + "unknown error");
  }
}
 
// ============================================================================
// Forward Declarations and Type Traits
// ============================================================================
 
// Forward declarations
template <typename UnitTag> class Quantity;
template <typename NumeratorTag, typename DenominatorTag> struct CompoundTag;
 
// Type trait to detect compound (derived) unit tags
template <typename T> struct is_compound : std::false_type {};
template <typename N, typename D> struct is_compound<CompoundTag<N, D>> : std::true_type {};
template <typename T> inline constexpr bool is_compound_v = is_compound<T>::value;
 
// Template trait to get unit ID from unit tag
// Each unit tag (e.g., MeterTag) must specialize this template to provide
// its corresponding C FFI unit ID constant (e.g., UNIT_ID_METER).
// Specializations are auto-generated in include/qtty/units/*.hpp
//
// For compound tags, specializations provide numerator_unit_id() and
// denominator_unit_id() instead of a single unit_id().
template <typename UnitTag> struct UnitTraits {
  // Default symbol returns empty string. Specialize for units that have
  // symbols.
  static constexpr std::string_view symbol() { return ""; }
};
 
// Detect whether a unit tag's UnitTraits specialization exposes dimension().
template <typename Tag, typename = void> struct has_dimension : std::false_type {};
template <typename Tag>
struct has_dimension<Tag, std::void_t<decltype(UnitTraits<Tag>::dimension())>> : std::true_type {};
 
// True for simple unit tags whose dimension is Dimensionless. Compound tags and
// tags without a generated dimension() are treated as non-dimensionless.
template <typename Tag> constexpr bool is_dimensionless_tag() {
  if constexpr (has_dimension<Tag>::value) {
    return UnitTraits<Tag>::dimension() == DIMENSION_ID_DIMENSIONLESS;
  } else {
    return false;
  }
}
template <typename Tag> inline constexpr bool is_dimensionless_v = is_dimensionless_tag<Tag>();
 
// Helper to extract tag from either a tag or Quantity<Tag>
// This allows .to<>() to accept both Quantity<KilometerTag> and KilometerTag,
// making the API more flexible and user-friendly.
template <typename T> struct ExtractTag {
  using type = T;
};
 
template <typename Tag> struct ExtractTag<Quantity<Tag>> {
  using type = Tag;
};
 
// ============================================================================
// Quantity Template Class
// ============================================================================
// The core abstraction representing a physical quantity with compile-time
// type safety. Each instantiation (e.g., Quantity<MeterTag>) is a distinct
// type, preventing accidental mixing of incompatible units at compile time.
//
// Key Design Decisions:
// - Header-only for zero-cost abstraction (all code inlined)
// - constexpr constructors enable compile-time quantity creation
// - explicit constructor prevents implicit double-to-Quantity conversions
// - Conversions go through the Rust FFI layer for correctness
 
// Base Quantity template class
template <typename UnitTag> class Quantity {
private:
  double m_value;
 
public:
  using unit_tag = UnitTag;
 
  // Constructors
  constexpr Quantity() : m_value(0.0) {}
  constexpr explicit Quantity(double value) : m_value(value) {}
 
  // Get the unit ID for this quantity type
  static constexpr UnitId unit_id() { return UnitTraits<UnitTag>::unit_id(); }
 
  // Get the raw value
  constexpr double value() const { return m_value; }
 
  // Get a reference to the raw value (mirrors Rust `value_ref`).
  constexpr const double &value_ref() const { return m_value; }
 
  // Strip the unit and return the underlying scalar (mirrors Rust
  // `erase_unit_raw`). Semantically identical to `value()` but named to make
  // the intent of discarding dimensional information explicit.
  constexpr double erase_unit_raw() const { return m_value; }
 
  // ========================================================================
  // Scalar Constructors / Constants (mirror Rust associated constants)
  // ========================================================================
 
  // Additive / multiplicative identities.
  static constexpr Quantity zero() { return Quantity(0.0); }
  static constexpr Quantity one() { return Quantity(1.0); }
 
  // IEEE-754 special values (mirror Rust `NAN`, `INFINITY`, `NEG_INFINITY`).
  static Quantity nan() { return Quantity(std::numeric_limits<double>::quiet_NaN()); }
  static Quantity infinity() { return Quantity(std::numeric_limits<double>::infinity()); }
  static Quantity neg_infinity() { return Quantity(-std::numeric_limits<double>::infinity()); }
 
  // ========================================================================
  // Unit Conversion
  // ========================================================================
  // Converts this quantity to a different unit of the same dimension.
  // The conversion is performed by the Rust qtty-ffi library to ensure
  // correctness and consistency with the authoritative conversion factors.
  //
  // Accepts either a tag type (e.g., KilometerTag) or a Quantity type
  // (e.g., Kilometer) for convenience, thanks to the ExtractTag helper.
  //
  // Throws IncompatibleDimensionsError if attempting to convert between
  // different dimensions (e.g., length to time).
 
  // Convert to another unit type (accepts either Tag or Quantity<Tag>)
  template <typename TargetType> Quantity<typename ExtractTag<TargetType>::type> to() const {
    using TargetTag = typename ExtractTag<TargetType>::type;
 
    if constexpr (is_compound_v<UnitTag>) {
      // Compound → compound conversion via qtty_derived_convert
      static_assert(is_compound_v<TargetTag>, "Cannot convert compound unit to simple unit");
      qtty_derived_quantity_t src_qty;
      qtty_derived_quantity_t dst_qty;
 
      QttyStatus status = qtty_derived_make(m_value, UnitTraits<UnitTag>::numerator_unit_id(),
                                            UnitTraits<UnitTag>::denominator_unit_id(), &src_qty);
      check_status(status, "Creating derived source quantity");
 
      status = qtty_derived_convert(src_qty, UnitTraits<TargetTag>::numerator_unit_id(),
                                    UnitTraits<TargetTag>::denominator_unit_id(), &dst_qty);
      check_status(status, "Converting derived units");
 
      return Quantity<TargetTag>(dst_qty.value);
    } else {
      // Simple unit conversion via qtty_quantity_convert
      qtty_quantity_t src_qty;
      qtty_quantity_t dst_qty;
 
      QttyStatus status = qtty_quantity_make(m_value, unit_id(), &src_qty);
      check_status(status, "Creating source quantity");
 
      status = qtty_quantity_convert(src_qty, UnitTraits<TargetTag>::unit_id(), &dst_qty);
      check_status(status, "Converting units");
 
      return Quantity<TargetTag>(dst_qty.value);
    }
  }
 
  // ========================================================================
  // Arithmetic Operators (Same Unit)
  // ========================================================================
  // Addition and subtraction only work between quantities of the same unit.
  // This enforces dimensional correctness at compile time. To add quantities
  // of different units, explicitly convert one to match the other first.
 
  // Arithmetic operators - same unit
  Quantity operator+(const Quantity &other) const { return Quantity(m_value + other.m_value); }
 
  Quantity operator-(const Quantity &other) const { return Quantity(m_value - other.m_value); }
 
  // ========================================================================
  // Scalar Operations
  // ========================================================================
  // Multiplying or dividing a quantity by a scalar preserves the unit.
  // E.g., 10 meters * 2 = 20 meters
 
  // Scalar multiplication and division
  Quantity operator*(double scalar) const { return Quantity(m_value * scalar); }
 
  Quantity operator/(double scalar) const { return Quantity(m_value / scalar); }
 
  // Friend function for scalar * quantity
  friend Quantity operator*(double scalar, const Quantity &q) { return q * scalar; }
 
  // ========================================================================
  // Comparison Operators
  // ========================================================================
  // All standard comparison operators are provided for convenience.
  // Comparisons only work between quantities of the same unit type,
  // enforcing type safety at compile time.
 
  // Comparison operators
  bool operator==(const Quantity &other) const { return m_value == other.m_value; }
 
  bool operator!=(const Quantity &other) const { return m_value != other.m_value; }
 
  bool operator<(const Quantity &other) const { return m_value < other.m_value; }
 
  bool operator>(const Quantity &other) const { return m_value > other.m_value; }
 
  bool operator<=(const Quantity &other) const { return m_value <= other.m_value; }
 
  bool operator>=(const Quantity &other) const { return m_value >= other.m_value; }
 
  // ========================================================================
  // Compound Assignment Operators
  // ========================================================================
  // Modify the quantity in place for efficiency.
 
  // Compound assignment operators
  Quantity &operator+=(const Quantity &other) {
    m_value += other.m_value;
    return *this;
  }
 
  Quantity &operator-=(const Quantity &other) {
    m_value -= other.m_value;
    return *this;
  }
 
  Quantity &operator*=(double scalar) {
    m_value *= scalar;
    return *this;
  }
 
  Quantity &operator/=(double scalar) {
    m_value /= scalar;
    return *this;
  }
 
  // ========================================================================
  // Unary Operators and Utilities
  // ========================================================================
 
  // Unary operators
  Quantity operator-() const { return Quantity(-m_value); }
 
  Quantity abs() const { return Quantity(std::abs(m_value)); }
 
  // ========================================================================
  // Scalar Reductions (same unit) — mirror Rust `min`/`max`/`clamp`/`mean`
  // ========================================================================
 
  Quantity min(const Quantity &other) const { return Quantity(std::min(m_value, other.m_value)); }
 
  Quantity max(const Quantity &other) const { return Quantity(std::max(m_value, other.m_value)); }
 
  Quantity clamp(const Quantity &min_val, const Quantity &max_val) const {
    return Quantity(std::max(min_val.m_value, std::min(m_value, max_val.m_value)));
  }
 
  // Arithmetic mean of two same-unit quantities.
  Quantity mean(const Quantity &other) const { return Quantity((m_value + other.m_value) * 0.5); }
 
  // ========================================================================
  // Floating-point Predicates — mirror Rust `is_nan`/`is_infinite`/`is_finite`
  // ========================================================================
 
  bool is_nan() const { return std::isnan(m_value); }
  bool is_infinite() const { return std::isinf(m_value); }
  bool is_finite() const { return std::isfinite(m_value); }
 
  // ========================================================================
  // Scalar Math — mirror Rust `signum`/`scalar_sqrt`/rounding helpers
  // ========================================================================
 
  // Sign of the underlying scalar (raw, unitless). Mirrors Rust `signum`.
  double signum() const { return std::copysign(1.0, m_value); }
 
  // Square root of the underlying scalar, returned raw (unitless). Mirrors
  // Rust `scalar_sqrt` (NOT the dimension-changing `sqrt`).
  double scalar_sqrt() const { return std::sqrt(m_value); }
 
  // Rounding helpers preserve the unit (mirror Rust).
  Quantity floor() const { return Quantity(std::floor(m_value)); }
  Quantity ceil() const { return Quantity(std::ceil(m_value)); }
  Quantity round() const { return Quantity(std::round(m_value)); }
  Quantity trunc() const { return Quantity(std::trunc(m_value)); }
  Quantity fract() const { return Quantity(m_value - std::trunc(m_value)); }
 
  // Euclidean remainder by a scalar (mirrors Rust `rem_euclid`).
  Quantity rem_euclid(double rhs) const {
    double r = std::fmod(m_value, rhs);
    if (r < 0.0) {
      r += std::abs(rhs);
    }
    return Quantity(r);
  }
 
  // ========================================================================
  // Unit-aware Comparison — mirror Rust `eq_unit`/`cmp_unit`
  // ========================================================================
  // Compare against a quantity expressed in a different unit of the same
  // dimension. The other quantity is converted into this unit (through the
  // Rust FFI) before comparison, so the comparison is value-correct across
  // units. Throws IncompatibleDimensionsError if the dimensions differ.
 
  template <typename V> bool eq_unit(const Quantity<V> &other) const {
    return m_value == other.template to<UnitTag>().value();
  }
 
  // Returns -1, 0 or 1 when ordered, or std::nullopt when either operand is
  // NaN (mirrors Rust `cmp_unit` returning `Option<Ordering>`).
  template <typename V> std::optional<int> cmp_unit(const Quantity<V> &other) const {
    double rhs = other.template to<UnitTag>().value();
    if (std::isnan(m_value) || std::isnan(rhs)) {
      return std::nullopt;
    }
    if (m_value < rhs) {
      return -1;
    }
    if (m_value > rhs) {
      return 1;
    }
    return 0;
  }
 
  // ========================================================================
  // String Formatting
  // ========================================================================
  // Format the quantity as a human-readable string, mirroring Rust's format
  // annotations.  The mapping is:
  //
  //   Rust             C++
  //   {}               format()
  //   {:.2}            format(2)
  //   {:e}             format(-1, QTTY_FMT_LOWER_EXP)
  //   {:.4e}           format(4,  QTTY_FMT_LOWER_EXP)
  //   {:E}             format(-1, QTTY_FMT_UPPER_EXP)
  //   {:.4E}           format(4,  QTTY_FMT_UPPER_EXP)
  //
  // The formatting logic lives in the Rust qtty-ffi library, so precision
  // semantics are identical on both sides of the FFI boundary.
 
  std::string format(int precision = -1, uint32_t flags = QTTY_FMT_DEFAULT) const {
    qtty_quantity_t qty;
    QttyStatus make_status = qtty_quantity_make(m_value, unit_id(), &qty);
    check_status(make_status, "format: creating quantity");
 
    char buf[512];
    QttyStatus result = qtty_quantity_format(qty, precision, flags, buf, sizeof(buf));
    if (result == QTTY_STATUS_BUFFER_TOO_SMALL) {
      // Retry with a generous large buffer (quantities should never need this)
      char big_buf[4096];
      result = qtty_quantity_format(qty, precision, flags, big_buf, sizeof(big_buf));
      if (result < 0) {
        throw QttyException("format: buffer too small even at 4096 bytes");
      }
      return std::string(big_buf);
    }
    if (result < 0) {
      check_status(result, "format: formatting quantity");
    }
    return std::string(buf);
  }
};
 
// ============================================================================
// Stream Insertion Operator
// ============================================================================
// Prints a quantity with its unit symbol, e.g., "1500 m" or "42.5 km".
//
// Because this streams `q.value()` (a plain double) directly into the
// `std::ostream`, all standard stream format manipulators are respected:
//
//   std::cout << std::fixed << std::setprecision(2) << qty;   // "1234.57 m"
//   std::cout << std::scientific << qty;                       // "1.23457e+003
//   m" std::cout << std::scientific << std::setprecision(4)
//             << qty;                                          // "1.2346e+003
//             m"
//
// For `std::format` (C++20) see the std::formatter specialisation below.
 
template <typename UnitTag> std::ostream &operator<<(std::ostream &os, const Quantity<UnitTag> &q) {
  os << q.value() << " " << UnitTraits<UnitTag>::symbol();
  return os;
}
 
} // namespace qtty
 
// ============================================================================
// C++20 std::formatter specialisation
// ============================================================================
// Allows `std::format` and `std::print` to be used with any Quantity type,
// honouring the same format specifiers as std::formatter<double>:
//
//   std::format("{}", qty)          → "1234.56789 s"
//   std::format("{:.2f}", qty)      → "1234.57 s"
//   std::format("{:e}", qty)        → "1.23457e+03 s"
//   std::format("{:.4e}", qty)      → "1.2346e+03 s"
//   std::format("{:E}", qty)        → "1.23457E+03 s"
//   std::format("{:>15.2f}", qty)   → "        1234.57 s"   (number padded, not
//   symbol)
//
// Note: width / fill / align specifications are applied to the numeric part
// only; the unit symbol is always appended directly after without padding.
// This mirrors the behaviour of the Rust Display/LowerExp/UpperExp impls.
 
#if __cplusplus >= 202002L
#include <format>
 
namespace std {
 
template <typename UnitTag> struct formatter<qtty::Quantity<UnitTag>> {
private:
  std::formatter<double> double_fmt_;
 
public:
  template <typename ParseContext> constexpr auto parse(ParseContext &ctx) {
    return double_fmt_.parse(ctx);
  }
 
  template <typename FormatContext>
  auto format(const qtty::Quantity<UnitTag> &qty, FormatContext &ctx) const {
    auto out = double_fmt_.format(qty.value(), ctx);
    return std::format_to(out, " {}", qtty::UnitTraits<UnitTag>::symbol());
  }
};
 
} // namespace std
#endif // __cplusplus >= 202002L