CategoricalDtype

class pandas::CategoricalDtype

Data type class for pandas extension types.

Example

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

// Use CategoricalDtype
CategoricalDtype obj;
// ... operations ...

Constructors

Signature	Location	Example
CategoricalDtype(const std::vector<std::string>& categories, bool ordered = false, const std::string& categories_dtype = "object")	pd_categorical_dtype.h:47

Indexing / Selection

Signature	Return Type	Location	Example
const std::string& get_category(int32_t code) const	const std::string&	pd_categorical_dtype.h:179
int32_t get_category_code(const std::string& value) const	int32_t	pd_categorical_dtype.h:165

Iteration

Signature	Return Type	Location	Example
size_t itemsize() const override	size_t	pd_categorical_dtype.h:75

Other Methods

Signature	Return Type	Location	Example
const std::vector<std::string>& categories() const	const std::vector<std::string>&	pd_categorical_dtype.h:118	View
const std::string& categories_dtype_str() const	const std::string&	pd_categorical_dtype.h:133
bool has_category(const std::string& value) const	bool	pd_categorical_dtype.h:156	View
std::string kind() const override	std::string	pd_categorical_dtype.h:83	View
std::string name() const override	std::string	pd_categorical_dtype.h:61	View
size_t num_categories() const	size_t	pd_categorical_dtype.h:147	View
numpy::DType numpy_dtype() const override	numpy::DType	pd_categorical_dtype.h:68
bool ordered() const	bool	pd_categorical_dtype.h:126	View
std::string repr() const override	std::string	pd_categorical_dtype.h:98	View
void set_categories_dtype(const std::string& dtype)	void	pd_categorical_dtype.h:140
const std::type_info& type() const override	const std::type_info&	pd_categorical_dtype.h:90	View
CategoricalDtype with_categories(const std::vector<std::string>& new_categories) const	CategoricalDtype	pd_categorical_dtype.h:244
CategoricalDtype with_ordered(bool ordered) const	CategoricalDtype	pd_categorical_dtype.h:237

Code Examples

The following examples are extracted from the test suite.

categories (pd_test_1_all.cpp:389)

        std::vector<std::optional<std::string>> vals = {
            std::optional<std::string>("low"),
            std::optional<std::string>("high"),
            std::optional<std::string>("medium")
        };
        pandas::CategoricalArray arr3(vals, cats, true);  // ordered
        if (!arr3.ordered()) {
            std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : should be ordered" << std::endl;
            throw std::runtime_error("pd_test_categorical_array_constructors failed: should be ordered");
        }
        if (arr3.categories().size() != 3) {
            std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : categories size != 3" << std::endl;
            throw std::runtime_error("pd_test_categorical_array_constructors failed: categories size != 3");
        }

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

    void pd_test_categorical_array_from_codes() {
        std::cout << "========= CategoricalArray: from_codes ======================= ";

has_category (pd_test_1_all.cpp:5303)

}

void pd_test_categorical_index_values_with_categories_constructor() {
    std::cout << "========= values with categories constructor ==========";

    std::vector<std::optional<std::string>> values = {"a", "b", "a"};
    std::vector<std::string> categories = {"a", "b", "c", "d"};
    pandas::CategoricalIndex idx(values, categories, true, "explicit_cats");

    bool passed = (idx.size() == 3 && idx.num_categories() == 4 &&
                   idx.ordered() && idx.has_category("c") && idx.has_category("d"));
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_values_with_categories_constructor()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_values_with_categories_constructor failed");
    }

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

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

kind (pd_test_1_all.cpp:300)

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

int pd_test_boolean_array_main() {
    std::cout << "====================================== running pd_test_boolean_array ==================================== " << std::endl;

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;

num_categories (pd_test_1_all.cpp:5285)

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

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

    std::vector<std::optional<std::string>> values = {"a", "b", "a", std::nullopt, "c"};
    pandas::CategoricalIndex idx(values, std::optional<std::string>("letters"), false);

    bool passed = (idx.size() == 5 && idx.num_categories() == 3 &&
                   !idx.ordered() && idx.name().has_value() && *idx.name() == "letters");
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_categorical_index_values_constructor()" << std::endl;
        throw std::runtime_error("pd_test_categorical_index_values_constructor failed");
    }

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

void pd_test_categorical_index_values_with_categories_constructor() {

ordered (pd_test_1_all.cpp:359)

    void pd_test_categorical_array_constructors() {
        std::cout << "========= CategoricalArray: constructors ======================= ";

        // Default constructor
        pandas::CategoricalArray arr1;
        if (arr1.size() != 0) {
            std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default constructor size != 0" << std::endl;
            throw std::runtime_error("pd_test_categorical_array_constructors failed: default constructor size != 0");
        }
        if (arr1.ordered()) {
            std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default should be unordered" << std::endl;
            throw std::runtime_error("pd_test_categorical_array_constructors failed: default should be unordered");
        }

        // Constructor from values (infer categories)
        std::vector<std::optional<std::string>> values = {
            std::optional<std::string>("a"),
            std::optional<std::string>("b"),
            std::optional<std::string>("a"),
            std::optional<std::string>("c")

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

type (pd_test_3_all.cpp:15450)

/**
 * Test Series.convert_dtypes() parameter flags
 */
void pd_test_series_convert_dtypes_flags() {
    std::cout << "========= Series.convert_dtypes() flags =================";

    // Test convert_integer=false - with floats disabled too, so it becomes string/object
    pandas::Series<std::string> s({"1", "2", "3"}, "numbers");
    auto converted = s.convert_dtypes(true, true, false, true, false);  // convert_integer=false, convert_floating=false

    // Should remain object type (Series<std::string> has dtype_name()="object")
    // When integer and floating are both disabled for integer-like strings, it falls back to string type
    if (converted->dtype_name() != "object") {
        std::cout << "  [FAIL] : dtype should be object when convert_integer=false and convert_floating=false, got " << converted->dtype_name() << std::endl;
        throw std::runtime_error("pd_test_series_convert_dtypes_flags failed: convert_integer");
    }

    // Test convert_boolean=false - strings stay as object/string type
    pandas::Series<std::string> s_bool({"true", "false"}, "bools");
    auto converted_bool = s_bool.convert_dtypes(true, true, true, false, true);  // convert_boolean=false