Interval

class pandas::Interval

Scalar type representing a single value.

Example

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

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

Constructors

Signature	Location	Example
Interval(T left, T right, const std::string& closed)	pd_interval_dtype.h:292	View

Arithmetic

Signature	Return Type	Location	Example
const std::string& subtype_override() const	const std::string&	pd_interval_dtype.h:254	View

Comparison

Signature	Return Type	Location	Example
T left() const	T	pd_interval_dtype.h:303	View
T length() const	T	pd_interval_dtype.h:320	View

I/O

Signature	Return Type	Location	Example
std::string to_string() const	std::string	pd_interval_dtype.h:485	View

Type Checking

Signature	Return Type	Location	Example
bool is_empty() const	bool	pd_interval_dtype.h:357	View

Other Methods

Signature	Return Type	Location	Example
IntervalClosed closed() const	IntervalClosed	pd_interval_dtype.h:327	View
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	View
bool contains(T value) const	bool	pd_interval_dtype.h:373	View
size_t hash() const	size_t	pd_interval_dtype.h:570
double mid() const	double	pd_interval_dtype.h:313	View
bool overlaps(const Interval& other) const	bool	pd_interval_dtype.h:396	View
std::string repr() const	std::string	pd_interval_dtype.h:524	View
T right() const	T	pd_interval_dtype.h:308	View
void set_subtype_override(const std::string& s)	void	pd_interval_dtype.h:252	View

Code Examples

The following examples are extracted from the test suite.

Interval (pd_test_3_all.cpp:24961)

    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;

subtype_override (pd_test_3_all.cpp:24889)

    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;
}

left (pd_test_1_all.cpp:1909)

    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;
    }

length (pd_test_1_all.cpp:2137)

    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;
}

to_string (pd_test_1_all.cpp:2693)

        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];

is_empty (pd_test_1_all.cpp:2164)

    // 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

closed (pd_test_1_all.cpp:1903)

// ============================================================================
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);

closed_string (pd_test_1_all.cpp:12813)

    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 =========================";

contains (pd_test_1_all.cpp:2200)

// 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)

mid (pd_test_1_all.cpp:2124)

    // 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;

overlaps (pd_test_1_all.cpp:2244)

// 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;
    }

repr (pd_test_1_all.cpp:10906)

    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;
}

right (pd_test_1_all.cpp:1910)

        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;
    }

set_subtype_override (pd_test_3_all.cpp:24977)

    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 =============";