العمل مع التواريخ والوقت في Kotlin: من الألف إلى الياء — دليل شامل

مقدمة في العمل مع التواريخ والوقت في Kotlin

العمل مع التواريخ والوقت هو أحد أكثر المهام شيوعًا في التطوير الحديث. سواء كان ذلك لتسجيل الأحداث، حساب المواعيد النهائية، جدولة المهام، أو عرض واجهة المستخدم — لا يمكن الاستغناء عن التعامل الصحيح مع الطوابع الزمنية. في Kotlin، المتوافق تمامًا مع Java، المعيار الفعلي هو الحزمة java.time، التي تم تقديمها في Java 8. هذه الحزمة حلت محل java.util.Date و java.util.Calendar القديمتين، مقدمةً واجهة برمجة تطبيقات آمنة للخيوط، غير قابلة للتغيير، وبديهية.

في هذه المقالة، سنشرح جميع الجوانب الرئيسية للعمل مع التواريخ والوقت في Kotlin: من إنشاء الكائنات إلى تنسيقها، وتحليلها، وإجراء العمليات الحسابية. ستتعلم كيفية استخدام LocalDate، LocalTime، LocalDateTime، Instant، Duration و Period من خلال أمثلة عملية.

1. الفئات الأساسية للعمل مع التواريخ والوقت

تحتوي الحزمة java.time على عدة فئات رئيسية، كل منها يحل مشكلة محددة. دعنا نستعرضها بالتفصيل.

1.1 LocalDate — العمل مع التاريخ بدون وقت

تمثل الفئة LocalDate التاريخ (السنة، الشهر، اليوم) دون مراعاة الوقت والمنطقة الزمنية. مثالية لأعياد الميلاد، الأحداث التقويمية، والتواريخ غير المرتبطة بلحظة محددة.

import java.time.LocalDate\n\nfun main() {\n    // التاريخ الحالي\n    val today = LocalDate.now()\n    println("اليوم: $today") // 2025-04-05\n\n    // تاريخ محدد\n    val newYear = LocalDate.of(2025, 1, 1)\n    println("رأس السنة: $newYear")\n\n    // تحليل من سلسلة نصية\n    val parsedDate = LocalDate.parse("2025-12-31")\n    println("تاريخ محلل: $parsedDate")\n}

1.2 LocalTime — العمل مع الوقت بدون تاريخ

LocalTime يخزن الوقت فقط (الساعات، الدقائق، الثواني، النانو ثانية). وهو مفيد لتخزين وقت بدء يوم العمل، الجداول الزمنية، أو المؤقتات.

import java.time.LocalTime\n\nfun main() {\n    // الوقت الحالي\n    val now = LocalTime.now()\n    println("الآن: $now")\n\n    // وقت محدد\n    val meetingTime = LocalTime.of(14, 30, 0)\n    println("وقت الاجتماع: $meetingTime")\n\n    // تحليل\n    val parsedTime = LocalTime.parse("09:15:30")\n    println("وقت محلل: $parsedTime")\n}

1.3 LocalDateTime — دمج التاريخ والوقت

LocalDateTime يدمج LocalDate و LocalTime. هذه هي الفئة الأكثر استخدامًا لتخزين لحظة زمنية بدون منطقة زمنية.

import java.time.LocalDateTime\n\nfun main() {\n    // التاريخ والوقت الحاليين\n    val current = LocalDateTime.now()\n    println("الآن: $current")\n\n    // الإنشاء من المكونات\n    val specific = LocalDateTime.of(2025, 4, 5, 10, 30, 0)\n    println("لحظة محددة: $specific")\n\n    // دمج التاريخ والوقت\n    val date = LocalDate.of(2025, 12, 25)\n    val time = LocalTime.of(18, 0)\n    val christmas = LocalDateTime.of(date, time)\n    println("عيد الميلاد: $christmas")\n}

1.4 Instant — لحظة زمنية بتوقيت UTC

Instant يمثل نقطة على الخط الزمني بتنسيق Unix timestamp (عدد الثواني والنانو ثانية منذ 1 يناير 1970). لا غنى عنه لتخزين السجلات، العمل مع قواعد البيانات، وتبادل البيانات بين الأنظمة.

import java.time.Instant\n\nfun main() {\n    // اللحظة الحالية بتوقيت UTC\n    val now = Instant.now()\n    println("الآن (UTC): $now")\n\n    // من Unix timestamp\n    val fromEpoch = Instant.ofEpochSecond(1_700_000_000)\n    println("من timestamp: $fromEpoch")\n\n    // التحويل إلى ملي ثانية\n    val millis = now.toEpochMilli()\n    println("الملي ثانية: $millis")\n}

2. تنسيق وتحليل التواريخ والوقت

لتحويل التواريخ إلى سلاسل نصية