Method first_day_of_year

Returns a new ParsiDate instance representing the first day (Farvardin 1st) of the year corresponding to the date represented by self.

Description

This method creates a new ParsiDate representing the beginning of the Persian calendar year in which the current date (self) falls. It preserves the year from the self instance but sets the month component to 1 (Farvardin) and the day component to 1.

Safety & Performance: For optimal performance, this method likely utilizes unsafe { ParsiDate::new_unchecked } or a similar internal mechanism that bypasses the standard validation checks of ParsiDate::new.

This usage is considered safe under the assumption that the self instance is already a valid ParsiDate. The reasoning is:

1. If self is valid (which may be checked via debug_assert!(self.is_valid()) in debug builds), its year component is inherently within the supported, valid range (e.g., [1, 9999]).
2. Month 1 (Farvardin) and Day 1 always form a valid date combination for any valid Persian calendar year. Therefore, constructing a date with the valid self.year, month = 1, and day = 1 will always result in a valid ParsiDate.

Arguments

This method takes no arguments other than the implicit self reference to the ParsiDate instance it is called on.

Returns

• A new ParsiDate instance representing Farvardin 1st of the same year as the self instance.

Note: Due to the safety assumptions and the fact that Farvardin 1st is always valid for a valid year, this method typically returns a ParsiDate directly, not wrapped in a Result.

Examples (Rust)

use parsidate::ParsiDate; // Assuming ParsiDate exists

// Create a date in the middle of the year
let date_mid_year = ParsiDate::new(1403, 5, 15).unwrap(); // Mordad 15th, 1403

// Get the first day of that year
let first_day = date_mid_year.first_day_of_year();

// Verify the result
assert_eq!(first_day.year(), 1403);
assert_eq!(first_day.month(), 1);
assert_eq!(first_day.day(), 1);
// Compare with a date constructed normally
assert_eq!(first_day, ParsiDate::new(1403, 1, 1).unwrap());


// Create a date at the end of a different year
let date_end_year = ParsiDate::new(1404, 12, 29).unwrap(); // Esfand 29th, 1404 (common year)

// Get the first day of that year
let first_day_for_end = date_end_year.first_day_of_year();

// Verify the result
assert_eq!(first_day_for_end.year(), 1404);
assert_eq!(first_day_for_end.month(), 1);
assert_eq!(first_day_for_end.day(), 1);
assert_eq!(first_day_for_end, ParsiDate::new(1404, 1, 1).unwrap());

// Example with a date that is already the first day
let date_first_day = ParsiDate::new(1399, 1, 1).unwrap();
let first_day_again = date_first_day.first_day_of_year();
assert_eq!(first_day_again, ParsiDate::new(1399, 1, 1).unwrap());