PersianDateShamsi 2.0.0

Persian Date Library

Convert Gregorian (Miladi) dates to Solar Hijri (Shamsi) dates with ease!

Features

Core Features

• Convert Gregorian dates to Shamsi (Persian) dates
• Support for both DateTime and DateTimeOffset
• Get Shamsi year, month, and day components
• Get Shamsi month and day names
• Extension methods for easy conversion

✨ New in v2.0.0

• 🚀 .NET 10 Support: Full support for .NET 10.0
• 🎨 Enhanced Formatting Options: Multiple format styles, Persian/English digits, custom patterns
• 🔍 Date Parsing and Validation: Parse Persian date strings with comprehensive validation
• 🌐 Localization and Culture Support: Full Persian and English culture support with RTL text

Installation

Install the package via NuGet:

dotnet add package PersianDateShamsi

Usage

Basic Conversion

using PersianDate;

PersianDateShamsi persianDate = new PersianDateShamsi();
DateTime now = DateTime.Now;

int shamsiYear = persianDate.GetShamsiYear(now);
string shamsiMonthName = persianDate.GetShamsiMonthName(now);
string shamsiDayString = persianDate.GetShamsiDayString(now);
string shamsiDayName = persianDate.GetShamsiDayName(now);
string shamsiDayShortName = persianDate.GetShamsiDayShortName(now);

Console.WriteLine($"Year: {shamsiYear}");
// Output: Year: 1402

Console.WriteLine($"Month: {shamsiMonthName}");
// Output: Month: فروردین

Console.WriteLine($"Day: {shamsiDayString}");
// Output: Day: 01

Console.WriteLine($"Day Name: {shamsiDayName}");
// Output: Day Name: سه‌شنبه

Console.WriteLine($"Short Day Name: {shamsiDayShortName}");
// Output: Short Day Name: سه‌

✨ Enhanced Formatting Options (New in v1.9.3)

Multiple Format Styles

using PersianDate;

DateTime date = new DateTime(2024, 3, 20);

// Predefined format styles
string short = ShamsiDateFormatter.Format(date, ShamsiFormatStyle.Short);
// Output: ۱۴۰۳/۱/۱

string medium = ShamsiDateFormatter.Format(date, ShamsiFormatStyle.Medium);
// Output: ۱ فرو ۱۴۰۳

string long = ShamsiDateFormatter.Format(date, ShamsiFormatStyle.Long);
// Output: ۱ فروردین ۱۴۰۳

string full = ShamsiDateFormatter.Format(date, ShamsiFormatStyle.Full);
// Output: چهارشنبه، ۱ فروردین ۱۴۰۳

Custom Format Patterns

// Custom patterns with Persian digits (default)
string custom1 = ShamsiDateFormatter.Format(date, "yyyy/MM/dd");
// Output: ۱۴۰۳/۰۱/۰۱

string custom2 = ShamsiDateFormatter.Format(date, "dddd، dd MMMM yyyy");
// Output: چهارشنبه، ۰۱ فروردین ۱۴۰۳

// English digits
string english = ShamsiDateFormatter.FormatWithEnglishDigits(date, "yyyy/MM/dd");
// Output: 1403/01/01

Time Formatting

DateTime dateTime = new DateTime(2024, 3, 20, 14, 30, 45);

string withTime = ShamsiDateFormatter.Format(dateTime, "yyyy/MM/dd HH:mm:ss");
// Output: ۱۴۰۳/۰۱/۰۱ ۱۴:۳۰:۴۵

string timeOnly = ShamsiDateFormatter.FormatTime(dateTime, "HH:mm");
// Output: ۱۴:۳۰

🔍 Date Parsing and Validation (New in v1.9.3)

Parse Persian Date Strings

using PersianDate;

// Parse various formats
DateTime parsed1 = ShamsiDateParser.Parse("۱۴۰۳/۱/۱");
DateTime parsed2 = ShamsiDateParser.Parse("1403/1/1");
DateTime parsed3 = ShamsiDateParser.Parse("1403-01-01");

// Safe parsing with TryParse
if (ShamsiDateParser.TryParse("۱۴۰۳/۱۲/۲۹", out DateTime result))
{
    Console.WriteLine($"Parsed: {result}");
}

// Strict validation
var validation = ShamsiDateParser.ParseAndValidate("1403/13/1");
if (!validation.IsValid)
{
    Console.WriteLine($"Error: {validation.ErrorMessage}");
    // Output: Error: Month must be between 1 and 12
}

Validation Options

// Different validation modes
bool isValid1 = ShamsiDateParser.IsValidShamsiDate(1403, 12, 30); // false (invalid day)
bool isValid2 = ShamsiDateParser.IsValidShamsiDate(1403, 6, 31);  // false (month 6 has max 31 days)
bool isValid3 = ShamsiDateParser.IsValidShamsiDate(1403, 1, 31);  // true

// Parse with custom validation
var strictResult = ShamsiDateParser.ParseAndValidate("1403/12/30", ValidationMode.Strict);
var lenientResult = ShamsiDateParser.ParseAndValidate("1403/12/30", ValidationMode.Lenient);

🌐 Localization and Culture Support (New in v1.9.3)

Persian Culture

using PersianDate;

DateTime date = new DateTime(2024, 3, 20);
var persianCulture = ShamsiCultureInfo.Persian;

// Persian formatting with Persian digits and month names
string persian = ShamsiLocalizedFormatter.Format(date, "dd MMMM yyyy", persianCulture);
// Output: ۰۱ فروردین ۱۴۰۳

// Extension method for Persian culture
string persianExt = date.ToShamsiString(ShamsiFormatStyle.Long, persianCulture);
// Output: ۱ فروردین ۱۴۰۳

English Culture

var englishCulture = ShamsiCultureInfo.English;

// English formatting with English digits and transliterated names
string english = ShamsiLocalizedFormatter.Format(date, "dd MMMM yyyy", englishCulture);
// Output: 01 Farvardin 1403

// Extension method for English culture
string englishExt = date.ToShamsiString(ShamsiFormatStyle.Full, englishCulture);
// Output: Wednesday, 1 Farvardin 1403

Culture-Specific Properties

// Persian culture properties
Console.WriteLine(persianCulture.DisplayName);        // فارسی (ایران)
Console.WriteLine(persianCulture.IsRightToLeft);      // true
Console.WriteLine(persianCulture.UsesPersianDigits);  // true
Console.WriteLine(persianCulture.DateSeparator);      // /

// English culture properties  
Console.WriteLine(englishCulture.DisplayName);        // English
Console.WriteLine(englishCulture.IsRightToLeft);      // false
Console.WriteLine(englishCulture.UsesPersianDigits);  // false

Extension Methods

using PersianDate;

DateTime? dateTime = new DateTime(2023, 10, 5);
DateTimeOffset? dateTimeOffset = new DateTimeOffset(2023, 10, 5, 0, 0, 0, TimeSpan.Zero);

Console.WriteLine(dateTime.ToShamsiDate());
// Output: 1402/07/13

Console.WriteLine(dateTimeOffset.ToShamsiDate());
// Output: 1402/07/13

Console.WriteLine(dateTime.ToShortShamsiDate());
// Output: 02/07/13

Console.WriteLine(dateTimeOffset.ToShortShamsiDate());
// Output: 02/07/13

Console.WriteLine(dateTime.ToLongShamsiDate());
// Output: پنجشنبه 13 مهر 1402

Console.WriteLine(dateTimeOffset.ToLongShamsiDate());
// Output: پنجشنبه 13 مهر 1402

// New localized extensions
Console.WriteLine(dateTime.ToShamsiString(ShamsiFormatStyle.Full, ShamsiCultureInfo.English));
// Output: Thursday, 13 Mehr 1402

Converting to Gregorian

using PersianDate;

ToGregorian toGregorian = new ToGregorian();

int gregorianYear = toGregorian.GetGregorianYear(1402, 1, 1);
DateTime gregorianDate = toGregorian.ToGregorianDate(1402, 1, 1);
int gregorianMonth = toGregorian.GetGregorianMonth(1402, 1, 1);
int gregorianDay = toGregorian.GetGregorianDay(1402, 1, 1);

Console.WriteLine($"Gregorian Year: {gregorianYear}");
// Output: Gregorian Year: 2023

Console.WriteLine($"Gregorian Date: {gregorianDate}");
// Output: Gregorian Date: 2023-03-21

Console.WriteLine($"Gregorian Month: {gregorianMonth}");
// Output: Gregorian Month: 3

Console.WriteLine($"Gregorian Day: {gregorianDay}");
// Output: Gregorian Day: 21

Supported Platforms

• .NET 6.0
• .NET 7.0
• .NET 8.0
• .NET 9.0
• .NET 10.0

📚 API Reference

ShamsiDateFormatter

• Format(DateTime, ShamsiFormatStyle) - Format with predefined styles
• Format(DateTime, string) - Format with custom pattern (Persian digits)
• FormatWithEnglishDigits(DateTime, string) - Format with English digits
• FormatTime(DateTime, string) - Format time components only
• ConvertToPersianDigits(string) - Convert English to Persian digits

ShamsiDateParser

• Parse(string) - Parse Persian date string to DateTime
• TryParse(string, out DateTime) - Safe parsing with boolean result
• ParseAndValidate(string, ValidationMode?) - Parse with validation details
• IsValidShamsiDate(int year, int month, int day) - Validate date components

ShamsiCultureInfo

• Persian - Persian culture (fa-IR) with Persian digits and RTL support
• English - English culture (en-US) with English digits and transliterated names
• CreateCulture(string) - Create custom culture

ShamsiLocalizedFormatter

• Format(DateTime, string, ShamsiCultureInfo) - Culture-aware formatting

Extension Methods

• ToShamsiString(ShamsiFormatStyle, ShamsiCultureInfo?) - Convert to localized Shamsi string
• ToShamsiDate() - Convert to basic Shamsi date string
• ToShortShamsiDate() - Convert to short format
• ToLongShamsiDate() - Convert to long format with day name

Format Patterns

🏗️ Project Structure

PersianDate/
├── Core/                    # Core date conversion functionality
│   ├── PersianDateShamsi.cs    # Main Persian date conversion class
│   ├── ToGregorian.cs          # Gregorian conversion utilities
│   └── ToShamsi.cs            # Extension methods for conversion
├── Formatting/              # Enhanced formatting features
│   └── ShamsiDateFormatter.cs  # Advanced formatting with styles and patterns
├── Parsing/                 # Date parsing and validation
│   └── ShamsiDateParser.cs     # Parse Persian date strings with validation
├── Culture/                 # Localization and culture support
│   └── ShamsiCultureInfo.cs    # Persian and English culture definitions
├── Extensions/              # Extension methods and operations
│   ├── ShamsiCalendarExtensions.cs   # DateTime extension methods
│   └── ShamsiCalendarOperations.cs   # Advanced calendar operations
└── Utils/                   # Utility classes
    └── StringUtil.cs           # String manipulation utilities

Getting Started

1. Install .NET 10.0 SDK
2. Clone the repository:

   git clone https://github.com/hootanht/PersianDate.git
   

3. Navigate to the project directory:

   cd PersianDate
   

4. Restore dependencies:

   dotnet restore
   

5. Build the project:

   dotnet build
   

6. Run tests:

   dotnet test
   

Version History

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ by Hootan Hemmati