Method with_second (on ParsiDateTime)

Creates a new ParsiDateTime instance with only the second 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 second component of the time part. The date part (year, month, day) and the other time components (hour, minute) are copied directly from the original self instance.

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

Arguments

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

Returns

• Ok(ParsiDateTime): If the original ParsiDateTime has a valid date part and the provided second is valid (0-59), returns the new ParsiDateTime instance (with updated second and original date/hour/minute) wrapped in Ok.
• Err(DateError::InvalidTime): If the provided second value is outside the valid range [0, 59].
• 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 Second Within Valid Range ---
let dt_new_sec_result = dt.with_second(0); // Change second to 0
assert!(dt_new_sec_result.is_ok());
let dt_new_sec = dt_new_sec_result.unwrap();

// Verify the new second and preserved components
assert_eq!(dt_new_sec.second(), 0);
assert_eq!(dt_new_sec.date(), ParsiDate::new(1403, 5, 2).unwrap()); // Date unchanged
assert_eq!(dt_new_sec.hour(), 10); // Hour unchanged
assert_eq!(dt_new_sec.minute(), 30); // Minute unchanged

// Set second to 59
let dt_59_sec_result = dt.with_second(59);
assert!(dt_59_sec_result.is_ok());
assert_eq!(dt_59_sec_result.unwrap().second(), 59);


// --- Error Case: Attempting to Set an Invalid Second ---
// Try setting second to 60 (valid range is 0-59).
let result_invalid_second = dt.with_second(60);
assert!(result_invalid_second.is_err());
assert_eq!(result_invalid_second, Err(DateError::InvalidTime)); // Check error type

// Try setting second to a large invalid number
let result_invalid_second_large = dt.with_second(100);
assert!(result_invalid_second_large.is_err());
assert_eq!(result_invalid_second_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, 30, 45) }; // Invalid date
// assert!(!invalid_start_dt.is_valid());
// Attempting to change the second should fail because the original date is invalid
// assert_eq!(invalid_start_dt.with_second(50), Err(DateError::InvalidDate));