Constructor ParsiDateTime::new

Creates a new ParsiDateTime instance from individual Persian date and time components, performing full validation.

Description

This constructor attempts to create a ParsiDateTime object representing the specific date and time provided by the year, month, day, hour, minute, and second arguments.

Crucially, it performs comprehensive validation on both the date and time parts:

1. Date Validation: It verifies that the year, month, and day combination forms a valid date within the Persian (Hejri-Shamsi) calendar. This uses the same logic as ParsiDate::new, checking:
   • Year is within the supported range (e.g., [1, 9999]).
   • Month is between 1 and 12.
   • Day is valid for the given month and year (considering 31/30 days per month and 29/30 days for Esfand based on leap year status).
2. Time Validation: It ensures that the hour, minute, and second components fall within their standard ranges:
   • hour must be between 0 and 23 (inclusive).
   • minute must be between 0 and 59 (inclusive).
   • second must be between 0 and 59 (inclusive).

If all checks pass for both date and time components, a ParsiDateTime instance is successfully created and returned within an Ok variant. If any check fails, an Err variant containing the appropriate DateError is returned.

Arguments

• year (i32 or similar): The Persian year (e.g., 1403). Must be within the library's supported range.
• month (u8 or similar): The Persian month (1 = Farvardin, ..., 12 = Esfand). Must be 1-12.
• day (u8 or similar): The day of the month. Must be valid for the given month and year.
• hour (u8 or similar): The hour of the day (24-hour clock). Must be 0-23.
• minute (u8 or similar): The minute of the hour. Must be 0-59.
• second (u8 or similar): The second of the minute. Must be 0-59.

Returns

• Ok(ParsiDateTime): If all date and time components form a valid Persian date and time within the supported ranges.
• Err(DateError::InvalidDate): If the year, month, day combination is invalid according to Persian calendar rules (delegated to ParsiDate::new logic).
• Err(DateError::InvalidTime): If hour, minute, or second is outside its valid range (0-23, 0-59, 0-59 respectively).

Examples (Rust)

use parsidate::{ParsiDateTime, DateError, ParsiDate}; // Assuming these types exist

// --- Successful Creation ---
let dt_result = ParsiDateTime::new(1403, 5, 2, 15, 30, 45); // Mordad 2nd, 1403, 15:30:45
assert!(dt_result.is_ok());

if let Ok(dt) = dt_result {
    // Verify components if needed
    assert_eq!(dt.date(), ParsiDate::new(1403, 5, 2).unwrap());
    assert_eq!(dt.hour(), 15);
    assert_eq!(dt.minute(), 30);
    assert_eq!(dt.second(), 45);
    assert!(dt.is_valid());
}


// --- Error Cases: Invalid Date ---

// Example: Esfand 30th in a common year (1404)
assert_eq!(
    ParsiDateTime::new(1404, 12, 30, 10, 0, 0),
    Err(DateError::InvalidDate) // Day 30 invalid for Esfand in non-leap year 1404
);

// Example: Day 31 in Mehr (Month 7 only has 30 days)
assert_eq!(
    ParsiDateTime::new(1403, 7, 31, 11, 0, 0),
    Err(DateError::InvalidDate)
);

// Example: Month 13 (invalid month)
assert_eq!(
    ParsiDateTime::new(1403, 13, 1, 12, 0, 0),
    Err(DateError::InvalidDate)
);

// Example: Year 0 (invalid year)
assert_eq!(
    ParsiDateTime::new(0, 1, 1, 13, 0, 0),
    Err(DateError::InvalidDate)
);


// --- Error Cases: Invalid Time ---

// Example: Hour 24 (valid range is 0-23)
assert_eq!(
    ParsiDateTime::new(1403, 5, 2, 24, 0, 0),
    Err(DateError::InvalidTime)
);

// Example: Minute 60 (valid range is 0-59)
assert_eq!(
    ParsiDateTime::new(1403, 5, 2, 10, 60, 0),
    Err(DateError::InvalidTime)
);

// Example: Second 60 (valid range is 0-59)
assert_eq!(
    ParsiDateTime::new(1403, 5, 2, 10, 0, 60),
    Err(DateError::InvalidTime)
);