Method format

Formats the ParsiDate instance into a string based on either predefined style names or a custom strftime-like pattern.

Description

This method provides a flexible way to represent the ParsiDate (self) as a formatted string. It accepts a single argument which can be either:

1. A predefined style name: A specific string ("short", "long", "iso") that corresponds to a commonly used date format.
2. A custom pattern string: A string containing literal characters and strftime-like format specifiers (e.g., %Y, %m, %d, %B) which allows for fine-grained control over the output format.

When a custom pattern is provided, this method typically delegates the formatting logic to the format_strftime method, supporting the same set of specifiers and error handling behavior (using placeholders for invalid components). The short format is often used as the default representation, for instance, when using the Display trait (to_string()).

Arguments

• pattern_or_style: A string slice (&str) that is either:
  • One of the predefined style names: "short", "long", "iso".
  • A custom format pattern string containing strftime-like specifiers.

Formatting Options

Predefined Styles

These style names provide convenient shortcuts for common formats:

Style	Format Example	Description
short	"1403/05/02"	Default numeric format (YYYY/MM/DD).
long	"2 مرداد 1403"	Common Persian format (Day MonthName Year).
iso	"1403-05-02"	ISO 8601 standard format (YYYY-MM-DD).

Note: The Display trait implementation for ParsiDate typically defaults to the "short" format.

Custom Patterns

If the pattern_or_style argument does not match a predefined style name, it is treated as a custom format pattern. This allows for detailed control over the output using the same specifiers supported by the format_strftime method. Key specifiers include:

Specifier	Replacement	Example (for 1403/05/02)
%Y	Year with century (4 digits)	1403
%m	Month as a zero-padded number	05
%d	Day of the month, zero-padded	02
%B	Full Persian month name	مرداد
%A	Full Persian weekday name	چهارشنبه
%w	Weekday as a number (Sat=0)	4
%j	Day of the year, zero-padded	127
%K	Persian season name	تابستان
%%	A literal % character	%

(Refer to format_strftime documentation for the full list and detailed behavior.)

Returns

• A String containing the formatted date according to the specified style or pattern.
• Placeholder strings (e.g., ?InvalidMonth?) may be included in the output if the underlying date components are invalid or if errors occur during formatting, especially when using custom patterns.

Error Handling

• Designed to handle invalid internal date states gracefully without panicking.
• If formatting fails for a specific component (e.g., getting the name for an invalid month number when using %B or the "long" style), descriptive placeholder strings are inserted into the output.
• The overall structure of the requested format is generally maintained even if some components are replaced by placeholders.

Examples (Rust)

use parsidate::ParsiDate; // Assuming ParsiDate exists

// Example Date: Mordad 2nd, 1403
let date = ParsiDate::new(1403, 5, 2).unwrap();

// --- Using Predefined Styles ---
assert_eq!(date.format("short").as_str(), "1403/05/02");
assert_eq!(date.format("long").as_str(), "2 مرداد 1403"); // Note: Day is not zero-padded in 'long'
assert_eq!(date.format("iso").as_str(), "1403-05-02");

// --- Default Display Trait ---
// Usually matches the 'short' format
assert_eq!(date.to_string().as_str(), "1403/05/02");


// --- Using Custom Patterns ---
// Custom pattern similar to 'long' but with zero-padded day
assert_eq!(date.format("%d %B %Y").as_str(), "02 مرداد 1403");

// Custom pattern showing day of year and season
// (Assuming 1403/05/02 is day 127 and in Tabestan/Summer)
assert_eq!(date.format("%Y-%j (%K)").as_str(), "1403-127 (تابستان)");

// Mixing literals and specifiers
assert_eq!(date.format("Date: %d/%m/%Y Season: %K").as_str(), "Date: 02/05/1403 Season: تابستان");


// --- Using an unrecognized string treats it as a custom pattern ---
// If "medium" is not a predefined style, it's treated as a literal pattern
assert_eq!(date.format("medium").as_str(), "medium");