Method week_of_year (on ParsiDateTime)

Calculates the week number of the year for this date-time’s date component.

Description

This method determines the week number for the date component of the ParsiDateTime instance within its corresponding Persian (Solar Hijri) year. It achieves this by delegating the calculation directly to the ParsiDate::week_of_year method (here), using only the date part (year, month, day) of the ParsiDateTime.

The time component (hour, minute, second) is completely ignored in this calculation.

How it Works

The process is straightforward due to delegation:

1. Extract Date Component: Retrieves or constructs the ParsiDate equivalent from the ParsiDateTime instance (self). This involves taking the year, month, and day, discarding the time information.
2. Delegate Calculation: Calls the week_of_year() method on the extracted ParsiDate instance.
3. Return Result: Returns the Result<u32, DateError> obtained directly from the ParsiDate::week_of_year() call.

Returns

Since this method delegates to ParsiDate::week_of_year, it returns the same potential results:

• Ok(u32): If the underlying ParsiDate::week_of_year calculation succeeds, returns the week number (typically an integer between 1 and 53).
• Err(DateError::InvalidDate): If the date component of the ParsiDateTime is invalid (this check is performed by the delegated ParsiDate::week_of_year method).
• Err(DateError::GregorianConversionError): If the underlying calculation of the first day's weekday (required for week number calculation) fails, likely due to Gregorian conversion issues (delegated error).
• Err(DateError::ArithmeticOverflow): If the underlying calculation of the ordinal day (required for week number calculation) results in an arithmetic overflow (delegated error).

Examples (Rust)

use parsidate::{ParsiDateTime, ParsiDate, DateError}; // Assuming these types exist

// Example 1: Farvardin 4th, 1403, 10:00 AM
// The date 1403-01-04 falls in week 2. The time is ignored.
let dt1 = ParsiDateTime::new(1403, 1, 4, 10, 0, 0).unwrap();
// This should yield the same result as ParsiDate::new(1403, 1, 4).week_of_year()
assert_eq!(dt1.week_of_year(), Ok(2));

// Example 2: Same date, different time - Result should be identical
let dt2 = ParsiDateTime::new(1403, 1, 4, 23, 59, 59).unwrap();
assert_eq!(dt2.week_of_year(), Ok(2)); // Still week 2

// Example 3: A date from the ParsiDate example (1403-05-02 is week 19)
let dt3 = ParsiDateTime::new(1403, 5, 2, 12, 30, 15).unwrap();
// Corresponds to ParsiDate::new(1403, 5, 2).week_of_year()
assert_eq!(dt3.week_of_year(), Ok(19));

// Example 4: End of year (1403-12-30 is week 53)
let dt_end_year = ParsiDateTime::new(1403, 12, 30, 0, 0, 0).unwrap();
// Corresponds to ParsiDate::new(1403, 12, 30).week_of_year()
assert_eq!(dt_end_year.week_of_year(), Ok(53));

// Example 5: Handling an invalid date component
// Using an invalid day for a non-leap year (e.g., 1402-12-30)
// Let's assume ParsiDateTime::new would catch this, or use unsafe if needed
// For demonstration, let's imagine an unsafe creation if `new` prevents it:
// let invalid_dt = unsafe { ParsiDateTime::new_unchecked(1402, 12, 30, 10, 0, 0) };
// For a safe example, let's assume `new` returns an error for invalid dates:
let result_invalid = ParsiDateTime::new(1402, 12, 30, 10, 0, 0); // 1402 is not leap
assert!(result_invalid.is_err());
// If we *could* create it and then call week_of_year:
// let invalid_dt = /* somehow create ParsiDateTime(1402, 12, 30, ...) */;
// let result = invalid_dt.week_of_year();
// assert!(result.is_err());
// // The error would likely be InvalidDate from the delegated call
// assert_eq!(result.err().unwrap(), DateError::InvalidDate);

// Example using unsafe construction for direct error check from week_of_year
let invalid_dt_unsafe = unsafe { ParsiDateTime::new_unchecked(1402, 12, 30, 10, 0, 0) };
let result_unsafe = invalid_dt_unsafe.week_of_year();
assert!(result_unsafe.is_err());
// Expect InvalidDate because the date itself is invalid before calculation starts
assert_eq!(result_unsafe.err().unwrap(), DateError::InvalidDate);