Method first_day_of_month

Returns a new ParsiDate instance representing the first day of the month for the date represented by self.

Description

This method creates a new ParsiDate that corresponds to the very beginning of the month in which the current date (self) resides. It preserves the year and month from the self instance but sets the day component explicitly to 1.

For performance reasons, this method may utilize unsafe { ParsiDate::new_unchecked } or a similar internal, optimized constructor that bypasses the standard validation checks typically performed by ParsiDate::new.

Safety Justification: This optimization is considered safe based on the strong assumption that the self instance, on which the method is called, is already a valid ParsiDate. Since day 1 is always a valid day for any valid month and year combination in the Persian calendar, constructing a date with day 1 using the existing valid year and month will inherently result in a valid ParsiDate.

To help catch potential misuse of this assumption during development, an internal debug_assert!(self.is_valid()) might be included to verify the validity of self in debug builds only.

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 the first day (day 1) of the same month and year as the self instance.

Note: Because it assumes self is valid and day 1 is always valid for that month/year, this method typically returns a ParsiDate directly, not a Result. It does not perform validation that would lead to returning an Err.

Examples (Rust)

use parsidate::ParsiDate; // Assuming ParsiDate exists

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

// Get the first day of that month
let first_day = date.first_day_of_month();

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


// Create a date at the end of a month (Esfand in a common year)
let date_esfand = ParsiDate::new(1404, 12, 29).unwrap(); // 1404 is common year

// Get the first day of that month
let first_day_esfand = date_esfand.first_day_of_month();

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

// Example with a leap year's Esfand
let date_leap_esfand = ParsiDate::new(1403, 12, 30).unwrap(); // 1403 is leap year
let first_day_leap_esfand = date_leap_esfand.first_day_of_month();
assert_eq!(first_day_leap_esfand, ParsiDate::new(1403, 12, 1).unwrap());