Method add_days (on ParsiDateTime)

Adds a specified number of days to the date part of this ParsiDateTime, returning a new ParsiDateTime with the same time component.

Description

This method calculates a new ParsiDateTime by modifying only the date part (year, month, day) based on the number of days added or subtracted. The time part (hour, minute, second) of the original ParsiDateTime instance remains unchanged in the resulting instance.

The core date calculation, including handling month/year boundaries and leap years, is delegated to the corresponding ParsiDate::add_days method. Please refer to its documentation for details on the date arithmetic logic and potential errors related to the date calculation itself.

Arguments

• days: The number of days to add (i64 or similar signed integer type).
  • A positive value moves the date forward.
  • A negative value moves the date backward.

Returns

• Ok(ParsiDateTime): If the starting ParsiDateTime is valid and the underlying ParsiDate::add_days call succeeds, returns the new ParsiDateTime instance (with updated date and original time) wrapped in Ok.
• Err(DateError::...): Returns an error if either of the following occurs:
  1. The starting ParsiDateTime instance itself holds invalid data (e.g., invalid date or time components, potentially from unsafe creation). An internal validity check might be performed first.
  2. The delegated call to ParsiDate::add_days fails. This propagates errors like DateError::InvalidDate (if the underlying date part was invalid), DateError::GregorianConversionError (if conversion is used internally by ParsiDate::add_days), or DateError::ArithmeticOverflow (if the resulting date falls outside the supported range).

Examples (Rust)

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

let dt = ParsiDateTime::new(1403, 1, 15, 10, 30, 0).unwrap(); // Farvardin 15th, 10:30:00

// --- Adding Days ---

// Add 20 days. Farvardin has 31 days.
// 31 - 15 = 16 days left in Farvardin.
// Need 20 - 16 = 4 more days -> Lands on Ordibehesht 4th.
let dt_plus_20d = dt.add_days(20);
assert!(dt_plus_20d.is_ok());
let dt_plus_20d_unwrapped = dt_plus_20d.unwrap();
// Check the date part
assert_eq!(dt_plus_20d_unwrapped.date(), ParsiDate::new(1403, 2, 4).unwrap()); // Expected date: 1403-02-04
// Check that the time part is unchanged
assert_eq!(dt_plus_20d_unwrapped.hour(), 10);
assert_eq!(dt_plus_20d_unwrapped.minute(), 30);
assert_eq!(dt_plus_20d_unwrapped.second(), 0);


// --- Subtracting Days ---

let dt2 = ParsiDateTime::new(1404, 1, 5, 23, 59, 59).unwrap(); // Farvardin 5th, 1404, almost midnight

// Subtract 10 days. Go back 5 days to 1403-12-30 (1403 is leap). Need 5 more days.
// -> Lands on 1403-12-25.
let dt_minus_10d = dt2.add_days(-10);
assert!(dt_minus_10d.is_ok());
let dt_minus_10d_unwrapped = dt_minus_10d.unwrap();
// Check the date part
assert_eq!(dt_minus_10d_unwrapped.date(), ParsiDate::new(1403, 12, 25).unwrap()); // Expected date: 1403-12-25
// Check that the time part is unchanged
assert_eq!(dt_minus_10d_unwrapped.hour(), 23);
assert_eq!(dt_minus_10d_unwrapped.minute(), 59);
assert_eq!(dt_minus_10d_unwrapped.second(), 59);


// --- Error Case (e.g., Resulting date out of range) ---
let earliest_dt = ParsiDateTime::new(1, 1, 1, 0, 0, 0).unwrap();
let result = earliest_dt.add_days(-1); // Attempt to go before year 1
assert!(result.is_err());
// The error kind would be propagated from ParsiDate::add_days
// assert!(matches!(result, Err(DateError::ArithmeticOverflow) | Err(DateError::GregorianConversionError)));