Parsidate -کامل ترین کتابخانه کار با تاریخ و ساعت شمسی در اکوسیستم Rust

اگر تاکنون با زبان Rust کار کرده باشید و خواسته باشید تاریخ‌های شمسی (Jalali/Shamsi) را مدیریت کنید، احتمالاً متوجه شده‌اید که امکانات استاندارد Rust و حتی کرِیت‌های معروف مانند chrono بیشتر بر روی تاریخ میلادی تمرکز دارند. اینجاست که به کتابخانه ParsiDate به عنوان یک راه‌حل جامع برای مدیریت تاریخ و زمان فارسی نیاز پیدا میکنید.

ParsiDate یک کتابخانه Rust است که امکانات گسترده‌ای برای کار با تاریخ و زمان شمسی ارائه می‌دهد. این کتابخانه نه تنها می‌تواند تاریخ‌های ساده را مدیریت کند، بلکه تبدیل بین تاریخ میلادی و شمسی، محاسبات زمانی، اعتبارسنجی و پشتیبانی از زمان‌های با منطقه زمانی را نیز فراهم می‌کند.

ویژگی‌های کلیدی ParsiDate

۱. سه نوع داده اصلی

کتابخانه ParsiDate سه نوع داده اصلی دارد که هرکدام کاربرد خاص خود را دارند:

1. ParsiDate: نمایشی ساده از تاریخ (سال، ماه، روز) بدون اطلاعات زمانی.

2. ParsiDateTime: نمایشی از تاریخ و زمان (ساعت، دقیقه، ثانیه) بدون توجه به منطقه زمانی.

3. ZonedParsiDateTime: تاریخ و زمان با توجه به منطقه زمانی، شامل پشتیبانی از تغییر ساعت تابستانی و آفست‌ها. این ویژگی نیاز به فعال‌سازی timezone feature دارد.

۲. تبدیل و تعامل با chrono

یکی از نقاط قوت اصلی ParsiDate امکان تبدیل آسان بین تاریخ‌های میلادی (NaiveDate, NaiveDateTime) و تاریخ‌های شمسی است. این بدان معنی است که شما می‌توانید داده‌های موجود خود را بدون دردسر به تاریخ شمسی تبدیل کنید و بالعکس.

use parsidate::ParsiDate;
use chrono::NaiveDate;

let g_date = NaiveDate::from_ymd_opt(2024, 7, 23).unwrap();
let pd = ParsiDate::from_gregorian(g_date).unwrap();
assert_eq!(pd.to_gregorian().unwrap(), g_date);

۳. اعتبارسنجی و ایمنی

تمام تاریخ‌ها و زمان‌ها در ParsiDate به صورت دقیق اعتبارسنجی می‌شوند. برای مثال، تلاش برای ایجاد یک روز نامعتبر مانند ۳۰ اسفند در سال غیرکبیسه، خطا ایجاد می‌کند.

assert!(ParsiDate::new(1404, 12, 30).is_err()); // روز نامعتبر

۴. فرمت‌بندی و پارسینگ پیشرفته

ParsiDate امکان نمایش و تبدیل تاریخ‌ها و زمان‌ها با الگوهای مشابه strftime را فراهم می‌کند. شما می‌توانید از نام‌های فارسی ماه‌ها، روزهای هفته، فصل‌ها و تمام اجزای تاریخ و زمان استفاده کنید.

let pd = ParsiDate::new(1403, 5, 2).unwrap();
assert_eq!(pd.format("%d %B %Y"), "02 مرداد 1403");

همچنین، پارس کردن رشته‌ها به تاریخ شمسی با فرمت‌های مختلف به آسانی ممکن است:

let parsed = ParsiDate::parse("1403/05/02", "%Y/%m/%d").unwrap();
assert_eq!(parsed, pd);

۵. محاسبات زمانی (Arithmetic)

ParsiDate امکان جمع و تفریق روزها، ماه‌ها و سال‌ها را با در نظر گرفتن طول ماه‌ها و سال‌های کبیسه فراهم می‌کند. همچنین با استفاده از chrono::Duration می‌توان محاسبات دقیق زمان را انجام داد.

let next_day = pd.add_days(1).unwrap(); // اضافه کردن یک روز

۶. اطلاعات کامل تاریخ و زمان

کتابخانه امکانات متنوعی برای استخراج اطلاعات از تاریخ‌ها فراهم کرده است:

• روز هفته شمسی

• روز سال

• فصل

• شماره هفته

• اجزای تاریخ و زمان (سال، ماه، روز، ساعت، دقیقه، ثانیه)

همچنین امکان دریافت اولین و آخرین روز ماه، سال و فصل وجود دارد.

۷. پشتیبانی از زمان واقعی سیستم

• ParsiDate::today() – دریافت تاریخ امروز شمسی

• ParsiDateTime::now() – دریافت تاریخ و زمان کنونی

• ZonedParsiDateTime::now(tz) – دریافت زمان کنونی با منطقه زمانی

use parsidate::ParsiDateTime;
let now = ParsiDateTime::now();
println!("Current ParsiDateTime: {}", now);

۸. پشتیبانی از سریال‌سازی (Serde)

با فعال کردن serde feature، تمامی نوع‌های تاریخ و زمان می‌توانند سریال‌سازی و دی‌سریال‌سازی شوند که برای ذخیره‌سازی یا ارسال داده‌ها بسیار مفید است.

نصب و فعال‌سازی امکانات

برای اضافه کردن ParsiDate به پروژه Rust کافیست Cargo.toml را به شکل زیر تنظیم کنید:

[dependencies]parsidate = "1.7.1"chrono = "0.4"

فعال‌سازی ویژگی‌های اضافی:

• serde – سریال‌سازی و دی‌سریال‌سازی

• timezone – پشتیبانی از ZonedParsiDateTime و مناطق زمانی

مثال:

parsidate = { version = "1.7.1", features = ["serde", "timezone"] }
chrono-tz = "0.8"  # مورد نیاز برای timezone

مثال‌های کاربردی

ایجاد و مدیریت تاریخ شمسی

use parsidate::ParsiDate;

let pd = ParsiDate::new(1403, 5, 2).unwrap();
println!("تاریخ شمسی: {}", pd.format("%d %B %Y"));

محاسبات زمانی

let tomorrow = pd.add_days(1).unwrap();
println!("فردا: {}", tomorrow);

مدیریت زمان با منطقه زمانی

#[cfg(feature = "timezone")]
{
    use parsidate::ZonedParsiDateTime;
    use chrono_tz::Asia::Tehran;

    let tehran_now = ZonedParsiDateTime::now(Tehran);
    println!("زمان فعلی تهران: {}", tehran_now);
}

دریافت فصل و محدوده آن

use parsidate::{ParsiDate, Season};

let winter_date = ParsiDate::new(1403, 11, 10).unwrap();
assert_eq!(winter_date.season().unwrap(), Season::Zemestan);
let end_of_winter = winter_date.end_of_season().unwrap();
println!("پایان زمستان: {}", end_of_winter);

جمع‌بندی

کتابخانه ParsiDate یک ابزار کامل و حرفه‌ای برای کار با تاریخ و زمان شمسی در Rust است. این کتابخانه برای برنامه‌نویسانی که می‌خواهند:

• تاریخ شمسی را با دقت و اعتبار بالا مدیریت کنند،

• محاسبات زمانی پیچیده را انجام دهند،

• و با تاریخ میلادی و مناطق زمانی تعامل داشته باشند،

یک راه‌حل بسیار مطمئن و کاربردی محسوب می‌شود.

با توجه به پشتیبانی از serde، امکانات فرمت‌بندی، پارسینگ، و محاسبات دقیق زمان، ParsiDate می‌تواند هسته‌ی سیستم‌های تاریخ و زمان فارسی را در پروژه‌های Rust شما تشکیل دهد.

دسترسی

صفحه ی parsidate در crates.io :

https://crates.io/crates/parsidate

صفحه ی parsidate در lib.rs:

https://lib.rs/crates/parsidate

صفحه ی مستندات parsidate در docs.rs :

https://docs.rs/parsidate

WiKi:

https://github.com/parsicore/ParsiDate/wiki

آخرین تغییرات:

https://github.com/parsicore/ParsiDate/blob/master/CHANGELOG.md