Method with_time (on ParsiDateTime)

Creates a new ParsiDateTime instance with completely new time components (hour, minute, second), preserving the original date component.

Description

This method creates a new ParsiDateTime based on the current instance (self), replacing the entire time part with the provided hour, minute, and second. The date part (year, month, day) is copied directly from the original self instance.

This method performs validation on all provided time components (hour, minute, second) to ensure they fall within their standard valid ranges (0-23 for hour, 0-59 for minute and second). It also implicitly relies on the original ParsiDateTime's date part being valid.

Arguments

• hour: The desired new hour (u8 or similar integer type). Must be between 0 and 23 (inclusive).
• minute: The desired new minute (u8 or similar integer type). Must be between 0 and 59 (inclusive).
• second: The desired new second (u8 or similar integer type). Must be between 0 and 59 (inclusive).

Returns

• Ok(ParsiDateTime): If the original ParsiDateTime has a valid date part and the provided hour, minute, and second are all valid, returns the new ParsiDateTime instance (with the updated time and original date) wrapped in Ok.
• Err(DateError::InvalidTime): If any of the provided hour, minute, or second values are outside their respective valid ranges (e.g., hour = 24, minute = 60).
• Err(DateError::InvalidDate): If the date part of the original ParsiDateTime instance (self) was invalid (e.g., created unsafely with invalid date components).

Examples (Rust)

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

let dt = ParsiDateTime::new(1403, 5, 2, 10, 30, 45).unwrap(); // 1403-05-02 10:30:45

// --- Success Case: Change Time Within Valid Range ---
let dt_new_time_result = dt.with_time(23, 59, 59); // Change time to 23:59:59
assert!(dt_new_time_result.is_ok());
let dt_new_time = dt_new_time_result.unwrap();

// Verify the new time components and preserved date
assert_eq!(dt_new_time.hour(), 23);
assert_eq!(dt_new_time.minute(), 59);
assert_eq!(dt_new_time.second(), 59);
assert_eq!(dt_new_time.date(), ParsiDate::new(1403, 5, 2).unwrap()); // Date unchanged

// Change time to 00:00:00
let dt_zero_time_result = dt.with_time(0, 0, 0);
assert!(dt_zero_time_result.is_ok());
let dt_zero_time = dt_zero_time_result.unwrap();
assert_eq!(dt_zero_time.hour(), 0);
assert_eq!(dt_zero_time.minute(), 0);
assert_eq!(dt_zero_time.second(), 0);
assert_eq!(dt_zero_time.date(), dt.date()); // Date still unchanged


// --- Error Case: Attempting to Set an Invalid Time Component ---

// Try setting minute to 60 (invalid).
let result_invalid_minute = dt.with_time(11, 60, 0);
assert!(result_invalid_minute.is_err());
assert_eq!(result_invalid_minute, Err(DateError::InvalidTime)); // Check error type

// Try setting hour to 24 (invalid).
let result_invalid_hour = dt.with_time(24, 0, 0);
assert!(result_invalid_hour.is_err());
assert_eq!(result_invalid_hour, Err(DateError::InvalidTime)); // Check error type

// Try setting second to 70 (invalid).
let result_invalid_second = dt.with_time(10, 30, 70);
assert!(result_invalid_second.is_err());
assert_eq!(result_invalid_second, Err(DateError::InvalidTime)); // Check error type


// --- Error Case: Starting date is invalid ---
// Create an invalid DateTime unsafely (invalid date part)
// let invalid_start_dt = unsafe { ParsiDateTime::new_unchecked(1404, 13, 30, 10, 30, 0) }; // Invalid month 13
// assert!(!invalid_start_dt.is_valid()); // Assuming an is_valid method exists or internal check fails
// Attempting to change the time should fail because the original date is invalid
// assert_eq!(invalid_start_dt.with_time(11, 30, 0), Err(DateError::InvalidDate));