Constructor ParsiDate::new

Creates a new ParsiDate instance from individual year, month, and day components, performing validation.

Description

This constructor attempts to create a ParsiDate object representing the date specified by the year, month, and day arguments. Crucially, it performs validation to ensure that the provided combination forms a valid date according to the rules of the Persian (Hejri-Shamsi) calendar and falls within the supported range of this library.

The validation checks include:

1. Year Range: The year must be between 1 and 9999 (inclusive).
2. Month Range: The month must be between 1 (Farvardin) and 12 (Esfand) (inclusive).
3. Day Range: The day must be between 1 and the correct number of days for the specified month in the given year. This logic correctly handles:
   • Months 1-6 (Farvardin to Shahrivar) having 31 days.
   • Months 7-11 (Mehr to Bahman) having 30 days.
   • Month 12 (Esfand) having 30 days in a leap year and 29 days in a common year.

If all checks pass, a ParsiDate instance is successfully created and returned within an Ok variant. If any check fails, an Err variant containing a DateError is returned.

Arguments

• year (i32 or similar integer type): The Persian year component. Must be within the range [1, 9999].
• month (u8 or similar integer type): The Persian month component. Must be within the range [1, 12]. (1 = Farvardin, ..., 12 = Esfand).
• day (u8 or similar integer type): The day of the month component. Must be valid for the given month and year (e.g., between 1 and 29, 30, or 31).

Returns

• Ok(ParsiDate): If the provided year, month, and day form a valid Persian date within the supported range. The ParsiDate instance representing that date is contained within the Ok.
• Err(DateError::InvalidDate): If the combination of year, month, and day is invalid (e.g., month is 13, day is 31 for Mehr, day is 30 for Esfand in a common year, year is 0 or 10000).

Examples (Rust)

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

// --- Successful Creation ---

// Create a standard valid date
let date_result = ParsiDate::new(1403, 5, 2); // 2nd of Mordad, 1403
assert!(date_result.is_ok());
// We can safely unwrap now
let date = date_result.unwrap();
assert_eq!(date.year(), 1403);
assert_eq!(date.month(), 5);
assert_eq!(date.day(), 2);

// Create a date representing a leap day (Esfand 30th in a leap year)
let leap_day_result = ParsiDate::new(1403, 12, 30); // 1403 is a leap year
assert!(leap_day_result.is_ok());
assert_eq!(leap_day_result.unwrap(), ParsiDate::new(1403, 12, 30).unwrap());


// --- Failed Creation (Invalid Inputs) ---

// Example of an invalid month (Month 13)
assert_eq!(ParsiDate::new(1403, 13, 1), Err(DateError::InvalidDate));

// Example of an invalid day (Esfand 30th in a common year)
assert_eq!(ParsiDate::new(1404, 12, 30), Err(DateError::InvalidDate)); // 1404 is common

// Example of an invalid day (Day 31 in a 30-day month)
assert_eq!(ParsiDate::new(1403, 7, 31), Err(DateError::InvalidDate)); // Mehr (month 7) has 30 days

// Example of an invalid day (Day 0)
assert_eq!(ParsiDate::new(1403, 1, 0), Err(DateError::InvalidDate));

// Example of an invalid year (Year 0 - outside supported range [1, 9999])
assert_eq!(ParsiDate::new(0, 1, 1), Err(DateError::InvalidDate));

// Example of an invalid year (Year 10000 - outside supported range [1, 9999])
assert_eq!(ParsiDate::new(10000, 1, 1), Err(DateError::InvalidDate));