Period

class pandas::Period

Scalar type representing a single value.

Example

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

// Use Period
Period obj;
// ... operations ...

Constructors

Signature	Location	Example
Period(int64_t ordinal, const std::string& freq)	pd_period.h:74
Period(const std::string& value, const std::string& freq)	pd_period.h:92

Statistics

Signature	Return Type	Location	Example
int minute() const	int	pd_period.h:227	View

Arithmetic

Signature	Return Type	Location	Example
Period add_ordinals(int64_t n) const	Period	pd_period.h:480

Time Series

Signature	Return Type	Location	Example
Period asfreq(const std::string& freq, const std::string& how = "E") const	Period	pd_period.h:317	View
pandas::Timestamp to_timestamp(const std::string& freq = "", const std::string& how = "start") const	pandas::Timestamp	pd_period.h:381	View

Iteration

Signature	Return Type	Location	Example
pandas::Timestamp end_time() const	pandas::Timestamp	pd_period.h:407	View

Type Checking

Signature	Return Type	Location	Example
bool is_leap_year() const	bool	pd_period.h:302	View

Other Methods

Signature	Return Type	Location	Example
static Period NaT(const std::string& freq = "D")	static Period	pd_period.h:160	View
int day() const	int	pd_period.h:211	View
int day_of_week() const { return dayofweek()	int	pd_period.h:256	View
int day_of_year() const { return dayofyear()	int	pd_period.h:266	View
int dayofweek() const	int	pd_period.h:251	View
int dayofyear() const	int	pd_period.h:261	View
int days_in_month() const	int	pd_period.h:290	View
days_since_epoch_to_date(days, y, m, d)		pd_period.h:352
PeriodFrequency freq() const	PeriodFrequency	pd_period.h:181	View
int64_t freq_multiplier() const	int64_t	pd_period.h:489
static int64_t freq_to_nanos(PeriodFrequency freq)	static int64_t	pd_period.h:466
std::string freqstr() const	std::string	pd_period.h:176	View
int hour() const	int	pd_period.h:219	View
bool isNaT() const	bool	pd_period.h:186	View
int month() const	int	pd_period.h:203	View
static Period now(const std::string& freq = "D", const std::string& tz = "")	static Period	pd_period.h:129	View
int64_t ordinal() const	int64_t	pd_period.h:171	View
int quarter() const	int	pd_period.h:243	View
int qyear() const	int	pd_period.h:281	View
std::string repr() const	std::string	pd_period.h:450	View
int second() const	int	pd_period.h:235	View
pandas::Timestamp start_time() const	pandas::Timestamp	pd_period.h:400	View
std::string strftime(const std::string& date_format) const	std::string	pd_period.h:428	View
std::string toString() const	std::string	pd_period.h:418	View
int week() const	int	pd_period.h:271	View
int weekofyear() const { return week()	int	pd_period.h:276
int year() const	int	pd_period.h:195	View

Code Examples

The following examples are extracted from the test suite.

minute (pd_test_1_all.cpp:7505)

    std::cout << "========= minute property =============================";

    std::vector<std::optional<numpy::datetime64>> values = {
        make_dt(0),                    // Minute 0
        make_dt(30 * NS_PER_MIN),      // Minute 30
        make_dt(59 * NS_PER_MIN)       // Minute 59
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeIndex idx(arr);

    auto minutes = idx.minute();

    bool passed = (minutes.size() == 3);
    auto m0 = minutes[0];
    auto m1 = minutes[1];
    auto m2 = minutes[2];
    passed = passed && m0.has_value() && *m0 == 0;
    passed = passed && m1.has_value() && *m1 == 30;
    passed = passed && m2.has_value() && *m2 == 59;

    if (!passed) {

asfreq (pd_test_1_all.cpp:2869)

        std::cout << "========= PeriodArray: asfreq ======================= ";

        // Monthly to quarterly
        pandas::PeriodArray arr_m(std::vector<std::string>{
            "2024-01",
            "2024-04",
            "2024-07",
            "NaT"
        }, "M");

        auto arr_q = arr_m.asfreq("Q");
        if (arr_q.size() != 4) {
            std::cout << "  [FAIL] : asfreq size should be 4" << std::endl;
            throw std::runtime_error("pd_test_period_array_asfreq failed: size");
        }
        if (arr_q.freqstr() != "Q") {
            std::cout << "  [FAIL] : asfreq freqstr should be 'Q'" << std::endl;
            throw std::runtime_error("pd_test_period_array_asfreq failed: freqstr");
        }

        // Check NaT is preserved

to_timestamp (pd_test_1_all.cpp:2830)

    void pd_test_period_array_to_timestamp() {
        std::cout << "========= PeriodArray: to_timestamp ======================= ";

        pandas::PeriodArray arr(std::vector<std::string>{
            "2024-01",
            "2024-06",
            "NaT"
        }, "M");

        // to_timestamp with start
        auto ts_start = arr.to_timestamp("start");
        if (ts_start.size() != 3) {
            std::cout << "  [FAIL] : to_timestamp size should be 3" << std::endl;
            throw std::runtime_error("pd_test_period_array_to_timestamp failed: size");
        }

        auto ts0 = ts_start[0];
        if (!ts0.has_value()) {
            std::cout << "  [FAIL] : ts_start[0] should have value" << std::endl;
            throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[0]");
        }

end_time (pd_test_1_all.cpp:17146)

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

void pd_test_period_index_end_time() {
    std::cout << "========= end_time property ===========================";

    std::vector<int64_t> ordinals = {0};  // 1970-01-01 daily period
    pandas::PeriodIndex idx = pandas::PeriodIndex::from_ordinals(ordinals, "D");

    pandas::DatetimeArray end_times = idx.end_time();

    bool passed = (end_times.size() == 1 && !end_times.is_na(0));
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_period_index_end_time()" << std::endl;
        throw std::runtime_error("pd_test_period_index_end_time failed");
    }

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

is_leap_year (pd_test_1_all.cpp:1280)

        }

        // is_month_end
        auto me = arr.is_month_end();
        if (!me[1].has_value() || !me[1].value()) {
            std::cout << "  [FAIL] : 2023-03-31 should be month end" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month end");
        }

        // is_leap_year
        auto ly = arr.is_leap_year();
        if (!ly[2].has_value() || !ly[2].value()) {
            std::cout << "  [FAIL] : 2024 should be leap year" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_boolean_props failed: leap year");
        }
        if (!ly[0].has_value() || ly[0].value()) {
            std::cout << "  [FAIL] : 2023 should not be leap year" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_boolean_props failed: not leap year");
        }

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

NaT (pd_test_1_all.cpp:1305)

        pandas::DatetimeArray arr(std::vector<std::string>{
            "2023-06-15",
            "NaT",
            "2023-01-01",
            "2023-12-31"
        });

        // argsort ascending
        auto indices = arr.argsort(true, "last");
        // Expected order: 2023-01-01(2), 2023-06-15(0), 2023-12-31(3), NaT(1)
        if (indices.getElementAt({0}) != 2) {
            std::cout << "  [FAIL] : argsort: first should be index 2 (2023-01-01)" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_sorting failed: argsort first");
        }
        if (indices.getElementAt({3}) != 1) {
            std::cout << "  [FAIL] : argsort: last should be index 1 (NaT)" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_sorting failed: NaT position");
        }

        // argmin

day (pd_test_1_all.cpp:1193)

            std::cout << "  [FAIL] : month[0] should be 3" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[0]");
        }
        auto m1 = months[1];
        if (!m1.has_value() || m1.value() != 12) {
            std::cout << "  [FAIL] : month[1] should be 12" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[1]");
        }

        // Day
        auto days = arr.day();
        auto d0 = days[0];
        if (!d0.has_value() || d0.value() != 15) {
            std::cout << "  [FAIL] : day[0] should be 15" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: day[0]");
        }
        auto d1 = days[1];
        if (!d1.has_value() || d1.value() != 25) {
            std::cout << "  [FAIL] : day[1] should be 25" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: day[1]");
        }

day_of_week (pd_test_3_all.cpp:22018)

void test_dt_aliases() {
    std::cout << "========= dt accessor aliases ====================";

    std::vector<numpy::datetime64> dates = {
        numpy::datetime64("2023-01-15"),
        numpy::datetime64("2023-06-20")
    };
    pandas::Series<numpy::datetime64> s(dates);

    auto dow1 = s.dt().dayofweek();
    auto dow2 = s.dt().day_of_week();
    auto dow3 = s.dt().weekday();

    if (dow1[0] != dow2[0] || dow1[0] != dow3[0]) {
        throw std::runtime_error("dt aliases: dayofweek/day_of_week/weekday mismatch");
    }

    auto doy1 = s.dt().dayofyear();
    auto doy2 = s.dt().day_of_year();

    if (doy1[0] != doy2[0]) {

day_of_year (pd_test_3_all.cpp:22026)

    auto dow1 = s.dt().dayofweek();
    auto dow2 = s.dt().day_of_week();
    auto dow3 = s.dt().weekday();

    if (dow1[0] != dow2[0] || dow1[0] != dow3[0]) {
        throw std::runtime_error("dt aliases: dayofweek/day_of_week/weekday mismatch");
    }

    auto doy1 = s.dt().dayofyear();
    auto doy2 = s.dt().day_of_year();

    if (doy1[0] != doy2[0]) {
        throw std::runtime_error("dt aliases: dayofyear/day_of_year mismatch");
    }

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

void test_dt_days_in_month() {
    std::cout << "========= dt.days_in_month ======================";

dayofweek (pd_test_1_all.cpp:7565)

    // 1970-01-01 was a Thursday (day 3)
    std::vector<std::optional<numpy::datetime64>> values = {
        make_dt(0),                // Thursday (3)
        make_dt(NS_PER_DAY),       // Friday (4)
        make_dt(2 * NS_PER_DAY),   // Saturday (5)
        make_dt(3 * NS_PER_DAY)    // Sunday (6)
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeIndex idx(arr);

    auto dow = idx.dayofweek();

    bool passed = (dow.size() == 4);
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_datetime_index_dayofweek()" << std::endl;
        throw std::runtime_error("pd_test_datetime_index_dayofweek failed");
    }

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

dayofyear (pd_test_3_all.cpp:18582)

    auto seconds = s.dt().second();
    if (seconds[0] != 45 || seconds[1] != 30 || seconds[2] != 59) {
        std::cout << "  [FAIL] : second() failed" << std::endl;
        throw std::runtime_error("pd_test_dt_time_components: second() failed");
    }

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

// ============================================================================
// Test dt().dayofweek(), dt().dayofyear(), dt().quarter()
// ============================================================================

void pd_test_dt_derived_properties() {
    std::cout << "========= Series.dt().dayofweek/dayofyear/quarter() ======";

    // 2020-01-01 is a Wednesday (dayofweek=2), dayofyear=1, Q1
    // 2020-07-04 is a Saturday (dayofweek=5), dayofyear=186, Q3
    pandas::Series<std::string> s({"2020-01-01", "2020-07-04"});

    auto dow = s.dt().dayofweek();

days_in_month (pd_test_1_all.cpp:2766)

            std::cout << "  [FAIL] : day[0] should be 15" << std::endl;
            throw std::runtime_error("pd_test_period_array_day_components failed: day[0]");
        }
        auto d1 = days[1];
        if (!d1.has_value() || d1.value() != 25) {
            std::cout << "  [FAIL] : day[1] should be 25" << std::endl;
            throw std::runtime_error("pd_test_period_array_day_components failed: day[1]");
        }

        // Days in month
        auto dim = arr.days_in_month();
        auto dim0 = dim[0];
        if (!dim0.has_value() || dim0.value() != 31) {
            std::cout << "  [FAIL] : days_in_month[0] should be 31 (March)" << std::endl;
            throw std::runtime_error("pd_test_period_array_day_components failed: days_in_month[0]");
        }
        auto dim1 = dim[1];
        if (!dim1.has_value() || dim1.value() != 31) {
            std::cout << "  [FAIL] : days_in_month[1] should be 31 (December)" << std::endl;
            throw std::runtime_error("pd_test_period_array_day_components failed: days_in_month[1]");
        }

freq (pd_test_1_all.cpp:8233)

    std::cout << "========= freq property ===============================";

    std::vector<std::optional<numpy::datetime64>> values = {
        numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond),
        numpy::datetime64(86400000000000LL, numpy::DateTimeUnit::Nanosecond)  // 1 day
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeMixinIndex idx(arr);

    // Default freq is nullopt or inferred
    auto f = idx.freq();
    std::string fs = idx.freqstr();

    bool passed = true;  // freq may or may not be set
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_datetime_mixin_freq()" << std::endl;
        throw std::runtime_error("pd_test_datetime_mixin_freq failed");
    }

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

freqstr (pd_test_1_all.cpp:2671)

        }

        pandas::PeriodDtype dtype_y("Y");
        if (dtype_y.name() != "period[Y]") {
            std::cout << "  [FAIL] : dtype_y.name() should be 'period[Y]'" << std::endl;
            throw std::runtime_error("pd_test_period_array_freq_validation failed: dtype name Y");
        }

        // Test frequency string
        pandas::PeriodArray arr(std::vector<std::string>{"2024-01-15"}, "D");
        if (arr.freqstr() != "D") {
            std::cout << "  [FAIL] : arr.freqstr() should be 'D'" << std::endl;
            throw std::runtime_error("pd_test_period_array_freq_validation failed: freqstr");
        }

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

    void pd_test_period_array_year_month_quarter() {
        std::cout << "========= PeriodArray: year/month/quarter components ======================= ";

hour (pd_test_1_all.cpp:7476)

    std::cout << "========= hour property ===============================";

    std::vector<std::optional<numpy::datetime64>> values = {
        make_dt(0),                    // Hour 0
        make_dt(6 * NS_PER_HOUR),      // Hour 6
        make_dt(23 * NS_PER_HOUR)      // Hour 23
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeIndex idx(arr);

    auto hours = idx.hour();

    bool passed = (hours.size() == 3);
    auto h0 = hours[0];
    auto h1 = hours[1];
    auto h2 = hours[2];
    passed = passed && h0.has_value() && *h0 == 0;
    passed = passed && h1.has_value() && *h1 == 6;
    passed = passed && h2.has_value() && *h2 == 23;

    if (!passed) {

isNaT (pd_test_3_all.cpp:1523)

    }

    // Case B: pandas::Timedelta == pandas::Timedelta
    {
        static_assert(std::is_same_v<pandas::Timedelta, pandas::Timedelta>,
                      "pandas::Timedelta must alias pandas::Timedelta");
    }

    // Case C: pandas::NaT is a NaT-valued Timestamp
    {
        if (!pandas::NaT.isNaT()) {
            throw std::runtime_error("pandas::NaT is not a NaT value");
        }
        pandas::Timestamp default_ts;
        if (default_ts.isNaT() != pandas::NaT.isNaT()) {
            throw std::runtime_error(
                "pandas::NaT and default Timestamp NaT-state mismatch");
        }
    }

    // Case D: round-trip - reproduces the failing test pattern

month (pd_test_1_all.cpp:1180)

    void pd_test_datetime_array_component_month_day() {
        std::cout << "========= DatetimeArray: month/day components ======================= ";

        pandas::DatetimeArray arr(std::vector<std::string>{
            "2023-03-15",
            "2023-12-25",
            "NaT"
        });

        // Month
        auto months = arr.month();
        auto m0 = months[0];
        if (!m0.has_value() || m0.value() != 3) {
            std::cout << "  [FAIL] : month[0] should be 3" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[0]");
        }
        auto m1 = months[1];
        if (!m1.has_value() || m1.value() != 12) {
            std::cout << "  [FAIL] : month[1] should be 12" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[1]");
        }

now (pd_test_3_all.cpp:20077)

    bool passed = months_default[0] == "June" && days_default[0] == "Monday";
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_name_locale_params()" << std::endl;
        throw std::runtime_error("pd_test_name_locale_params failed");
    }

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

// ============================================================================
// Test Period.now() with tz parameter
// ============================================================================

void pd_test_period_now_tz() {
    std::cout << "========= Period.now(tz) ================================";

    // Test now() with default (local time)
    auto p_local = pandas::Period::now("D");

    // Test now() with UTC timezone
    auto p_utc = pandas::Period::now("D", "UTC");

ordinal (pd_test_5_all.cpp:41796)

    std::cout << "----- case_11_period_nat_sentinel_api_self_check -----\n";
    pandas::Period nat1 = pandas::Period::NaT("D");
    pandas::Period nat2;  // default ctor = NaT
    pandas::Period real(123, std::string("D"));

    pandas_tests::check(nat1.isNaT(), "case11.NaT_factory_isNaT", local_fail);
    pandas_tests::check(nat2.isNaT(),
                        "case11.default_ctor_isNaT", local_fail);
    pandas_tests::check(!real.isNaT(),
                        "case11.real_period_is_NOT_NaT", local_fail);
    pandas_tests::check(nat1.ordinal() == pandas::PERIOD_NAT,
                        "case11.NaT_ordinal_equals_PERIOD_NAT_sentinel", local_fail);
    pandas_tests::check(real.ordinal() == 123,
                        "case11.real_period_ordinal_value", local_fail);

    std::cout << "  NaT.ordinal=" << nat1.ordinal()
              << " PERIOD_NAT=" << pandas::PERIOD_NAT
              << " real.ordinal=" << real.ordinal() << "\n";
}

void case_12_period_oracle_parity_subset(int& local_fail) {

quarter (pd_test_1_all.cpp:1218)

    void pd_test_datetime_array_quarter() {
        std::cout << "========= DatetimeArray: quarter ======================= ";

        pandas::DatetimeArray arr(std::vector<std::string>{
            "2023-01-15",  // Q1
            "2023-05-20",  // Q2
            "2023-09-10",  // Q3
            "2023-11-25"   // Q4
        });

        auto quarters = arr.quarter();

        auto q0 = quarters[0];
        if (!q0.has_value() || q0.value() != 1) {
            std::cout << "  [FAIL] : quarter[0] should be 1" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_quarter failed: quarter[0]");
        }
        auto q1 = quarters[1];
        if (!q1.has_value() || q1.value() != 2) {
            std::cout << "  [FAIL] : quarter[1] should be 2" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_quarter failed: quarter[1]");

qyear (pd_test_1_all.cpp:17092)

// ============================================================================

void pd_test_period_index_qyear() {
    std::cout << "========= qyear property ==============================";

    // Monthly periods in Q1 2020
    std::vector<int> years = {2020, 2020, 2020};
    std::vector<int> months = {1, 2, 3};
    pandas::PeriodIndex idx = pandas::PeriodIndex::from_fields(years, months, {}, {}, {}, {}, "M");

    pandas::IntegerArray<numpy::int32> qyears = idx.qyear();

    bool passed = (qyears.size() == 3 &&
                   qyears[0].has_value() && *qyears[0] == 2020 &&
                   qyears[1].has_value() && *qyears[1] == 2020 &&
                   qyears[2].has_value() && *qyears[2] == 2020);
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_period_index_qyear()" << std::endl;
        throw std::runtime_error("pd_test_period_index_qyear failed");
    }

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

second (pd_test_1_all.cpp:7534)

    std::cout << "========= second property =============================";

    std::vector<std::optional<numpy::datetime64>> values = {
        make_dt(0),                    // Second 0
        make_dt(30 * NS_PER_SEC),      // Second 30
        make_dt(59 * NS_PER_SEC)       // Second 59
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeIndex idx(arr);

    auto seconds = idx.second();

    bool passed = (seconds.size() == 3);
    auto s0 = seconds[0];
    auto s1 = seconds[1];
    auto s2 = seconds[2];
    passed = passed && s0.has_value() && *s0 == 0;
    passed = passed && s1.has_value() && *s1 == 30;
    passed = passed && s2.has_value() && *s2 == 59;

    if (!passed) {

start_time (pd_test_1_all.cpp:2848)

            std::cout << "  [FAIL] : ts_start[0] should have value" << std::endl;
            throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[0]");
        }

        auto ts2 = ts_start[2];
        if (ts2.has_value()) {
            std::cout << "  [FAIL] : ts_start[2] should be NaT" << std::endl;
            throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[2]");
        }

        // start_time() alias
        auto start_times = arr.start_time();
        if (start_times.size() != 3) {
            std::cout << "  [FAIL] : start_time size should be 3" << std::endl;
            throw std::runtime_error("pd_test_period_array_to_timestamp failed: start_time size");
        }

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

    void pd_test_period_array_asfreq() {

strftime (pd_test_1_all.cpp:8434)

void pd_test_datetime_mixin_strftime() {
    std::cout << "========= strftime ====================================";

    std::vector<std::optional<numpy::datetime64>> values = {
        numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond),  // 1970-01-01
        numpy::datetime64(86400000000000LL, numpy::DateTimeUnit::Nanosecond)  // 1970-01-02
    };
    pandas::DatetimeArray arr(values);
    pandas::DatetimeMixinIndex idx(arr);

    std::vector<std::string> formatted = idx.strftime("%Y-%m-%d");

    bool passed = (formatted.size() == 2 && !formatted[0].empty() && !formatted[1].empty());
    if (!passed) {
        std::cout << "  [FAIL] : in pd_test_datetime_mixin_strftime()" << std::endl;
        throw std::runtime_error("pd_test_datetime_mixin_strftime failed");
    }

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

toString (pd_test_1_all.cpp:9539)

void pd_test_timedelta_rounding_params() {
    std::cout << "========= Timedelta rounding with DST params =====";

    // Create a Timedelta: 1h 30m 45s
    // Constructor is: (days, hours, minutes, seconds, ...)
    pandas::Timedelta td(0, 1, 30, 45);  // 0 days, 1h, 30m, 45s

    // Test floor with ambiguous/nonexistent params
    pandas::Timedelta floored = td.floor("h", "raise", "raise");
    std::cout << std::endl << "  floor('h'): " << floored.toString();

    // Test ceil with ambiguous/nonexistent params
    pandas::Timedelta ceiled = td.ceil("h", "raise", "raise");
    std::cout << std::endl << "  ceil('h'): " << ceiled.toString();

    // Test round with ambiguous/nonexistent params
    pandas::Timedelta rounded = td.round("h", "raise", "raise");
    std::cout << std::endl << "  round('h'): " << rounded.toString();

    // Verify results:

week (pd_test_timestamp_scalar.cpp:406)

      // 2024-06-15 is a Saturday
      pandas::Timestamp ts(2024, 6, 15);

      if (ts.dayofweek() != 5) { pass = false; fail_msg = "2024-06-15 should be Saturday (5)"; }
      if (ts.day_of_week() != 5) { pass = false; fail_msg = "day_of_week alias"; }
      if (ts.dayofyear() != 167) { pass = false; fail_msg = "2024-06-15 should be day 167"; }
      if (ts.day_of_year() != 167) { pass = false; fail_msg = "day_of_year alias"; }
      if (ts.quarter() != 2) { pass = false; fail_msg = "June is Q2"; }
      if (ts.days_in_month() != 30) { pass = false; fail_msg = "June has 30 days"; }

      int week = ts.week();
      if (week < 1 || week > 53) { pass = false; fail_msg = "week should be 1-53"; }

      if (!pass) {
        std::cout << "  [FAIL] : in np_test_timestamp_derived() : " << fail_msg;
        throw std::runtime_error("np_test_timestamp_derived failed: " + fail_msg);
      }

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

year (pd_test_1_all.cpp:1147)

    void pd_test_datetime_array_component_year() {
        std::cout << "========= DatetimeArray: year component ======================= ";

        pandas::DatetimeArray arr(std::vector<std::string>{
            "2020-01-15",
            "NaT",
            "2025-06-20"
        });

        auto years = arr.year();

        auto y0 = years[0];
        if (!y0.has_value() || y0.value() != 2020) {
            std::cout << "  [FAIL] : year[0] should be 2020" << std::endl;
            throw std::runtime_error("pd_test_datetime_array_component_year failed: year[0]");
        }

        auto y1 = years[1];
        if (y1.has_value()) {
            std::cout << "  [FAIL] : year[1] should be NA (NaT)" << std::endl;