NDArrayBackedExtensionIndex

class pandas::NDArrayBackedExtensionIndex

Index class for axis labels in pandas data structures.

Example

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

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

Constructors

Signature	Location	Example
explicit NDArrayBackedExtensionIndex(const ArrayType& array, const std::optional<std::string>& name = std::nullopt, bool copy = false)	pd_ndarray_backed_extension_index.h:141
explicit NDArrayBackedExtensionIndex(ArrayType&& array, const std::optional<std::string>& name = std::nullopt)	pd_ndarray_backed_extension_index.h:151
NDArrayBackedExtensionIndex(const NDArrayBackedExtensionIndex& other)	pd_ndarray_backed_extension_index.h:160
NDArrayBackedExtensionIndex(NDArrayBackedExtensionIndex&& other) noexcept	pd_ndarray_backed_extension_index.h:168

Indexing / Selection

Signature	Return Type	Location	Example
std::string get_value_str(size_t index) const override	std::string	pd_ndarray_backed_extension_index.h:705	View

Data Manipulation

Signature	Return Type	Location	Example
NDArrayBackedExtensionIndex rename(const std::optional<std::string>& new_name) const	NDArrayBackedExtensionIndex	pd_ndarray_backed_extension_index.h:757	View

I/O

Signature	Return Type	Location	Example
std::string to_string() const override	std::string	pd_ndarray_backed_extension_index.h:618	View

Conversion

Signature	Return Type	Location	Example
NDArrayBackedExtensionIndex copy() const	NDArrayBackedExtensionIndex	pd_ndarray_backed_extension_index.h:750	View

Type Checking

Signature	Return Type	Location	Example
bool is_all_dates() const	bool	pd_ndarray_backed_extension_index.h:489	View

Other Methods

Signature	Return Type	Location	Example
DatetimeArray arr(data, mask)	DatetimeArray	pd_ndarray_backed_extension_index.h:279	View
TimedeltaArray arr(data, mask)	TimedeltaArray	pd_ndarray_backed_extension_index.h:296	View
DatetimeArray arr(data, mask)	DatetimeArray	pd_ndarray_backed_extension_index.h:349	View
TimedeltaArray arr(data, mask)	TimedeltaArray	pd_ndarray_backed_extension_index.h:365	View
PeriodArray arr(data, mask, "D")	PeriodArray	pd_ndarray_backed_extension_index.h:379	View
PeriodArray arr(data, mask, freq)	PeriodArray	pd_ndarray_backed_extension_index.h:405	View
size_t cache_memory_usage() const override	size_t	pd_ndarray_backed_extension_index.h:957
void clear_cache() const override	void	pd_ndarray_backed_extension_index.h:938	View
std::unique_ptr<IndexBase> clone() const override	std::unique_ptr<IndexBase>	pd_ndarray_backed_extension_index.h:607	View
static std::string format_datetime(const numpy::datetime64& val)	static std::string	pd_ndarray_backed_extension_index.h:771
std::string format_period(numpy::int64 ordinal) const	std::string	pd_ndarray_backed_extension_index.h:920
static std::string format_timedelta(const numpy::timedelta64& val)	static std::string	pd_ndarray_backed_extension_index.h:846
std::string freq_string() const	std::string	pd_ndarray_backed_extension_index.h:566	View
bool has_cached_values() const override	bool	pd_ndarray_backed_extension_index.h:948	View
std::string inferred_type() const override	std::string	pd_ndarray_backed_extension_index.h:593	View
PeriodArray arr(data, mask, period_freq_to_string(current_arr.freq()))	PeriodArray arr(data, mask,	pd_ndarray_backed_extension_index.h:312
std::string repr() const override	std::string	pd_ndarray_backed_extension_index.h:698	View
std::string resolution() const	std::string	pd_ndarray_backed_extension_index.h:427	View
NDArrayBackedExtensionIndex result(\*this)	NDArrayBackedExtensionIndex	pd_ndarray_backed_extension_index.h:758	View
IndexTypeId type_id() const override	IndexTypeId	pd_ndarray_backed_extension_index.h:611	View
std::string unit() const	std::string	pd_ndarray_backed_extension_index.h:528	View
static std::string unit_to_string(numpy::DateTimeUnit unit)	static std::string	pd_ndarray_backed_extension_index.h:543

Internal Methods

6 internal methods (prefixed with underscore)

Code Examples

The following examples are extracted from the test suite.

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

rename (pd_test_1_all.cpp:5816)

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

void pd_test_categorical_index_rename() {
    std::cout << "========= rename ======================================";

    pandas::CategoricalArray arr({"x", "y"});
    pandas::CategoricalIndex idx(arr, "old_name");

    pandas::CategoricalIndex renamed = idx.rename("new_name");

    bool passed = (renamed.name().has_value() && *renamed.name() == "new_name" &&
                   renamed.size() == idx.size() && renamed.categories() == idx.categories());
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_rename()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_rename failed");
    }

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

copy (pd_test_1_all.cpp:5798)

// ============================================================================
// Copy/Rename Tests
// ============================================================================

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

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

    pandas::CategoricalIndex copied = idx.copy();

    bool passed = (copied.size() == idx.size() && copied.name() == idx.name() &&
                   copied.categories() == idx.categories() && copied.ordered() == idx.ordered());
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_copy()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_copy failed");
    }

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

is_all_dates (pd_test_1_all.cpp:15606)

    bool passed = (res == "day");
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_period_index_resolution() : resolution check failed, got: " << res << std::endl;
        throw std::runtime_error("pd_test_period_index_resolution failed");
    }

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

// ============================================================================
// is_all_dates() Tests
// ============================================================================

void pd_test_is_all_dates() {
    std::cout << "========= is_all_dates() =========================";

    // DatetimeIndex
    numpy::NDArray<numpy::datetime64> dt_data(std::vector<size_t>{1});
    dt_data.setElementAt({0}, numpy::datetime64(1000LL, numpy::DateTimeUnit::Nanosecond));
    numpy::NDArray<numpy::bool_> dt_mask(std::vector<size_t>{1});
    dt_mask.setElementAt({0}, numpy::bool_(false));

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

arr (pd_test_1_all.cpp:45)

            std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : initializer_list size != 4" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_constructors failed: initializer_list size != 4");
        }

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

    void pd_test_boolean_array_na_handling() {
        std::cout << "========= BooleanArray: NA handling ======================= ";

        pandas::BooleanArray arr({
            std::optional<bool>(true),
            std::nullopt,  // NA at index 1
            std::optional<bool>(false)
        });

        if (!arr.is_na(1)) {
            std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
            throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
        }

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

freq_string (pd_test_1_all.cpp:15733)

    bool passed = (isnan_mask.size() == 2);
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_period_index_isnan() : _isnan check failed" << std::endl;
        throw std::runtime_error("pd_test_period_index_isnan failed");
    }

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

// ============================================================================
// unit() and freq_string() Tests
// ============================================================================

void pd_test_unit_freq_string() {
    std::cout << "========= unit() / freq_string() =========================";

    // PeriodIndex with monthly frequency
    numpy::NDArray<numpy::int64> data(std::vector<size_t>{1});
    data.setElementAt({0}, numpy::int64(0));

    numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{1});

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();

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

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

resolution (pd_test_1_all.cpp:15536)

    }

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

// ============================================================================
// Resolution Tests
// ============================================================================

void pd_test_datetime_index_resolution() {
    std::cout << "========= DatetimeIndex resolution() =========================";

    numpy::NDArray<numpy::datetime64> data(std::vector<size_t>{1});
    data.setElementAt({0}, numpy::datetime64(1000LL, numpy::DateTimeUnit::Nanosecond));

    numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{1});
    mask.setElementAt({0}, numpy::bool_(false));

    pandas::DatetimeArray arr(data, mask);
    pandas::DatetimeIndexBase idx(arr);

result (pd_test_1_all.cpp:15406)

    data.setElementAt({0}, numpy::datetime64(100LL, numpy::DateTimeUnit::Nanosecond));
    data.setElementAt({1}, numpy::datetime64(200LL, numpy::DateTimeUnit::Nanosecond));

    numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{2});
    mask.setElementAt({0}, numpy::bool_(false));
    mask.setElementAt({1}, numpy::bool_(false));

    pandas::DatetimeArray arr(data, mask);
    pandas::DatetimeIndexBase idx(arr, "original");

    // Create join result (int64 values)
    numpy::NDArray<numpy::int64> join_result(std::vector<size_t>{3});
    join_result.setElementAt({0}, numpy::int64(500LL));
    join_result.setElementAt({1}, numpy::int64(600LL));
    join_result.setElementAt({2}, numpy::int64(700LL));

    auto new_idx = idx._from_join_target(join_result);

    bool passed = (new_idx.size() == 3 &&
                   new_idx.name().has_value() && *new_idx.name() == "original");
    if (!passed) {

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)

unit (pd_test_1_all.cpp:9284)

    data.setElementAt({0}, numpy::datetime64(1000LL, numpy::DateTimeUnit::Nanosecond));
    data.setElementAt({1}, numpy::datetime64(2000LL, numpy::DateTimeUnit::Nanosecond));

    numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{2});
    mask.setElementAt({0}, numpy::bool_(false));
    mask.setElementAt({1}, numpy::bool_(false));

    pandas::DatetimeArray arr(data, mask);
    pandas::DatetimeTDMixin idx(arr);

    std::string unit = idx.unit();

    bool passed = (unit == "ns");  // nanosecond
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_datetime_unit_property() : unit property check failed, got '" << unit << "'" << std::endl;
        throw std::runtime_error("pd_test_datetime_unit_property failed");
    }

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