مكتبة chrono في Rust: الدليل الكامل للتعامل مع التواريخ والأوقات

1. ما هي مكتبة chrono ولماذا تحتاجها؟

مكتبة chrono هي المعيار الفعلي للتعامل مع التواريخ والأوقات في نظام Rust البيئي. توفر واجهة برمجة تطبيقات قوية وآمنة من حيث الأنواع وسهلة الاستخدام لتحليل النصوص، والتنسيق، والعمليات الحسابية، والتلاعب بالطوابع الزمنية. على عكس المكتبة القياسية في Rust التي تقدم فقط إمكانيات أساسية عبر std::time (للعمل مع المدد والوقت النظامي)، تغطي chrono جميع احتياجات المطور تقريبًا: من التعامل مع المناطق الزمنية إلى الحسابات التقويمية المعقدة.

لماذا تحتاجها؟ إذا كنت تكتب تطبيقًا يجب أن يعالج تواريخ الميلاد، أو يسجل الأحداث بدقة نانو ثانية، أو يبني جداول زمنية، أو يعمل مع مناطق زمنية دولية — فلا غنى عن chrono. تدعم المكتبة صيغ ISO 8601 و RFC 2822 و RFC 3339، كما تسمح بإنشاء أدوات تنسيق مخصصة. بفضل نظام الأنواع الصارم في Rust، تساعدك chrono على تجنب الأخطاء المتعلقة بالتواريخ غير الصالحة (مثل 30 فبراير) أو الخلط بين UTC والتوقيت المحلي.

المكتبة مدعومة بنشاط من المجتمع، ولها توثيق ممتاز، وتُستخدم في آلاف المشاريع بما في ذلك المشاريع المعروفة مثل tokio و actix-web و diesel. الإصدار 0.4.x مستقر ويوصى باستخدامه في بيئات الإنتاج.

2. التثبيت

لإضافة chrono إلى مشروعك في Rust، استخدم مدير الحزم Cargo. نفّذ الأمر التالي في الطرفية داخل المجلد الرئيسي للمشروع:

cargo add chrono

أو أضف التبعية يدويًا إلى ملف Cargo.toml:

[dependencies]
chrono = "0.4"

بعد ذلك، نفّذ cargo build لتحميل المكتبة وتبعياتها. للعمل مع المناطق الزمنية (مثل تحليل أسماء المدن)، قد تحتاج إلى تفعيل الخاصية serde أو clock:

[dependencies]
chrono = { version = "0.4", features = ["serde"] }

3. البداية السريعة — مثال عملي بسيط

أنشئ ملفًا باسم main.rs والصق الكود التالي:

use chrono::{Local, Utc, DateTime, Duration};

fn main() {
    // الوقت الحالي في UTC
    let utc_now: DateTime = Utc::now();
    println!("الوقت الحالي UTC: {}", utc_now);

    // الوقت المحلي الحالي
    let local_now: DateTime = Local::now();
    println!("الوقت المحلي الحالي: {}", local_now);

    // تنسيق التاريخ
    println!("التاريخ المنسق: {}", local_now.format("%Y-%m-%d %H:%M:%S"));

    // العمليات الحسابية: إضافة يومين
    let future = utc_now + Duration::days(2);
    println!("بعد يومين (UTC): {}", future);
}

شغّل البرنامج باستخدام الأمر cargo run. سترى الوقت الحالي في UTC، والوقت المحلي، وسلسلة نصية منسقة، والتاريخ بعد يومين.

4. أهم الدوال والأنواع

فيما يلي 8 دوال وأنواع رئيسية من مكتبة chrono. لكل منها التوقيع والوصف ومثال كود.

4.1. `Utc::now()`

التوقيع: pub fn now() -> DateTime<Utc>

الوصف: تُرجع اللحظة الزمنية الحالية في المنطقة الزمنية UTC. هذه هي الطريقة الأكثر أمانًا للحصول على طابع زمني لأنها لا تعتمد على إعدادات المنطقة الزمنية للنظام.

use chrono::Utc;

fn main() {
    let now = Utc::now();
    println!("الوقت الحالي في UTC: {}", now);
    // الإخراج: 2025-03-15 14:30:00.123456 UTC
}