Method with_hour (on ParsiDateTime)

Creates a new ParsiDateTime instance with only the hour component changed, preserving the date and other time components.

Description

This method creates a new ParsiDateTime based on the current instance (self), replacing only the hour component of the time part. The date part (year, month, day) and the other time components (minute, second) are copied directly from the original self instance.

This method performs validation on the provided hour value to ensure it is within the standard 24-hour clock range (0-23). It also implicitly checks if the original ParsiDateTime's date part was valid.

Arguments

• hour: The desired new hour (u8 or similar integer type) for the new ParsiDateTime. Must be between 0 and 23 (inclusive).

Returns

• Ok(ParsiDateTime): If the original ParsiDateTime has a valid date part and the provided hour is valid (0-23), returns the new ParsiDateTime instance (with updated hour and original date/minute/second) wrapped in Ok.
• Err(DateError::InvalidTime): If the provided hour value is outside the valid range [0, 23].
• 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(); // 10:30:45 AM

// --- Success Case: Change Hour Within Valid Range ---
let dt_evening_result = dt.with_hour(18); // Change hour to 18 (6 PM)
assert!(dt_evening_result.is_ok());
let dt_evening = dt_evening_result.unwrap();

// Verify the new hour and preserved components
assert_eq!(dt_evening.hour(), 18);
assert_eq!(dt_evening.date(), ParsiDate::new(1403, 5, 2).unwrap()); // Date unchanged
assert_eq!(dt_evening.minute(), 30); // Minute unchanged
assert_eq!(dt_evening.second(), 45); // Second unchanged

// Set hour to 0 (midnight)
let dt_midnight_result = dt.with_hour(0);
assert!(dt_midnight_result.is_ok());
assert_eq!(dt_midnight_result.unwrap().hour(), 0);


// --- Error Case: Attempting to Set an Invalid Hour ---
// Try setting hour to 24 (valid range is 0-23).
let result_invalid_hour = dt.with_hour(24);
assert!(result_invalid_hour.is_err());
assert_eq!(result_invalid_hour, Err(DateError::InvalidTime)); // Check error type

// Try setting hour to a large invalid number
let result_invalid_hour_large = dt.with_hour(100);
assert!(result_invalid_hour_large.is_err());
assert_eq!(result_invalid_hour_large, Err(DateError::InvalidTime));


// --- Error Case: Starting date is invalid ---
// Create an invalid DateTime unsafely (invalid date part)
// let invalid_start_dt = unsafe { ParsiDateTime::new_unchecked(1404, 12, 30, 10, 0, 0) }; // Invalid date
// assert!(!invalid_start_dt.is_valid());
// Attempting to change the hour should fail because the original date is invalid
// assert_eq!(invalid_start_dt.with_hour(11), Err(DateError::InvalidDate));