LocalDate، LocalTime اور LocalDateTime: یہ کیا ہیں، تاریخ کے ساتھ کام

LocalDate، LocalTime اور LocalDateTime کیا ہیں؟

LocalDate — ایک کلاس جو وقت اور ٹائم زون کی معلومات کے بغیر سال-مہینہ-دن کی شکل میں تاریخ کی نمائندگی کرتی ہے۔ یہ سالگرہ، واقعات کی تاریخیں یا میعاد ختم ہونے کی تاریخیں جیسے ڈیٹا ذخیرہ کرنے کے لیے استعمال ہوتی ہے۔

LocalDate -999999999 سے +999999999 تک کی حد میں سال، 1 سے 12 تک مہینہ اور لیپ سال کو مدنظر رکھتے ہوئے مہینے کا دن ذخیرہ کرتا ہے۔ کلاس مکمل طور پر immutable ہے — کوئی بھی عمل نیا آبجیکٹ لوٹاتا ہے۔

LocalTime دن کے وقت کی نمائندگی کرتا ہے: گھنٹے، منٹ، سیکنڈ اور نینو سیکنڈ۔ زیادہ سے زیادہ درستگی ایک نینو سیکنڈ تک ہے۔ LocalTime میں تاریخ یا ٹائم زون کی کوئی معلومات نہیں ہوتی، جو اسے دکان کے کھلنے کے اوقات یا عمل کی مدت ذخیرہ کرنے کے لیے آسان بناتا ہے۔

LocalDateTime LocalDate اور LocalTime کو ایک آبجیکٹ میں یکجا کرتا ہے۔ یہ سب سے زیادہ استعمال ہونے والی قسم ہے جب آپ کو تاریخ اور وقت دونوں ذخیرہ کرنے کی ضرورت ہوتی ہے، لیکن ٹائم زون کی پابندی کی ضرورت نہیں ہوتی۔ مثال کے طور پر، مقامی فارمیٹ میں کنسرٹ کی تاریخ اور وقت۔

Oracle Java دستاویزات (2024) کے مطابق، تینوں کلاسیں Joda-Time لائبریری کے خیالات پر مبنی ہیں، لیکن بہتر فن تعمیر اور معیاری لائبریری میں مکمل انضمام کے ساتھ۔

java.time پیکیج کیسے کام کرتا ہے؟

java.time پیکیج Java 8 میں پرانی Date، Calendar اور SimpleDateFormat کلاسز کے متبادل کے طور پر متعارف ہوا۔ اس کا فن تعمیر immutable آبجیکٹس اور fluent انٹرفیس کے اصولوں پر بنایا گیا ہے۔

ایک اہم خصوصیت — تمام اہم کلاسیں value-based ہیں۔ اس کا مطلب ہے کہ ان کی مثالوں کا موازنہ قدر سے کیا جاتا ہے، حوالہ سے نہیں، اور انہیں وراثت میں نہیں لیا جا سکتا۔ دو آبجیکٹس کا موازنہ کرنے کے لیے == آپریٹر نہیں، بلکہ equals طریقہ استعمال کریں۔

پیکیج کئی زمروں میں تقسیم ہے۔ ٹائم زون کے بغیر اقسام — LocalDate، LocalTime، LocalDateTime — مقامی تاریخوں اور اوقات کے لیے استعمال ہوتی ہیں۔ ٹائم زون والی اقسام — ZonedDateTime، OffsetDateTime، OffsetTime — آفسیٹ یا زون کی معلومات شامل کرتی ہیں۔ فوری اقسام — Instant — UTC میں وقت کی لکیر پر ایک نقطہ کی نمائندگی کرتی ہیں۔

یہ تقسیم پرانی API میں موجود ایک مسئلہ حل کرتی ہے: ڈیولپر کبھی نہیں جانتا تھا کہ Date آبجیکٹ میں ٹائم زون کی معلومات ہے یا نہیں۔ java.time میں، ہر قسم واضح طور پر اپنے معنی کا اعلان کرتی ہے۔

LocalDate: تاریخ کے ساتھ کام

LocalDate کلاس تاریخیں بنانے، پڑھنے اور تبدیل کرنے کے لیے بہت سے طریقے فراہم کرتی ہے۔ موجودہ تاریخ جامد طریقہ now() کے ذریعے حاصل کی جا سکتی ہے۔ ایک مخصوص تاریخ — of(int year, int month, int dayOfMonth) طریقہ کے ذریعے۔

تاریخ کے اجزاء پڑھنے کے لیے گیٹرز استعمال کیے جاتے ہیں: getYear()، getMonthValue()، getDayOfMonth()، getDayOfWeek()، getDayOfYear()۔ getMonth() طریقہ Month enum لوٹاتا ہے، اور getDayOfWeek() DayOfWeek enum لوٹاتا ہے۔

LocalDate تاریخ کی جانچ کو سپورٹ کرتا ہے۔ isBefore()، isAfter() اور isEqual() طریقے تاریخوں کا موازنہ کرنے کی اجازت دیتے ہیں۔ isLeapYear() طریقہ چیک کرتا ہے کہ آیا سال لیپ سال ہے۔ lengthOfMonth() طریقہ مہینے میں دنوں کی تعداد لوٹاتا ہے، اور lengthOfYear() سال میں دنوں کی تعداد لوٹاتا ہے۔

تبدیلی کے لیے withYear()، withMonth()، withDayOfMonth() طریقے استعمال کیے جاتے ہیں، جو تبدیل شدہ جز کے ساتھ نیا آبجیکٹ لوٹاتے ہیں۔ plusDays()، minusMonths() اور اسی طرح کے طریقے تاریخ کا ریاضی انجام دیتے ہیں۔

LocalTime: وقت کے ساتھ کام

LocalTime نینو سیکنڈ درستگی کے ساتھ دن کے وقت کی نمائندگی کرتا ہے۔ معیاری فارمیٹ ISO-8601 (HH:mm:ss.nnnnnnnnn) ہے۔ کم سے کم قیمت 00:00 ہے، زیادہ سے زیادہ 23:59:59.999999999 ہے۔

LocalTime آبجیکٹ now() کے ساتھ موجودہ وقت کے لیے، of(int hour, int minute)، of(int hour, int minute, int second) یا of(int hour, int minute, int second, int nanoOfSecond) کے ساتھ بنایا جا سکتا ہے۔ parse(CharSequence text) طریقہ ISO-8601 فارمیٹ میں سٹرنگ کا تجزیہ کرتا ہے۔

گیٹرز میں getHour()، getMinute()، getSecond()، getNano() شامل ہیں۔ toSecondOfDay() طریقہ دن کے آغاز سے سیکنڈز کی تعداد لوٹاتا ہے، اور toNanoOfDay() نینو سیکنڈ لوٹاتا ہے۔ یہ ایک دن کے اندر مدت کا حساب لگانے کے لیے آسان ہے۔

LocalTime LocalDate جیسے ہی موازنہ اور تبدیلی کے عمل کو سپورٹ کرتا ہے: plusHours()، minusMinutes()، withHour()، withMinute()۔ isBefore() اور isAfter() طریقے اس بات کو مدنظر رکھتے ہوئے کام کرتے ہیں کہ وقت ایک دن کے اندر چکری ہے۔

LocalDateTime: تاریخ اور وقت کا مجموعہ

LocalDateTime ایک کلاس میں LocalDate اور LocalTime کی صلاحیتوں کو یکجا کرتا ہے۔ یہ تاریخ اور وقت دونوں ذخیرہ کرتا ہے، لیکن ٹائم زون کے بغیر۔ یہ سب سے لچکدار مقامی قسم ہے، لیکن تقسیم شدہ نظاموں میں استعمال کرتے ہوئے احتیاط کی ضرورت ہے۔

LocalDateTime جامد طریقوں now()، of(LocalDate date, LocalTime time)، of(int year, Month month, int dayOfMonth, int hour, int minute) اور ان کے اوورلوڈز کے ذریعے بنایا جا سکتا ہے۔ LocalDate اور LocalTime کو atTime() طریقہ کے ذریعے بھی ملایا جا سکتا ہے۔

LocalDateTime متعلقہ گیٹرز کے ذریعے تمام تاریخ اور وقت کے فیلڈز تک رسائی فراہم کرتا ہے: toLocalDate() اور toLocalTime() انفرادی اجزاء لوٹاتے ہیں۔ truncatedTo(TemporalUnit unit) طریقہ وقت کو مخصوص درستگی تک گول کرنے کی اجازت دیتا ہے — مثال کے طور پر، منٹوں تک۔

ٹائم زون میں تبدیل کرنے کے لیے atZone(ZoneId zone) طریقہ استعمال کیا جاتا ہے، جو ZonedDateTime لوٹاتا ہے۔ LocalDateTime میں ٹائم زون شامل کرنے کا یہ واحد طریقہ ہے۔

تاریخ اور وقت کے آبجیکٹ کیسے بنائیں؟

تینوں کلاسیں جامد فیکٹری طریقوں کے ذریعے متحد تخلیق پیٹرن استعمال کرتی ہیں۔ کلاس کنسٹرکٹرز کو private قرار دیا گیا ہے — new استعمال کرکے براہ راست آبجیکٹ نہیں بنایا جا سکتا۔

اہم تخلیق طریقے:

• now() — سسٹم کلاک سے موجودہ تاریخ/وقت
• of(...) — اجزاء سے (سال، مہینہ، دن، وغیرہ)
• parse(String) — ISO-8601 فارمیٹ میں سٹرنگ سے
• from(TemporalAccessor) — کسی دوسرے وقتی آبجیکٹ سے

of طریقہ کے بہت سے اوورلوڈز ہیں۔ LocalDate کے لیے سال، مہینہ اور دن درکار ہیں۔ LocalTime کے لیے — گھنٹے اور منٹ (اختیاری طور پر سیکنڈ اور نینو سیکنڈ)۔ LocalDateTime کے لیے — سال، مہینہ، دن، گھنٹے، منٹ۔ مہینہ int (1-12) یا Month enum کے طور پر پاس کیا جا سکتا ہے۔

val today = LocalDate.now()
val specificDate = LocalDate.of(2026, Month.JULY, 21)
val parsedDate = LocalDate.parse("2026-07-21")

val currentTime = LocalTime.now()
val lunchTime = LocalTime.of(13, 30, 0)
val parsedTime = LocalTime.parse("13:30:00")

val now = LocalDateTime.now()
val meeting = LocalDateTime.of(2026, 7, 21, 15, 0)

اقسام کے درمیان تبدیلی

java.time کلاسیں ایک دوسرے میں آسان تبدیلی کے لیے ڈیزائن کی گئی ہیں۔ LocalDate atTime(LocalTime) یا atStartOfDay() طریقہ کے ذریعے LocalDateTime میں تبدیل کیا جا سکتا ہے۔ LocalTime — atDate(LocalDate) کے ذریعے۔

LocalDateTime toLocalDate() کے ذریعے LocalDate میں اور toLocalTime() کے ذریعے LocalTime میں واپس تبدیل کیا جا سکتا ہے۔ ZonedDateTime میں تبدیل کرنے کے لیے atZone(ZoneId) طریقہ استعمال کیا جاتا ہے۔

java.util.Date میں تبدیلی (پرانی کوڈ کے ساتھ مطابقت کے لیے) Instant اور ٹائم زون کے ذریعے ایک درمیانی مرحلہ درکار ہے۔ Baeldung (2024) کے مطابق، یہ عمل Date.from(instant) کے ذریعے انجام دیا جاتا ہے۔

val date = LocalDate.of(2026, 7, 21)
val dateTime = date.atTime(LocalTime.of(10, 30))

val time = LocalTime.of(14, 0)
val dateTimeFromTime = time.atDate(date)

val extractedDate = dateTime.toLocalDate()
val extractedTime = dateTime.toLocalTime()

val zoned = dateTime.atZone(ZoneId.of("Europe/Moscow"))

فارمیٹنگ اور تجزیہ

فارمیٹنگ اور تجزیہ کے لیے DateTimeFormatter کلاس استعمال کی جاتی ہے۔ یہ مستقلات (ISO_LOCAL_DATE، ISO_LOCAL_TIME، ISO_LOCAL_DATE_TIME) کے ذریعے پہلے سے طے شدہ فارمیٹس اور پیٹرن سٹرنگز کے ذریعے حسب ضرورت فارمیٹس بنانے کی صلاحیت فراہم کرتی ہے۔

فارمیٹنگ پیٹرن علامات استعمال کرتے ہیں: yyyy — سال، MM — مہینہ (دو ہندسے)، dd — دن، HH — گھنٹہ (0-23)، mm — منٹ، ss — سیکنڈ۔ format() طریقہ تاریخ-وقت آبجیکٹ پر یا DateTimeFormatter کے ذریعے بلایا جاتا ہے۔

DateTimeFormatter جامد طریقوں ofLocalizedDate(FormatStyle)، ofLocalizedTime(FormatStyle) اور ofLocalizedDateTime(FormatStyle) کے ذریعے مقامی کاری کو بھی سپورٹ کرتا ہے۔ دستیاب اسٹائل SHORT، MEDIUM، LONG اور FULL ہیں۔

val formatter = DateTimeFormatter.ofPattern("dd.MM.yyyy HH:mm")
val formatted = LocalDateTime.now().format(formatter)

val parsed = LocalDate.parse(
    "21.07.2026",
    DateTimeFormatter.ofPattern("dd.MM.yyyy")
)

تاریخ-وقت آبجیکٹس کا موازنہ

تینوں کلاسیں Comparable انٹرفیس کو لاگو کرتی ہیں، جو انہیں قدرتی طور پر موازنہ کرنے کی اجازت دیتی ہیں۔ compareTo() طریقہ ترتیب کے مطابق منفی، صفر یا مثبت عدد لوٹاتا ہے۔ isBefore()، isAfter() اور isEqual() طریقے بولین لوٹاتے ہیں۔

LocalDate کے لیے، موازنہ تاریخ وار ہے — پہلے کی تاریخ چھوٹی سمجھی جاتی ہے۔ LocalTime کے لیے — دن کے وقت کے مطابق۔ LocalDateTime کے لیے — پہلے تاریخ کے مطابق، پھر وقت کے مطابق۔ تمام موازنے لیپ سالوں اور مہینوں میں دنوں کی تعداد کو صحیح طور پر مدنظر رکھتے ہیں۔

پرانی API سے ایک اہم فرق: LocalDate، LocalTime اور LocalDateTime کے لیے equals() اقدار کا موازنہ کرتا ہے، حوالوں کا نہیں۔ اس کا مطلب ہے کہ ایک جیسے فیلڈز والے دو آبجیکٹ برابر ہوں گے، چاہے وہ مختلف مثالیں ہی کیوں نہ ہوں۔

val d1 = LocalDate.of(2026, 7, 21)
val d2 = LocalDate.of(2026, 12, 25)

if (d1.isBefore(d2)) {
    Log.d("تاریخ", "d1، d2 سے پہلے")
}

val sortedDates = listOf(d2, d1).sorted()

تاریخ اور وقت کا ریاضی

تینوں کلاسیں plus اور minus طریقوں کے ذریعے ریاضی کے عمل کو سپورٹ کرتی ہیں۔ LocalDate کے لیے plusDays()، plusWeeks()، plusMonths()، plusYears() اور متعلقہ minus طریقے دستیاب ہیں۔ LocalTime plusHours()، plusMinutes()، plusSeconds()، plusNanos() کو سپورٹ کرتا ہے۔

LocalDateTime دونوں اقسام سے تمام ریاضی کے عمل وراثت میں لیتا ہے۔ LocalDate کی ایک قابل ذکر خصوصیت: ایک مہینہ شامل کرنے پر، نتائج مختلف مہینوں کی لمبائی کو صحیح طریقے سے ہینڈل کرتے ہیں۔ مثال کے طور پر، 31 جنوری + 1 مہینہ = 28 (لیپ سال میں 29) فروری۔

مزید پیچیدہ عمل کے لیے Period کلاس (تاریخوں کے لیے) اور Duration کلاس (وقت کے لیے) موجود ہیں۔ plus(TemporalAmount) اور minus(TemporalAmount) طریقے یہ آبجیکٹ قبول کرتے ہیں۔

val today = LocalDate.now()
val nextWeek = today.plusDays(7)
val nextMonth = today.plusMonths(1)
val lastYear = today.minusYears(1)

val now = LocalTime.now()
val inTwoHours = now.plusHours(2)
val halfHourAgo = now.minusMinutes(30)

Kotlin میں کوڈ کی مثالیں

ایک عملی مثال دیکھتے ہیں: کام کی شفٹ ٹریکنگ ایپلی کیشن۔ ہمیں شفٹ کی مدت کا حساب لگانا اور یہ تعین کرنا ہے کہ آیا یہ رات کے وقت آتی ہے۔ ہم شروع اور اختتام کے اوقات کے لیے LocalTime، تاریخ کے لیے LocalDate اور آدھی رات پار کرنے والی شفٹوں کے حساب کے لیے LocalDateTime استعمال کرتے ہیں۔

data class Shift(
    val startTime: LocalTime,
    val endTime: LocalTime,
    val date: LocalDate
) {
    fun isOvernight(): Boolean = endTime.isBefore(startTime)

    fun durationInMinutes(): Long {
        val start = LocalDateTime.of(date, startTime)
        val end = LocalDateTime.of(
            if (isOvernight()) date.plusDays(1) else date,
            endTime
        )
        return Duration.between(start, end).toMinutes()
    }
}

دوسری مثال — صارف کی عمر کا حساب۔ ہم پیدائش کی تاریخ کے لیے LocalDate استعمال کرتے ہیں اور پیدائش کے دن اور مہینے کو مدنظر رکھتے ہوئے موجودہ تاریخ سے موازنہ کرتے ہیں۔

fun calculateAge(birthDate: LocalDate): Int {
    val today = LocalDate.now()
    val period = Period.between(birthDate, today)
    return period.years
}

تیسری مثال — اطلاعات کے ساتھ کام۔ LocalDateTime یاد دہانیوں کے شیڈولنگ کے لیے استعمال ہوتا ہے۔ ہم چیک کرتے ہیں کہ آیا طے شدہ وقت آ گیا ہے۔

data class Reminder(
    val id: Long,
    val scheduledAt: LocalDateTime
) {
    fun isDue(): Boolean =
        LocalDateTime.now().isAfter(scheduledAt)
}

Android سپورٹ: API لیول اور Desugaring

java.time کے لیے بلٹ ان سپورٹ Android پر API 26 (Android 8.0 Oreo) سے ظاہر ہوئی۔ پرانے Android ورژن والے آلات کے لیے، desugaring استعمال کرنا ضروری ہے — ایک میکانزم جو پرانے ورژنز میں نئی Java API کے لیے سپورٹ شامل کرتا ہے۔

Android Gradle Plugin میں Desugaring build.gradle میں compileOptions کے ذریعے کنفیگر کیا جاتا ہے۔ بس isCoreLibraryDesugaringEnabled = true سیٹ کریں اور desugar_jdk_libs لائبریری شامل کریں۔ اس کے بعد، java.time 14 سے شروع ہونے والے تمام API لیولز کے لیے دستیاب ہو جاتا ہے۔

ان پروجیکٹس کے لیے جو desugaring استعمال نہیں کر سکتے (مثال کے طور پر، AGP 4.0 سے نیچے والے پرانے پروجیکٹس)، ThreeTenABP لائبریری موجود ہے — java.time کا بیک پورٹ۔ یہ وہی کلاسیں (LocalDate، LocalTime، LocalDateTime) فراہم کرتی ہے، لیکن org.threeten.bp پیکیج میں۔

@Suppress("UnstableApiUsage")
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    "coreLibraryDesugaring"("com.android.tools:desugar_jdk_libs:2.1.4")
}

عام غلطیاں اور ان سے کیسے بچیں

پہلی عام غلطی — ٹائم زون کو مدنظر رکھے بغیر تقسیم شدہ نظاموں میں LocalDateTime استعمال کرنا۔ اگر سرور Europe/Moscow میں ہے اور کلائنٹ Asia/Tokyo میں، LocalDateTime کی مختلف تشریح کی جائے گی۔ حل: عالمی ڈیٹا کے لیے Instant یا ZonedDateTime استعمال کریں۔

دوسری غلطی — غلط سٹرنگ تجزیہ۔ ڈیفالٹ طور پر، LocalDate.parse() ISO-8601 فارمیٹ (yyyy-MM-dd) کی توقع کرتا ہے۔ اگر سٹرنگ کسی اور فارمیٹ میں ہے، تو آپ کو واضح طور پر DateTimeFormatter پاس کرنا ہوگا۔ آپ کو DateTimeParseException کو بھی ہینڈل کرنا چاہیے تاکہ غلط ان پٹ پر ایپلیکیشن کریش نہ ہو۔

تیسری غلطی — null حفاظت کو نظر انداز کرنا۔ LocalDate، LocalTime اور LocalDateTime وہ آبجیکٹ ہیں جو null ہو سکتے ہیں۔ Kotlin میں، واضح جانچ یا Elvis آپریٹر کے ساتھ nullable اقسام استعمال کرنے کی سفارش کی جاتی ہے۔ Java میں — طریقے بلانے سے پہلے null چیک کریں۔

چوتھی غلطی — LocalDateTime اور ZonedDateTime کے درمیان الجھن۔ LocalDateTime میں ٹائم زون کی کوئی معلومات نہیں ہوتی۔ اگر آپ کو وقت میں ایک مطلق لمحہ پہنچانے کی ضرورت ہے — زونل اقسام استعمال کریں۔ اگر مقامی وقت کافی ہے — مقامی اقسام استعمال کریں۔