Method week_of_year

Calculates the week number of the year for this ParsiDate.

Description

This method determines the week number for the date represented by the ParsiDate instance within its corresponding Persian (Solar Hijri) year. The week number is calculated based on the following specific rules:

• Weeks start on Saturday ("شنبه").
• Week 1 is defined as the week containing the very first day of the year (Farvardin 1st).
• Weeks are numbered sequentially starting from 1 (Week 1, Week 2, Week 3, ...).

For example, if Farvardin 1st of a given year falls on a Wednesday, then Farvardin 1st (Wednesday), Farvardin 2nd (Thursday), and Farvardin 3rd (Friday) are all considered part of Week 1. The following day, Farvardin 4th (Saturday), marks the beginning of Week 2.

The resulting week number typically ranges from 1 to 53.

Returns

• Ok(u32): If the ParsiDate is valid and all calculations succeed, returns the week number (typically an integer between 1 and 53).
• Err(DateError::InvalidDate): If the ParsiDate instance (self) holds invalid date data (e.g., invalid month or day, checked during validation).
• Err(DateError::GregorianConversionError): If the internal calculation of the weekday for the first day of the year (Farvardin 1st) fails, likely due to issues during the necessary Gregorian conversion step.
• Err(DateError::ArithmeticOverflow): If calculating the ordinal day of the year for the given ParsiDate instance results in an arithmetic overflow.

Examples (Rust)

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

// --- Examples based on 1403 (Leap Year) ---
// Farvardin 1st, 1403 was a Wednesday (Weekday index 4 if Sat=0)
let farvardin_1st = ParsiDate::new(1403, 1, 1).unwrap();
// Calculation: wd_first=4, ord=1. week = ((1 + 4 - 1) / 7) + 1 = (4 / 7) + 1 = 0 + 1 = 1
assert_eq!(farvardin_1st.week_of_year(), Ok(1));

// Farvardin 3rd, 1403 was a Friday (Weekday index 6) - Still week 1
let farvardin_3rd = ParsiDate::new(1403, 1, 3).unwrap();
// Calculation: wd_first=4, ord=3. week = ((3 + 4 - 1) / 7) + 1 = (6 / 7) + 1 = 0 + 1 = 1
assert_eq!(farvardin_3rd.week_of_year(), Ok(1));

// Farvardin 4th, 1403 was a Saturday (Weekday index 0) - Start of week 2
let farvardin_4th = ParsiDate::new(1403, 1, 4).unwrap();
// Calculation: wd_first=4, ord=4. week = ((4 + 4 - 1) / 7) + 1 = (7 / 7) + 1 = 1 + 1 = 2
assert_eq!(farvardin_4th.week_of_year(), Ok(2));

// A date later in the year: 1403-05-02 (Ordinal day 126)
let mordad_2nd = ParsiDate::new(1403, 5, 2).unwrap();
// Calculation: wd_first=4, ord=126. week = ((126 + 4 - 1) / 7) + 1 = (129 / 7) + 1 = 18 + 1 = 19
assert_eq!(mordad_2nd.week_of_year(), Ok(19));

// Last day of leap year 1403 (Esfand 30th, Ordinal day 366)
let end_of_1403 = ParsiDate::new(1403, 12, 30).unwrap();
// Calculation: wd_first=4, ord=366. week = ((366 + 4 - 1) / 7) + 1 = (369 / 7) + 1 = 52 + 1 = 53
assert_eq!(end_of_1403.week_of_year(), Ok(53));


// --- Examples based on 1404 (Common Year) ---
// Farvardin 1st, 1404 was a Friday (Weekday index 6 if Sat=0)
let farvardin_1st_1404 = ParsiDate::new(1404, 1, 1).unwrap();
// Calculation: wd_first=6, ord=1. week = ((1 + 6 - 1) / 7) + 1 = (6 / 7) + 1 = 0 + 1 = 1
assert_eq!(farvardin_1st_1404.week_of_year(), Ok(1));

// Farvardin 2nd, 1404 was a Saturday (Weekday index 0) - Start of Week 2
let farvardin_2nd_1404 = ParsiDate::new(1404, 1, 2).unwrap();
// Calculation: wd_first=6, ord=2. week = ((2 + 6 - 1) / 7) + 1 = (7 / 7) + 1 = 1 + 1 = 2
assert_eq!(farvardin_2nd_1404.week_of_year(), Ok(2));

// Last day of common year 1404 (Esfand 29th, Ordinal day 365)
let end_of_1404 = ParsiDate::new(1404, 12, 29).unwrap();
// Calculation: wd_first=6, ord=365. week = ((365 + 6 - 1) / 7) + 1 = (370 / 7) + 1 = 52 + 1 = 53
assert_eq!(end_of_1404.week_of_year(), Ok(53));


// --- Example: Handling an invalid date ---
let invalid_date = unsafe { ParsiDate::new_unchecked(1405, 15, 1) }; // Invalid month
let result = invalid_date.week_of_year();
// Expect an error, likely InvalidDate because validation should fail first
assert!(result.is_err());
assert_eq!(result.err().unwrap(), DateError::InvalidDate); // Check the specific error