IndexBase

class pandas::IndexBase

Index class for axis labels in pandas data structures.

Example

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

// Create IndexBase
IndexBase<int64_t> idx({1, 2, 3}, "my_index");
size_t len = idx.size();

Indexing / Selection

Signature	Return Type	Location	Example
virtual std::optional<std::pair<int64_t, std::string>> get_datetime_ns_at(size_t pos) const	virtual std::optional<std::pair<int64_t, std::string>>	pd_index_base.h:195	View
virtual std::optional<std::string> get_freq() const	virtual std::optional<std::string>	pd_index_base.h:218	View
virtual int64_t get_loc_str(const std::string& key_str) const = 0	virtual int64_t	pd_index_base.h:115	View
virtual std::optional<size_t> get_loc_string(const std::string& key) const = 0	virtual std::optional<size_t>	pd_index_base.h:137	View
virtual std::string get_value_str(size_t index) const = 0	virtual std::string	pd_index_base.h:154	View

Combining

Signature	Return Type	Location	Example
static std::optional<std::string> combine_names( const std::optional<std::string>& a, const std::optional<std::string>& b)	static std::optional<std::string>	pd_index_base.h:88

I/O

Signature	Return Type	Location	Example
virtual std::string to_string() const = 0	virtual std::string	pd_index_base.h:174	View
virtual std::vector<std::string> to_string_vector() const = 0	virtual std::vector<std::string>	pd_index_base.h:147	View

Set Operations

Signature	Return Type	Location	Example
virtual numpy::NDArray<numpy::bool_> isin(const std::vector<int64_t>& values) const	virtual numpy::NDArray<numpy::bool_>	pd_index_base.h:232	View

Type Checking

Signature	Return Type	Location	Example
virtual bool is_range_index() const	virtual bool	pd_index_base.h:188	View
virtual bool is_unique() const = 0	virtual bool	pd_index_base.h:203	View

Other Methods

Signature	Return Type	Location	Example
void clear_cache() const override = 0	void	pd_index_base.h:251	View
virtual std::unique_ptr<IndexBase> clone() const = 0	virtual std::unique_ptr<IndexBase>	pd_index_base.h:160	View
virtual bool contains_str(const std::string& key_str) const = 0	virtual bool	pd_index_base.h:108	View
virtual std::string dtype_name() const = 0	virtual std::string	pd_index_base.h:72	View
virtual bool empty() const = 0	virtual bool	pd_index_base.h:61	View
bool has_cached_values() const override = 0	bool	pd_index_base.h:256	View
virtual bool has_duplicates() const = 0	virtual bool	pd_index_base.h:208	View
virtual std::string inferred_type() const = 0	virtual std::string	pd_index_base.h:97	View
virtual std::optional<std::string> name() const = 0	virtual std::optional<std::string>	pd_index_base.h:77	View
virtual size_t nbytes() const = 0	virtual size_t	pd_index_base.h:67	View
virtual std::string repr() const = 0	virtual std::string	pd_index_base.h:179	View
virtual void set_name(const std::optional<std::string>& name) = 0	virtual void	pd_index_base.h:82	View
virtual size_t size() const = 0	virtual size_t	pd_index_base.h:56	View
virtual IndexTypeId type_id() const = 0	virtual IndexTypeId	pd_index_base.h:165	View

Code Examples

The following examples are extracted from the test suite.

get_datetime_ns_at (pd_test_3_all.cpp:26202)

    auto [is_dt, data] = s.idxmin_typed();
    if (!is_dt) throw std::runtime_error("Expected datetime result");
    if (data.first != 2000000000LL) throw std::runtime_error("Expected 2000000000 ns, got " + std::to_string(data.first));
    std::cout << "PASSED" << std::endl;
}

void pd_test_idxmax_min_typed_non_datetime_ns() {
    std::cout << "  pd_test_idxmax_min_typed_non_datetime_ns: ";
    // RangeIndex's get_datetime_ns_at should return nullopt
    ::pandas::Series<::numpy::float64> s({1.0, 2.0, 3.0});
    auto result = s.index().get_datetime_ns_at(0);
    if (result.has_value()) throw std::runtime_error("Expected nullopt for non-datetime index");
    std::cout << "PASSED" << std::endl;
}

void pd_test_idxmax_min_typed_string_fallback() {
    std::cout << "  pd_test_idxmax_min_typed_string_fallback: ";
    // Verify that existing idxmax() string method still works
    ::pandas::Series<::numpy::float64> s({1.0, 3.0, 2.0});
    std::string result = s.idxmax();
    if (result != "1") throw std::runtime_error("Expected '1', got '" + result + "'");

get_freq (pd_test_2_all.cpp:20397)

    std::vector<numpy::datetime64> ts = {
        numpy::datetime64(0LL, numpy::DateTimeUnit::Day),
        numpy::datetime64(1LL, numpy::DateTimeUnit::Day),
        numpy::datetime64(2LL, numpy::DateTimeUnit::Day)
    };
    auto dt_idx = std::make_unique<pandas::DatetimeIndex>(ts);
    dt_idx->set_freq(std::string("D"));
    df.set_index(std::move(dt_idx));

    auto s = df.extract_column_as_numeric_series("val");
    check(s.get_freq().has_value(), "freq propagated");
    if (s.get_freq().has_value()) {
        check(s.get_freq().value() == "D", "freq value D");
    }

    // Test MultiIndex propagation
    pandas::DataFrame df2;
    std::vector<numpy::float64> vals2 = {10.0, 20.0};
    df2.insert(0, "A", std::make_unique<pandas::Series<numpy::float64>>(vals2, "A"), true);
    std::vector<std::vector<std::string>> arrays = {{"x", "y"}, {"1", "2"}};
    std::vector<std::optional<std::string>> names = {std::string("first"), std::string("second")};

get_loc_str (pd_test_1_all.cpp:10890)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_contains_str_get_loc_str() {
    std::cout << "========= contains_str/get_loc_str =========================";

    pandas::CategoricalArray arr({"apple", "banana", "cherry"});
    pandas::CategoricalIndex idx(arr);

    bool passed = (idx.contains_str("apple") && !idx.contains_str("grape") &&
                   idx.get_loc_str("banana") == 1 && idx.get_loc_str("grape") == -1);
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_extension_index_contains_str_get_loc_str() : contains_str/get_loc_str check failed" << std::endl;
        throw std::runtime_error("pd_test_extension_index_contains_str_get_loc_str failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_repr() {
    std::cout << "========= repr =========================";

get_loc_string (pd_test_3_all.cpp:28108)

        vals.push_back(numpy::timedelta64(ns, numpy::DateTimeUnit::Nanosecond));
    }
    return pandas::TimedeltaArray(vals);
}

void pd_test_getitem_timedelta_str_lookup() {
    std::cout << "  -- pd_test_getitem_timedelta_str_lookup --" << std::endl;
    int fail = 0;
    auto tda = ge_make_tda({1 * GE_NS_PER_DAY, 2 * GE_NS_PER_DAY, 3 * GE_NS_PER_DAY});
    pandas::TimedeltaIndex tdi(tda);
    auto pos = tdi.get_loc_string("2 days");
    if (!pos.has_value()) { std::cout << "    FAIL: '2 days' not found" << std::endl; fail++; }
    else if (*pos != 1) { std::cout << "    FAIL: expected pos=1, got " << *pos << std::endl; fail++; }
    if (fail == 0) std::cout << "    OK" << std::endl;
    if (fail) throw std::runtime_error("pd_test_getitem_timedelta_str_lookup failed");
}

void pd_test_getitem_timedelta_str_not_found() {
    std::cout << "  -- pd_test_getitem_timedelta_str_not_found --" << std::endl;
    int fail = 0;
    auto tda = ge_make_tda({1 * GE_NS_PER_DAY});

get_value_str (pd_test_1_all.cpp:4665)

            auto corr_df = df.corr();

            // Check dimensions
            bool passed = corr_df.nrows() == 2 && corr_df.ncols() == 2;
            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_aggregation_dataframe_corr() : corr should be 2x2" << std::endl;
                throw std::runtime_error("pd_test_aggregation_dataframe_corr failed: corr should be 2x2");
            }

            // Diagonal should be 1.0
            std::string aa = corr_df["A"].get_value_str(0);
            passed = std::abs(std::stod(aa) - 1.0) < 0.001;
            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_aggregation_dataframe_corr() : diagonal should be 1.0" << std::endl;
                throw std::runtime_error("pd_test_aggregation_dataframe_corr failed: diagonal should be 1.0");
            }

            // A-B correlation should be 1.0 (perfect correlation)
            std::string ab = corr_df["B"].get_value_str(0);
            passed = std::abs(std::stod(ab) - 1.0) < 0.001;
            if (!passed) {

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

to_string_vector (pd_test_1_all.cpp:10871)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_to_string_vector() {
    std::cout << "========= to_string_vector =========================";

    pandas::CategoricalArray arr({"a", std::nullopt, "c"});
    pandas::CategoricalIndex idx(arr);

    auto str_vec = idx.to_string_vector();

    bool passed = (str_vec.size() == 3 &&
                   str_vec[0] == "a" && str_vec[1] == "NA" && str_vec[2] == "c");
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_extension_index_to_string_vector() : to_string_vector check failed" << std::endl;
        throw std::runtime_error("pd_test_extension_index_to_string_vector failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

isin (pd_test_1_all.cpp:5938)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_categorical_index_isin() {
    std::cout << "========= inherited isin ==============================";

    pandas::CategoricalArray arr({"a", "b", "c", "d"});
    pandas::CategoricalIndex idx(arr);

    std::vector<std::string> values = {"a", "c"};
    numpy::NDArray<numpy::bool_> mask = idx.isin(values);

    bool passed = (mask.getSize() == 4 &&
                   mask.getElementAt({0}) == true &&   // a
                   mask.getElementAt({1}) == false &&  // b
                   mask.getElementAt({2}) == true &&   // c
                   mask.getElementAt({3}) == false);   // d
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_isin()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_isin failed");
    }

is_range_index (pd_test_5_all.cpp:21595)

                  << local_fail << " checks failed" << std::endl;
        throw std::runtime_error("f_test_merge_int_dtype_upcast_4 failed");
    }
    std::cout << " -> tests passed" << std::endl;
}

// --- f_test_rename_column_width_bug_4.cpp ---

namespace f_test_rename_column_width_bug_4_ns {

static bool is_range_index(const pandas::DataFrame& df) {
    return dynamic_cast<const pandas::RangeIndex*>(&df.index()) != nullptr;
}

static void diff_print(const std::string& got,
                       const std::string& expected,
                       const std::string& label) {
    if (got == expected) return;
    std::cout << "    [" << label << "] to_string MISMATCH\n";
    std::cout << "    --- got ---\n";
    std::cout << got << "\n";

is_unique (pd_test_1_all.cpp:5962)

void pd_test_categorical_index_is_unique() {
    std::cout << "========= inherited is_unique =========================";

    pandas::CategoricalArray arr_unique({"a", "b", "c"});
    pandas::CategoricalArray arr_dups({"a", "b", "a"});

    pandas::CategoricalIndex idx_unique(arr_unique);
    pandas::CategoricalIndex idx_dups(arr_dups);

    bool passed = (idx_unique.is_unique() && !idx_dups.is_unique());
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_is_unique()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_is_unique failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_categorical_index_hasnans() {
    std::cout << "========= inherited hasnans ===========================";

clear_cache (pd_test_1_all.cpp:19413)

            s.mean();
            s.min();
            s.max();

            passed = s.has_cached_values() == true;
            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_series_cache() : cache not populated" << std::endl;
                throw std::runtime_error("pd_test_series_cache failed: cache not populated");
            }

            s.clear_cache();
            passed = s.has_cached_values() == false;
            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_series_cache() : cache not cleared" << std::endl;
                throw std::runtime_error("pd_test_series_cache failed: cache not cleared");
            }

            std::cout << " -> tests passed" << std::endl;
        }

        void pd_test_series_string_repr() {

clone (pd_test_1_all.cpp:5776)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_categorical_index_clone() {
    std::cout << "========= clone =======================================";

    pandas::CategoricalArray arr({"p", "q", "r"});
    pandas::CategoricalIndex idx(arr, "original");

    std::unique_ptr<pandas::IndexBase> cloned = idx.clone();

    bool passed = (cloned != nullptr && cloned->size() == idx.size() &&
                   cloned->name() == idx.name());
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_clone()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_clone failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

contains_str (pd_test_1_all.cpp:10889)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_contains_str_get_loc_str() {
    std::cout << "========= contains_str/get_loc_str =========================";

    pandas::CategoricalArray arr({"apple", "banana", "cherry"});
    pandas::CategoricalIndex idx(arr);

    bool passed = (idx.contains_str("apple") && !idx.contains_str("grape") &&
                   idx.get_loc_str("banana") == 1 && idx.get_loc_str("grape") == -1);
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_extension_index_contains_str_get_loc_str() : contains_str/get_loc_str check failed" << std::endl;
        throw std::runtime_error("pd_test_extension_index_contains_str_get_loc_str failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_repr() {

dtype_name (pd_test_1_all.cpp:10104)

}

void pd_test_extension_index_array_constructor() {
    std::cout << "========= array constructor =========================";

    pandas::CategoricalArray arr({"apple", "banana", "apple", "cherry"});
    pandas::CategoricalIndex idx(arr, "fruits");

    bool passed = (idx.size() == 4 && !idx.empty() &&
                   idx.name().has_value() && *idx.name() == "fruits" &&
                   idx.dtype_name() == "category");
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_extension_index_array_constructor() : array constructor check failed" << std::endl;
        throw std::runtime_error("pd_test_extension_index_array_constructor failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_copy_constructor() {
    std::cout << "========= copy constructor =========================";

empty (pd_test_1_all.cpp:941)

#include "../pandas/pd_config.h"

namespace dataframe_tests {

namespace dataframe_tests_config {

    void pd_test_config_version() {
        std::cout << "========= df_config: version info ======================= ";
        const char* version = pandas::DataFrameInfo::version();
        if (version == nullptr || std::string(version).empty()) {
            std::cout << "[FAIL] : in pd_test_config_version() : version is null or empty" << std::endl;
            throw std::runtime_error("pd_test_config_version failed: version is null or empty");
        }
        std::cout << "-> tests passed" << std::endl;
    }

    void pd_test_config_na_repr() {
        std::cout << "========= df_config: NA representation ======================= ";
        const char* na_repr = pandas::DataFrameConfig::get_na_repr();
        if (na_repr == nullptr) {

has_cached_values (pd_test_1_all.cpp:19395)

            }

            std::cout << " -> tests passed" << std::endl;
        }

        void pd_test_series_cache() {
            std::cout << "========= cache management =========================================";

            pandas::Series<double> s({1.0, 2.0, 3.0, 4.0, 5.0});

            bool passed = s.has_cached_values() == false;
            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_series_cache() : initial cache not empty" << std::endl;
                throw std::runtime_error("pd_test_series_cache failed: initial cache not empty");
            }

            // Trigger cache
            s.sum();
            s.mean();
            s.min();
            s.max();

has_duplicates (pd_test_1_all.cpp:10176)

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_extension_index_uniqueness() {
    std::cout << "========= uniqueness =========================";

    // Unique values
    pandas::CategoricalArray arr1({"a", "b", "c"});
    pandas::CategoricalIndex idx1(arr1);

    bool passed1 = (idx1.is_unique() && !idx1.has_duplicates());
    if (!passed1) {
        std::cout << "  [FAIL] : in pd_test_extension_index_uniqueness() : unique check failed" << std::endl;
        throw std::runtime_error("pd_test_extension_index_uniqueness failed");
    }

    // With duplicates
    pandas::CategoricalArray arr2({"a", "b", "a", "c"});
    pandas::CategoricalIndex idx2(arr2);

    bool passed2 = (!idx2.is_unique() && idx2.has_duplicates());

inferred_type (pd_test_1_all.cpp:5270)

}

void pd_test_categorical_index_array_constructor() {
    std::cout << "========= array constructor ===========================";

    pandas::CategoricalArray arr({"apple", "banana", "apple", "cherry"});
    pandas::CategoricalIndex idx(arr, "fruits");

    bool passed = (idx.size() == 4 && !idx.empty() &&
                   idx.name().has_value() && *idx.name() == "fruits" &&
                   idx.inferred_type() == "categorical");
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_array_constructor()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_array_constructor failed");
    }

    std::cout << " -> tests passed" << std::endl;
}

void pd_test_categorical_index_values_constructor() {
    std::cout << "========= values constructor ==========================";

name (pd_test_1_all.cpp:295)

            throw std::runtime_error("pd_test_boolean_array_reductions failed: mean");
        }

        std::cout << " -> tests passed" << std::endl;
    }

    void pd_test_boolean_array_dtype() {
        std::cout << "========= BooleanArray: dtype ======================= ";

        pandas::BooleanArray arr;
        if (arr.dtype().name() != "boolean") {
            std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype name should be 'boolean'" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype name");
        }

        if (arr.dtype().kind() != "b") {
            std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype kind should be 'b'" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype kind");
        }

        std::cout << " -> tests passed" << std::endl;

nbytes (pd_test_1_all.cpp:6214)

            }

            // Test empty DataFrame
            pandas::DataFrame empty_df;
            if (!empty_df.empty()) {
                std::cout << "  [FAIL] : in pd_test_dataframe_properties() : should be empty" << std::endl;
                throw std::runtime_error("pd_test_dataframe_properties failed: should be empty");
            }

            // Test nbytes > 0 for non-empty
            if (df.nbytes() == 0) {
                std::cout << "  [FAIL] : in pd_test_dataframe_properties() : nbytes should be > 0" << std::endl;
                throw std::runtime_error("pd_test_dataframe_properties failed: nbytes should be > 0");
            }

            // Test columns index
            if (df.columns().size() != 3) {
                std::cout << "  [FAIL] : in pd_test_dataframe_properties() : columns size != 3" << std::endl;
                throw std::runtime_error("pd_test_dataframe_properties failed: columns size != 3");
            }

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

set_name (pd_test_1_all.cpp:11798)

                throw std::runtime_error("pd_test_index_vector_constructor failed");
            }

            std::cout << " -> tests passed" << std::endl;
        }

        void pd_test_index_copy_constructor() {
            std::cout << "========= copy constructor ============================";

            pandas::Index<numpy::int64> idx1{1, 2, 3};
            idx1.set_name("original");

            pandas::Index<numpy::int64> idx2(idx1);

            bool passed = (idx2.size() == 3);
            passed = passed && (idx2.name().value() == "original");
            passed = passed && idx2.equals(idx1);

            if (!passed) {
                std::cout << "  [FAIL] : in pd_test_index_copy_constructor() : copy failed" << std::endl;
                throw std::runtime_error("pd_test_index_copy_constructor failed");

size (pd_test_1_all.cpp:22)

#include "../pandas/pd_boolean_array.h"

namespace dataframe_tests {

namespace dataframe_tests_boolean_array {
    void pd_test_boolean_array_constructors() {
        std::cout << "========= BooleanArray: constructors ======================= ";

        // Default constructor
        pandas::BooleanArray arr1;
        if (arr1.size() != 0) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : default constructor size != 0" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: default constructor size != 0");
        }

        // Initializer list constructor
        pandas::BooleanArray arr2({
            std::optional<bool>(true),
            std::optional<bool>(false),
            std::nullopt,
            std::optional<bool>(true)

type_id (pd_test_3_all.cpp:25592)

// ------------------- pd_test_value_classify (end) ------------------

// ------------------- pd_test_index_type_id (start) ------------------
namespace dataframe_tests_index_type_id {

void pd_test_index_type_id_dispatch() {
    std::cout << "========= IndexTypeId dispatch =======================";

    // RangeIndex
    ::pandas::RangeIndex ri(0, 5);
    if (ri.type_id() != ::pandas::IndexTypeId::RangeIndex)
        throw std::runtime_error("RangeIndex type_id failed");

    // Index<string>
    ::pandas::Index<std::string> si(std::vector<std::string>{"a", "b", "c"});
    if (si.type_id() != ::pandas::IndexTypeId::IndexString)
        throw std::runtime_error("Index<string> type_id failed");

    // Index<int64>
    ::pandas::Index<numpy::int64> ii(std::vector<numpy::int64>{1, 2, 3});
    if (ii.type_id() != ::pandas::IndexTypeId::IndexInt64)