Method last_day_of_year

Returns a new ParsiDate instance representing the date of the last day of the year for the current date's year.

Description

This method determines the last day of the Persian year corresponding to the self.year of the current ParsiDate instance.

• If self.year is a leap year, the last day is Esfand 30th (Month 12, Day 30).
• If self.year is a common year, the last day is Esfand 29th (Month 12, Day 29).

It then constructs and returns a new ParsiDate instance representing this last day of the year.

Assumption: This method assumes that the self instance upon which it is called is already a valid ParsiDate. A debug_assert!(self.is_valid()) is included to help verify this during development.

Safety & Performance

Similar to last_day_of_month, this method utilizes unsafe { ParsiDate::new_unchecked } internally for performance optimization. This usage is considered safe due to the following reasons:

1. Valid self Assumption: The method assumes self is valid, meaning self.year is guaranteed to be within the supported range (e.g., [1, 9999]). This is checked via debug_assert!.
2. Correct Leap Year Check: The is_persian_leap_year function (or equivalent logic) correctly determines whether the year requires a 29th or 30th day for Esfand.
3. Guaranteed Validity: Month 12 (Esfand) combined with the correctly determined last day (29 or 30) will always form a valid date for the given self.year (which is assumed valid). Creating a date with year = self.year, month = 12, and day = 29 or 30 is inherently valid within the Persian calendar rules for a valid year.

The unsafe block avoids redundant validation checks performed by safer constructors like ParsiDate::new().

Returns

• A new ParsiDate instance representing the last day (Esfand 29th or 30th) of the year corresponding to the self instance's year.

Examples (Rust)

use parsidate::ParsiDate; // Assuming use of a hypothetical ParsiDate struct

// Example 1: Date within a leap year (1403 is leap)
let date_in_leap = ParsiDate::new(1403, 5, 15).unwrap(); // A date sometime in 1403
let last_day_leap = date_in_leap.last_day_of_year();
// Expected: 1403-12-30 (Esfand 30th)
assert_eq!(last_day_leap, ParsiDate::new(1403, 12, 30).unwrap());

// Example 2: Date within a common year (1404 is common)
let date_in_common = ParsiDate::new(1404, 7, 10).unwrap(); // A date sometime in 1404
let last_day_common = date_in_common.last_day_of_year();
// Expected: 1404-12-29 (Esfand 29th)
assert_eq!(last_day_common, ParsiDate::new(1404, 12, 29).unwrap());