Static Function ParsiDateTime::from_date_and_time

Creates a ParsiDateTime instance from a pre-existing ParsiDate object and individual time components (hour, minute, second).

Description

This function constructs a new ParsiDateTime by combining a given ParsiDate object with specified hour, minute, and second values.

A key difference from the standard ParsiDateTime::new constructor is that this function assumes the provided date argument is already a valid ParsiDate. It performs validation only on the time components (hour, minute, second) to ensure they fall within their standard ranges (0-23, 0-59, 0-59 respectively).

This approach can offer a slight performance benefit compared to ParsiDateTime::new if you have already validated or obtained a known-valid ParsiDate instance separately.

Arguments

• date: A ParsiDate object. This function assumes date represents a valid Persian date.
• hour: The hour component for the time (0-23).
• minute: The minute component for the time (0-59).
• second: The second component for the time (0-59).

Returns

• Ok(ParsiDateTime): If the provided hour, minute, and second values are within their valid ranges. The resulting ParsiDateTime combines the input date and the validated time components.
• Err(DateError::InvalidTime): If hour, minute, or second is outside its valid range (e.g., hour = 24, minute = 60).

Validation and Safety Considerations

• Time Validation Only: This function only validates the hour, minute, and second arguments. It explicitly trusts that the input date object is valid.
• Risk of Invalid Input Date: If an invalid ParsiDate (e.g., one created using unsafe ParsiDate::new_unchecked with incorrect data like month 13 or day 31 for Mehr) is passed as the date argument, this function will likely still return Ok (as long as the time components are valid). However, the resulting ParsiDateTime object will contain an invalid date part, which can lead to incorrect behavior or errors in subsequent operations.
• Recommendation: Only use this function if you are certain that the input date object is valid. If unsure, either use the standard ParsiDateTime::new constructor (which validates both date and time) or check the validity of the resulting ParsiDateTime object using its is_valid() method immediately after creation.

Examples (Rust)

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

// --- Success Case with Valid Date ---

// Assume `my_date` is known to be valid (e.g., from ParsiDate::new or other checks)
let my_date = ParsiDate::new(1399, 11, 22).expect("Date creation should succeed"); // Bahman 22nd, 1399

// Create a ParsiDateTime using the pre-validated date and valid time
let dt_result = ParsiDateTime::from_date_and_time(my_date, 20, 15, 0);
assert!(dt_result.is_ok());
let dt = dt_result.unwrap();

// Verify the components
assert_eq!(dt.date(), my_date); // Date part matches the input
assert_eq!(dt.hour(), 20);
assert_eq!(dt.minute(), 15);
assert_eq!(dt.second(), 0);
assert!(dt.is_valid()); // The resulting DateTime should be valid

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

// Invalid minute (60)
assert_eq!(
    ParsiDateTime::from_date_and_time(my_date, 10, 60, 0),
    Err(DateError::InvalidTime)
);

// Invalid hour (24)
assert_eq!(
    ParsiDateTime::from_date_and_time(my_date, 24, 0, 0),
    Err(DateError::InvalidTime)
);

// Invalid second (60) - Assuming standard range 0-59
assert_eq!(
    ParsiDateTime::from_date_and_time(my_date, 10, 0, 60),
    Err(DateError::InvalidTime)
);

// --- Warning Case: Passing an Invalid Date ---

// Create an invalid ParsiDate unsafely (Esfand 30 in a common year)
let invalid_date = unsafe { ParsiDate::new_unchecked(1404, 12, 30) }; // 1404 is common
assert!(!invalid_date.is_valid()); // Confirm the ParsiDate itself is invalid

// Call from_date_and_time with the *invalid* date but *valid* time
let result_with_invalid_date = ParsiDateTime::from_date_and_time(invalid_date, 10, 0, 0);

// The function SUCCEEDS because it only checks the time components!
assert!(result_with_invalid_date.is_ok());

// However, the resulting ParsiDateTime object is INVALID overall
let invalid_dt = result_with_invalid_date.unwrap();
assert!(!invalid_dt.is_valid()); // Check reveals the contained date is invalid

println!("Created DateTime with invalid date part: {:?}", invalid_dt); // Example output