Method format (on ParsiDateTime)

Formats the ParsiDateTime instance into a string according to a given format pattern.

Description

This method generates a string representation of the ParsiDateTime based on a provided pattern string. It functions similarly to the strftime function found in C or other date/time libraries.

The method processes the pattern string character by character:

• Format Specifiers: When it encounters a percent sign (%) followed by a recognized character (e.g., %Y, %m, %H), it replaces the specifier with the corresponding value from the ParsiDateTime instance (e.g., year, month number, hour).
• Literal Characters: Any character in the pattern that is not part of a recognized format specifier is included literally in the output string.

This method extends the formatting capabilities of ParsiDate's formatting by adding specifiers for time components (hour, minute, second).

Supported Format Specifiers

The following specifiers are recognized within the pattern string:

Date Specifiers (similar to ParsiDate):

• %Y: Year with century as a decimal number (e.g., 1403).
• %m: Month as a zero-padded decimal number (01, 02, ..., 12).
• %d: Day of the month as a zero-padded decimal number (01, 02, ..., 31).
• %B: Full Persian month name (e.g., "فروردین", "اردیبهشت", ..., "اسفند"). Requires the month component to be valid.
• %A: Full Persian weekday name (e.g., "شنبه", "یکشنبه", ..., "جمعه"). Requires date conversion and validity.
• %w: Weekday as a decimal number, where Saturday is 0 (0, 1, ..., 6). Requires date conversion and validity.
• %j: Day of the year as a zero-padded decimal number (001, 002, ..., 366). Requires date validity.
• %K: Full Persian season name ("بهار", "تابستان", "پاییز", "زمستان"). Requires the month component to be valid.
• %%: A literal % character.

Time Specifiers:

• %H: Hour (24-hour clock) as a zero-padded decimal number (00, 01, ..., 23).
• %M: Minute as a zero-padded decimal number (00, 01, ..., 59).
• %S: Second as a zero-padded decimal number (00, 01, ..., 59).
• %T: Equivalent to %H:%M:%S (e.g., 08:05:30).

Behavior with Invalid Data

Important: If the ParsiDateTime instance was created using unsafe methods and contains invalid data (e.g., month 13, hour 25, day 31 in Mehr):

• Specifiers that directly map to stored values (%Y, %m, %d, %H, %M, %S) might simply output the invalid numerical value stored within the instance.
• Specifiers that require calculation or mapping (%A, %B, %w, %j, %K) might produce unexpected results, default values, error strings (like ?InvalidMonth?), or even panic, depending on the implementation's error handling for invalid inputs during calculation. Always ensure ParsiDateTime instances are valid before relying on complex formatting specifiers.

Arguments

• pattern: A string slice (&str) containing the desired format. It can mix literal characters and the supported format specifiers listed above.

Returns

• String: A newly allocated string containing the date and time formatted according to the provided pattern.

Examples (Rust)

use parsidate::ParsiDateTime; // Assuming ParsiDateTime exists

// Sample date: 2nd Mordad 1403, 08:05:30 AM
// This corresponds to a Tuesday, in Tabestan (Summer)
let dt = ParsiDateTime::new(1403, 5, 2, 8, 5, 30).unwrap();

// Example 1: Common ISO-like format (using Persian calendar date)
assert_eq!(dt.format("%Y-%m-%d %H:%M:%S"), "1403-05-02 08:05:30");

// Example 2: Using %T for time
assert_eq!(dt.format("%Y/%m/%d %T"), "1403/05/02 08:05:30");

// Example 3: Format with full Persian names and season (%B, %K)
// Assuming "مرداد" is month 5 and "تابستان" is the season for month 5
assert_eq!(dt.format("%d %B (%K) %Y ساعت %H:%M"), "02 مرداد (تابستان) 1403 ساعت 08:05");

// Example 4: Including weekday (%A), day of year (%j), and weekday number (%w)
// Assuming 1403-05-02 is a Tuesday ("سه‌شنبه", weekday 3 if Sat=0) and day 126 of the year
assert_eq!(
    dt.format("%A، %d %B %Y - %T (روز %j سال، روز هفته %w)"),
    "سه‌شنبه، 02 مرداد 1403 - 08:05:30 (روز 126 سال، روز هفته 3)"
);

// Example 5: Using literal percent signs
assert_eq!(dt.format("Time is %H:%M %% %S seconds."), "Time is 08:05 % 30 seconds.");

// Example 6: Formatting potentially invalid data (created unsafely)
// Note: The exact output for invalid data specifiers might vary based on implementation.
// This example shows printing the raw, invalid numbers.
let invalid_dt = unsafe { ParsiDateTime::new_unchecked(1403, 1, 1, 25, 61, 99) };
assert_eq!(invalid_dt.format("%H:%M:%S"), "25:61:99"); // Outputs the invalid numbers
// Formatting with calculated fields might yield errors or placeholders:
// assert_eq!(invalid_dt.format("%A"), "?InvalidDate?"); // Hypothetical output