Method ordinal

Calculates the day number within the year, commonly known as the ordinal day.

Description

This method determines the position of the current ParsiDate instance's date within its year. The counting starts from 1 for the first day of the year (Farvardin 1st).

• For a common Persian year, the result will be an integer between 1 and 365 (inclusive).
• For a leap Persian year, the result will be an integer between 1 and 366 (inclusive).

The calculation involves summing the number of days in the preceding months of the year and adding the day of the current month.

Returns

• Ok(u16) or Ok(u32): If the calculation is successful, returns the ordinal day number (1-based) wrapped in Ok. The specific integer type (u16 or u32) depends on the implementation, but it will be large enough to hold 366.
• Err(DateError::InvalidDate): If the ParsiDate instance itself contains invalid data (e.g., it was created using unsafe ParsiDate::new_unchecked with out-of-range month or day values like 0). The method likely performs internal checks to detect such inconsistencies before calculation.
• Err(DateError::ArithmeticOverflow): In the highly unlikely event that an internal arithmetic overflow occurs during the summation of days within the year. This is generally improbable when calculating the ordinal day using standard integer types like u32.

Examples (Rust)

use parsidate::{ParsiDate, DateError}; // Assuming ParsiDate and DateError

// Example 1: First day of the year (Farvardin 1st)
let date1 = ParsiDate::new(1403, 1, 1).unwrap();
assert_eq!(date1.ordinal(), Ok(1));

// Example 2: Second day of the year (Farvardin 2nd)
let date2 = ParsiDate::new(1403, 1, 2).unwrap();
assert_eq!(date2.ordinal(), Ok(2));

// Example 3: First day of the second month (Ordibehesht 1st)
// Follows Farvardin, which has 31 days. So, 31 + 1 = 32.
let date3 = ParsiDate::new(1403, 2, 1).unwrap();
assert_eq!(date3.ordinal(), Ok(32));

// Example 4: Last day of a leap year (1403 is leap)
let date_leap_end = ParsiDate::new(1403, 12, 30).unwrap();
assert_eq!(date_leap_end.ordinal(), Ok(366));

// Example 5: Last day of a common year (1404 is common)
let date_common_end = ParsiDate::new(1404, 12, 29).unwrap();
assert_eq!(date_common_end.ordinal(), Ok(365));

// Example 6: Handling an invalid date created unsafely
// Trying to calculate ordinal for a date with month 0.
let invalid_date = unsafe { ParsiDate::new_unchecked(1403, 0, 1) };
let ordinal_result = invalid_date.ordinal();
// We expect an error, likely InvalidDate
assert!(ordinal_result.is_err());
// Optionally check the specific error kind if the API guarantees it
// assert_eq!(ordinal_result, Err(DateError::InvalidDate));

// Example 7: A date later in the year (Mehr 10th = Month 7, Day 10)
// Months 1-6 have 31 days = 6 * 31 = 186 days
// Ordinal = 186 (days in first 6 months) + 10 (day in Mehr) = 196
let date_mehr = ParsiDate::new(1403, 7, 10).unwrap();
assert_eq!(date_mehr.ordinal(), Ok(196));