Interval
========

.. cpp:class:: pandas::Interval

   Scalar type representing a single value.

Example
-------

.. code-block:: cpp

   #include <pandas/pandas.h>
   using namespace pandas;

   // Use Interval
   Interval obj;
   // ... operations ...

Constructors
------------

.. list-table::
   :widths: 55 25 20
   :header-rows: 1

   * - Signature
     - Location
     - Example
   * - ``Interval(T left, T right, const std::string& closed)``
     - pd_interval_dtype.h:292
     - :ref:`View <example-interval-interval-0>`

Arithmetic
----------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const std::string& subtype_override() const``
     - const std::string&
     - pd_interval_dtype.h:254
     - :ref:`View <example-interval-subtype_override-1>`

Comparison
----------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``T left() const``
     - T
     - pd_interval_dtype.h:303
     - :ref:`View <example-interval-left-2>`
   * - ``T length() const``
     - T
     - pd_interval_dtype.h:320
     - :ref:`View <example-interval-length-3>`

I/O
---

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::string to_string() const``
     - std::string
     - pd_interval_dtype.h:485
     - :ref:`View <example-interval-to_string-4>`

Type Checking
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool is_empty() const``
     - bool
     - pd_interval_dtype.h:357
     - :ref:`View <example-interval-is_empty-5>`

Other Methods
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``IntervalClosed closed() const``
     - IntervalClosed
     - pd_interval_dtype.h:327
     - :ref:`View <example-interval-closed-6>`
   * - ``bool closed_left() const``
     - bool
     - pd_interval_dtype.h:339
     - 
   * - ``bool closed_right() const``
     - bool
     - pd_interval_dtype.h:346
     - 
   * - ``std::string closed_string() const``
     - std::string
     - pd_interval_dtype.h:332
     - :ref:`View <example-interval-closed_string-7>`
   * - ``bool contains(T value) const``
     - bool
     - pd_interval_dtype.h:373
     - :ref:`View <example-interval-contains-8>`
   * - ``size_t hash() const``
     - size_t
     - pd_interval_dtype.h:570
     - 
   * - ``double mid() const``
     - double
     - pd_interval_dtype.h:313
     - :ref:`View <example-interval-mid-9>`
   * - ``bool overlaps(const Interval& other) const``
     - bool
     - pd_interval_dtype.h:396
     - :ref:`View <example-interval-overlaps-10>`
   * - ``std::string repr() const``
     - std::string
     - pd_interval_dtype.h:524
     - :ref:`View <example-interval-repr-11>`
   * - ``T right() const``
     - T
     - pd_interval_dtype.h:308
     - :ref:`View <example-interval-right-12>`
   * - ``void set_subtype_override(const std::string& s)``
     - void
     - pd_interval_dtype.h:252
     - :ref:`View <example-interval-set_subtype_override-13>`


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-interval-interval-0:

.. dropdown:: Interval (pd_test_3_all.cpp:24961)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 24951
      :emphasize-lines: 11

          return dataframe_tests_interval_type_inference::pd_test_interval_type_inference_main();
      }
      // ------------------- pd_test_interval_type_inference (end) ---------------------------
      
      // ------------------- pd_test_interval_repr (start) ---------------------------
      namespace dataframe_tests_interval_repr {
      
      void pd_test_interval_repr_integer() {
          std::cout << "========= Interval repr integer bounds =================";
          pandas::Interval<double> iv(0.0, 5.0);
          if (iv.repr() != "Interval(0, 5, closed='right')")
              throw std::runtime_error("repr mismatch: " + iv.repr());
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_interval_repr_float() {
          std::cout << "========= Interval repr float bounds ====================";
          pandas::Interval<double> iv(0.0, 1.5);
          if (iv.repr() != "Interval(0.0, 1.5, closed='right')")
              throw std::runtime_error("repr mismatch: " + iv.repr());
          std::cout << " -> tests passed" << std::endl;

.. _example-interval-subtype_override-1:

.. dropdown:: subtype_override (pd_test_3_all.cpp:24889)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 24879
      :emphasize-lines: 11

          return dataframe_tests_bdate_timedelta_range::pd_test_bdate_timedelta_range_main();
      }
      // ------------------- pd_test_bdate_timedelta_range (end) ---------------------------
      
      // ------------------- pd_test_interval_type_inference (begin) ---------------------------
      namespace dataframe_tests_interval_type_inference {
      
      void pd_test_interval_type_inference_breaks_int() {
          std::cout << "========= interval_type_inference_breaks_int ======================= ";
          auto idx = pandas::IntervalIndex<double>::from_breaks({0.0, 1.0, 2.0, 3.0});
          if (idx.subtype_override() != "int64")
              throw std::runtime_error("expected subtype_override 'int64', got '" + idx.subtype_override() + "'");
          std::string dtype = idx.dtype_name();
          if (dtype.find("int64") == std::string::npos)
              throw std::runtime_error("expected dtype containing 'int64', got '" + dtype + "'");
          std::string fmt = idx.format_interval(0);
          if (fmt.find('.') != std::string::npos)
              throw std::runtime_error("expected integer format without decimal, got '" + fmt + "'");
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-interval-left-2:

.. dropdown:: left (pd_test_1_all.cpp:1909)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 1899
      :emphasize-lines: 11

          if (empty.size() != 0) {
              std::cout << "[FAIL] : in test_constructors() : default constructor size" << std::endl;
              return;
          }
          if (empty.closed() != pandas::IntervalClosed::Right) {
              std::cout << "[FAIL] : in test_constructors() : default closure" << std::endl;
              return;
          }
      
          // Constructor from left/right arrays
          numpy::NDArray<numpy::float64> left(std::vector<size_t>{3});
          numpy::NDArray<numpy::float64> right(std::vector<size_t>{3});
          left.setElementAt({0}, 0.0);  right.setElementAt({0}, 1.0);
          left.setElementAt({1}, 1.0);  right.setElementAt({1}, 2.0);
          left.setElementAt({2}, 2.0);  right.setElementAt({2}, 3.0);
      
          pandas::IntervalArrayFloat64 arr1(left, right);
          if (arr1.size() != 3) {
              std::cout << "[FAIL] : in test_constructors() : array size" << std::endl;
              return;
          }

.. _example-interval-length-3:

.. dropdown:: length (pd_test_1_all.cpp:2137)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2127
      :emphasize-lines: 11

          auto mid0 = mid_arr[0];
          auto mid1 = mid_arr[1];
          auto mid2 = mid_arr[2];
          if (!mid0.has_value() || std::abs(mid0.value() - 1.0) > 1e-10 ||
              !mid1.has_value() || std::abs(mid1.value() - 3.5) > 1e-10 ||
              !mid2.has_value() || std::abs(mid2.value() - 7.5) > 1e-10) {
              std::cout << "[FAIL] : in test_left_right_mid_length() : mid()" << std::endl;
              return;
          }
      
          // Test length()
          auto len_arr = arr.length();
          if (len_arr.getElementAt({0}) != 2.0 ||
              len_arr.getElementAt({1}) != 3.0 ||
              len_arr.getElementAt({2}) != 5.0) {
              std::cout << "[FAIL] : in test_left_right_mid_length() : length()" << std::endl;
              return;
          }
      
          std::cout << "-> tests passed" << std::endl;
      }

.. _example-interval-to_string-4:

.. dropdown:: to_string (pd_test_1_all.cpp:2693)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2683
      :emphasize-lines: 11

              pandas::PeriodArray arr_m(std::vector<std::string>{
                  "2020-01",
                  "NaT",
                  "2025-06"
              }, "M");
      
              // Year
              auto years = arr_m.year();
              auto y0 = years[0];
              if (!y0.has_value() || y0.value() != 2020) {
                  std::cout << "  [FAIL] : year[0] should be 2020, got " << (y0.has_value() ? std::to_string(y0.value()) : "NA") << std::endl;
                  throw std::runtime_error("pd_test_period_array_year_month_quarter failed: year[0]");
              }
      
              auto y1 = years[1];
              if (y1.has_value()) {
                  std::cout << "  [FAIL] : year[1] should be NA (NaT)" << std::endl;
                  throw std::runtime_error("pd_test_period_array_year_month_quarter failed: year[1] should be NA");
              }
      
              auto y2 = years[2];

.. _example-interval-is_empty-5:

.. dropdown:: is_empty (pd_test_1_all.cpp:2164)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2154
      :emphasize-lines: 11

      
          // Test with right-closed intervals (a, b]
          std::vector<std::pair<numpy::float64, numpy::float64>> tuples = {
              {0.0, 1.0},   // Not empty
              {1.0, 1.0},   // Empty (1, 1] has no points
              {2.0, 2.0},   // Empty
              {2.0, 3.0}    // Not empty
          };
      
          auto arr_right = pandas::IntervalArrayFloat64::from_tuples(tuples, pandas::IntervalClosed::Right);
          auto empty_right = arr_right.is_empty();
      
          if (empty_right[0].value_or(true) != false ||
              empty_right[1].value_or(false) != true ||
              empty_right[2].value_or(false) != true ||
              empty_right[3].value_or(true) != false) {
              std::cout << "[FAIL] : in test_is_empty() : right-closed" << std::endl;
              return;
          }
      
          // Test with both-closed intervals [a, b] - [1, 1] is NOT empty

.. _example-interval-closed-6:

.. dropdown:: closed (pd_test_1_all.cpp:1903)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 1893
      :emphasize-lines: 11

      // ============================================================================
      void test_constructors() {
          std::cout << "========= IntervalArray: constructors ======================= ";
      
          // Default constructor
          pandas::IntervalArrayFloat64 empty;
          if (empty.size() != 0) {
              std::cout << "[FAIL] : in test_constructors() : default constructor size" << std::endl;
              return;
          }
          if (empty.closed() != pandas::IntervalClosed::Right) {
              std::cout << "[FAIL] : in test_constructors() : default closure" << std::endl;
              return;
          }
      
          // Constructor from left/right arrays
          numpy::NDArray<numpy::float64> left(std::vector<size_t>{3});
          numpy::NDArray<numpy::float64> right(std::vector<size_t>{3});
          left.setElementAt({0}, 0.0);  right.setElementAt({0}, 1.0);
          left.setElementAt({1}, 1.0);  right.setElementAt({1}, 2.0);
          left.setElementAt({2}, 2.0);  right.setElementAt({2}, 3.0);

.. _example-interval-closed_string-7:

.. dropdown:: closed_string (pd_test_1_all.cpp:12813)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 12803
      :emphasize-lines: 11

      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_interval_index_closed_string() {
          std::cout << "========= closed_string =========================";
      
          auto idx_right = pandas::IntervalIndex64::from_breaks({0, 1, 2}, pandas::IntervalClosed::Right);
          auto idx_left = pandas::IntervalIndex64::from_breaks({0, 1, 2}, pandas::IntervalClosed::Left);
      
          bool passed = (idx_right.closed_string() == "right" && idx_left.closed_string() == "left");
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_interval_index_closed_string() : closed_string check failed" << std::endl;
              throw std::runtime_error("pd_test_interval_index_closed_string failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_interval_index_is_left_right_closed() {
          std::cout << "========= is_left_closed/is_right_closed =========================";

.. _example-interval-contains-8:

.. dropdown:: contains (pd_test_1_all.cpp:2200)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2190
      :emphasize-lines: 11

      // Test: contains method
      // ============================================================================
      void test_contains() {
          std::cout << "========= IntervalArray: contains ======================= ";
      
          std::vector<numpy::float64> breaks = {0.0, 1.0, 2.0, 3.0};
      
          // Right-closed intervals: (0, 1], (1, 2], (2, 3]
          auto arr_right = pandas::IntervalArrayFloat64::from_breaks(breaks, pandas::IntervalClosed::Right);
      
          // Test contains(1.0) - should be in interval 0 but not 1 (since 1 is exclusive on left of interval 1)
          auto contains_1 = arr_right.contains(1.0);
          // (0, 1] contains 1: yes, (1, 2] contains 1: no (open on left), (2, 3] contains 1: no
          if (contains_1[0].value_or(false) != true ||
              contains_1[1].value_or(true) != false ||
              contains_1[2].value_or(true) != false) {
              std::cout << "[FAIL] : in test_contains() : right-closed contains 1.0" << std::endl;
              return;
          }
      
          // Left-closed intervals: [0, 1), [1, 2), [2, 3)

.. _example-interval-mid-9:

.. dropdown:: mid (pd_test_1_all.cpp:2124)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2114
      :emphasize-lines: 11

      
          // Test right()
          auto right_arr = arr.right();
          if (right_arr.getElementAt({0}) != 2.0 ||
              right_arr.getElementAt({1}) != 5.0 ||
              right_arr.getElementAt({2}) != 10.0) {
              std::cout << "[FAIL] : in test_left_right_mid_length() : right()" << std::endl;
              return;
          }
      
          // Test mid()
          auto mid_arr = arr.mid();
          // (0+2)/2=1, (2+5)/2=3.5, (5+10)/2=7.5
          auto mid0 = mid_arr[0];
          auto mid1 = mid_arr[1];
          auto mid2 = mid_arr[2];
          if (!mid0.has_value() || std::abs(mid0.value() - 1.0) > 1e-10 ||
              !mid1.has_value() || std::abs(mid1.value() - 3.5) > 1e-10 ||
              !mid2.has_value() || std::abs(mid2.value() - 7.5) > 1e-10) {
              std::cout << "[FAIL] : in test_left_right_mid_length() : mid()" << std::endl;
              return;

.. _example-interval-overlaps-10:

.. dropdown:: overlaps (pd_test_1_all.cpp:2244)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 2234
      :emphasize-lines: 11

      // Test: overlaps method
      // ============================================================================
      void test_overlaps() {
          std::cout << "========= IntervalArray: overlaps ======================= ";
      
          std::vector<numpy::float64> breaks = {0.0, 2.0, 4.0, 6.0};
          // Right-closed: (0, 2], (2, 4], (4, 6]
          auto arr = pandas::IntervalArrayFloat64::from_breaks(breaks, pandas::IntervalClosed::Right);
      
          // Check overlap with (1, 3]
          auto overlap_1_3 = arr.overlaps(1.0, 3.0);
          // (0, 2] overlaps (1, 3]? Yes (share 1-2)
          // (2, 4] overlaps (1, 3]? Yes (share 2-3)
          // (4, 6] overlaps (1, 3]? No
          if (overlap_1_3[0].value_or(false) != true ||
              overlap_1_3[1].value_or(false) != true ||
              overlap_1_3[2].value_or(true) != false) {
              std::cout << "[FAIL] : in test_overlaps() : overlaps (1, 3]" << std::endl;
              return;
          }
      

.. _example-interval-repr-11:

.. dropdown:: repr (pd_test_1_all.cpp:10906)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 10896
      :emphasize-lines: 11

          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_extension_index_repr() {
          std::cout << "========= repr =========================";
      
          pandas::CategoricalArray arr({"a", "b", "c"});
          // Use ExtensionIndex<CategoricalArray> directly to test base class repr
          pandas::ExtensionIndex<pandas::CategoricalArray> idx(arr, "test");
      
          std::string repr_str = idx.repr();
      
          bool passed = (!repr_str.empty() && repr_str.find("ExtensionIndex") != std::string::npos);
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_extension_index_repr() : repr check failed" << std::endl;
              throw std::runtime_error("pd_test_extension_index_repr failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-interval-right-12:

.. dropdown:: right (pd_test_1_all.cpp:1910)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 1900
      :emphasize-lines: 11

              std::cout << "[FAIL] : in test_constructors() : default constructor size" << std::endl;
              return;
          }
          if (empty.closed() != pandas::IntervalClosed::Right) {
              std::cout << "[FAIL] : in test_constructors() : default closure" << std::endl;
              return;
          }
      
          // Constructor from left/right arrays
          numpy::NDArray<numpy::float64> left(std::vector<size_t>{3});
          numpy::NDArray<numpy::float64> right(std::vector<size_t>{3});
          left.setElementAt({0}, 0.0);  right.setElementAt({0}, 1.0);
          left.setElementAt({1}, 1.0);  right.setElementAt({1}, 2.0);
          left.setElementAt({2}, 2.0);  right.setElementAt({2}, 3.0);
      
          pandas::IntervalArrayFloat64 arr1(left, right);
          if (arr1.size() != 3) {
              std::cout << "[FAIL] : in test_constructors() : array size" << std::endl;
              return;
          }
      

.. _example-interval-set_subtype_override-13:

.. dropdown:: set_subtype_override (pd_test_3_all.cpp:24977)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 24967
      :emphasize-lines: 11

          std::cout << "========= Interval repr float bounds ====================";
          pandas::Interval<double> iv(0.0, 1.5);
          if (iv.repr() != "Interval(0.0, 1.5, closed='right')")
              throw std::runtime_error("repr mismatch: " + iv.repr());
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_interval_repr_timedelta() {
          std::cout << "========= Interval repr timedelta subtype ===============";
          pandas::Interval<double> iv(0.0, 86400000000000.0);  // 1 day in nanos
          iv.set_subtype_override("timedelta64[ns]");
          std::string r = iv.repr();
          if (r.find("Timedelta") == std::string::npos)
              throw std::runtime_error("expected Timedelta in repr: " + r);
          if (r.find("1 days") == std::string::npos)
              throw std::runtime_error("expected '1 days' in repr: " + r);
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_interval_str_integer() {
          std::cout << "========= Interval to_string integer bounds =============";