Static Function ParsiDate::today

Returns the current system date, converted to a ParsiDate instance.

Description

This function determines the current date based on the system's local timezone setting. It retrieves the current Gregorian date from the operating system and then converts that Gregorian date into its corresponding ParsiDate using the library's conversion logic (equivalent to calling ParsiDate::from_gregorian on the current Gregorian date).

The result reflects the date at the moment the function is called, according to the system's clock and timezone configuration.

How it Works

1. Retrieves the current date from the operating system, respecting the local timezone settings.
2. Obtains the Gregorian date components (year, month, day) from this system date.
3. Uses the internal conversion logic (as found in ParsiDate::from_gregorian) to convert these Gregorian components into a ParsiDate.

Dependencies and Considerations

• System Clock: The accuracy of the result depends on the accuracy of the system's clock.
• Local Timezone: The date determined is based on the system's configured local timezone. Date transitions (like midnight) depend on this timezone.
• Conversion Logic: Relies on the correctness and supported range of the internal Gregorian-to-Persian conversion function (from_gregorian).

Returns

• Ok(ParsiDate): If the current system date can be successfully obtained and converted to a valid ParsiDate, returns that ParsiDate instance wrapped in Ok.
• Err(DateError::GregorianConversionError): If the conversion from the current system's Gregorian date to ParsiDate fails. See the Errors section for causes.

Errors

Returns Err(DateError::GregorianConversionError) under the following primary conditions:

• System Date Out of Range: The system clock is set to a Gregorian date that falls before the start of the Persian epoch (approximately March 622 CE), which cannot be represented by ParsiDate or handled by the [from_gregorian] conversion logic.
• Other Conversion Issues: Any other error that might occur during the internal call to the [from_gregorian] logic when processing the current system date.

Examples (Rust)

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

// Attempt to get today's Persian date
match ParsiDate::today() {
    Ok(today) => {
        // Successfully retrieved and converted the date
        println!("Today in the Persian calendar is: {}", today); // Assumes Display trait is implemented
        println!(
            "Current Persian Date: Year={}, Month={}, Day={}",
            today.year(),
            today.month(),
            today.day()
        );

        // Example: Perform actions based on the current Persian date
        if today.month() == 1 {
            println!("Happy New Year (Nowruz) season!");
        } else if today.month() == 12 {
            println!("We are in Esfand, the last month of the Persian year!");
        } else {
            println!("Current Persian Month: {}", today.month());
        }

        // You can now work with the 'today' ParsiDate object
        // let next_week = today.add_days(7);
        // println!("One week from now: {:?}", next_week);

    }
    Err(e) => {
        // Failed to get or convert the date
        eprintln!("Could not determine today's Persian date: {}", e);
        eprintln!("This might indicate an issue with the system clock (e.g., set before 622 CE) or an internal conversion problem.");
        // Handle the error appropriately in your application
    }
}