Method format_strftime

Formats the ParsiDate instance using strftime-like directives to create a custom date string representation.

Description

This method generates a formatted string representation of the ParsiDate (self) based on a provided pattern string containing format specifiers. The method processes the pattern string from left to right, replacing recognized specifiers (like %Y, %m, %B, etc.) with the corresponding date components.

Characters in the pattern string that are not part of a recognized format specifier are included literally in the output string. An unknown specifier (e.g., %x, %z) will also be outputted literally, including the % sign. A literal percent sign (%) can be included in the output by using %% in the pattern.

Crucially, this method is designed to handle potentially invalid internal states gracefully without panicking. If an error occurs during formatting (e.g., the month number is invalid when trying to get the month name for %B, or the internal date object itself is somehow invalid), specific placeholder strings are inserted into the output instead of the expected value.

Format Specifiers

The following format specifiers are recognized and replaced:

Specifier	Replacement	Example (for ParsiDate::new(1403, 5, 2))	Notes
%Y	Year with century (4 digits)	1403
%m	Month as a zero-padded number	05	(01-12)
%d	Day of the month, zero-padded	02	(01-31)
%B	Full Persian month name	مرداد	Uses localized Persian names
%A	Full Persian weekday name	چهارشنبه	Uses localized Persian names (Sat-Fri)
%w	Weekday as a number	4	Saturday = 0, Sunday = 1, ..., Friday = 6
%j	Day of the year, zero-padded	127	(001-365 or 001-366 for leap years)
%K	Persian season name	تابستان	Bahar, Tabestan, Paeez, Zemestan
%%	A literal % character	%	Escapes the percent sign

Note: The specific examples for %A, %w, and %j assume 1403/05/02 corresponds to a Wednesday (weekday 4) and is the 127th day of the year 1403.

Arguments

• pattern: A string slice (&str) containing the desired format. It can include any combination of the format specifiers listed above and literal characters.

Returns

• A String containing the formatted date according to the pattern.
• If errors occur during formatting (e.g., invalid month number for %B), placeholder strings will be inserted into the output string at the location of the failed specifier.

Error Handling and Placeholders

This method aims to never panic, even with invalid internal data or unexpected conditions during formatting. Instead, it inserts the following placeholders into the resulting string if an error occurs while processing a specific specifier:

• ?InvalidMonth?: If %B (month name) or %K (season name) cannot be determined due to an invalid month number (outside 1-12).
• ?WeekdayError?: If %A (weekday name) or %w (weekday number) cannot be determined (e.g., due to an error in the underlying Gregorian conversion or calculation).
• ?SeasonError?: If %K (season name) cannot be determined (potentially redundant with ?InvalidMonth? but could signify other internal issues).
• ???: A generic placeholder for other unexpected errors during formatting specific components (like %j calculation failure).

Note: The exact placeholder text might vary slightly based on implementation details.

Examples (Rust)

use parsidate::ParsiDate; // Assuming ParsiDate exists

// Example Date: Farvardin 7th, 1403 (Assuming this is a Tuesday, weekday 3, day 7 of year)
let date = ParsiDate::new(1403, 1, 7).unwrap();

// --- Standard Formats ---
// ISO-like format
assert_eq!(date.format_strftime("%Y-%m-%d").as_str(), "1403-01-07");

// Full Persian format
assert_eq!(
    date.format_strftime("%A، %d %B %Y (%K)").as_str(),
    "سه‌شنبه، 07 فروردین 1403 (بهار)" // Assuming Tuesday for 1403/01/07
);

// American-like format
assert_eq!(date.format_strftime("%m/%d/%Y").as_str(), "01/07/1403");


// --- Numeric and Component Formats ---
assert_eq!(
    date.format_strftime("Year %Y, Day of Year: %j (Weekday %w)").as_str(),
    "Year 1403, Day of Year: 007 (Weekday 3)" // Assuming Tuesday=3
);


// --- Literal Characters and Escaping ---
assert_eq!(
    date.format_strftime("Date: %Y/%m/%d.").as_str(),
    "Date: 1403/01/07."
);
assert_eq!(
    date.format_strftime("Sale: %d%% off for month %B!").as_str(),
    "Sale: 07% off for month فروردین!"
);


// --- Unknown Specifier Handling ---
// %x is not a recognized specifier in the table
assert_eq!(
    date.format_strftime("Year %Y %x Month %m").as_str(),
    "Year 1403 %x Month 01"
);


// --- Hypothethical Error Placeholder Example (Cannot be directly triggered if date is valid) ---
// If 'date' somehow became invalid internally *after* creation (e.g., month set to 13):
// let mut invalid_date = date;
// unsafe { /* Modify internal month to 13 */ }
// assert!(invalid_date.format_strftime("%B").contains("?InvalidMonth?"));