تجزیه و قالب‌بندی

کلاس‌های مبتنی بر Temporal در Date-Time API متدهای parse() برای پارس کردن رشته‌ای حاوی اطلاعات تاریخ و زمان دارند. این کلاس‌ها همچنین متدهای format() برای فرمت‌بندی اشیاء مبتنی بر Temporal جهت نمایش دارند. در هر دو مورد فرآیند مشابه است: یک الگو (Pattern) به DateTimeFormatter ارائه می‌دهید تا شیء formatter ساخته شود. سپس این formatter به متد parse() یا format() ارسال می‌شود.

کلاس DateTimeFormatter فرمت‌بند‌های ازپیش‌تعریف‌شده‌ی متعددی ارائه می‌دهد یا می‌توانید فرمت‌بند خودتان را تعریف کنید.

متدهای parse() و format() در صورت بروز مشکل در فرآیند تبدیل، Exception تولید می‌کنند. بنابراین کد parse شما باید خطای DateTimeParseException و کد format شما باید خطای DateTimeException را مدیریت کند. برای اطلاعات بیشتر درباره‌ی مدیریت Exception، بخش گرفتن و مدیریت Exceptionها را ببینید.

کلاس DateTimeFormatter هم تغییرناپذیر (Immutable) و هم Thread-Safe است و می‌تواند (و باید) در صورت لزوم به یک ثابت Static اختصاص داده شود.

نکته‌ی نسخه: اشیاء تاریخ-زمان java.time را می‌توان مستقیماً با java.util.Formatter و String.format() با استفاده از فرمت‌بندی الگویی آشنا — مشابه آنچه در کلاس‌های قدیمی java.util.Date و java.util.Calendar استفاده می‌شد — به کار برد.

پارس کردن (Parsing)

متد parse(CharSequence) با یک پارامتر در کلاس LocalDate از فرمت‌بند ISO_LOCAL_DATE استفاده می‌کند. برای مشخص کردن فرمت‌بند دیگر، می‌توانید از متد parse(CharSequence, DateTimeFormatter) با دو پارامتر استفاده کنید. مثال زیر از فرمت‌بند ازپیش‌تعریف‌شده‌ی BASIC_ISO_DATE استفاده می‌کند که قالب 19590709 را برای ۹ ژوئیه ۱۹۵۹ به کار می‌برد:

String in = ...;
LocalDate date = LocalDate.parse(in, DateTimeFormatter.BASIC_ISO_DATE);

همچنین می‌توانید فرمت‌بند را با الگوی خودتان تعریف کنید. کد زیر فرمت‌بندی با الگوی MMM d yyyy می‌سازد. این الگو سه کاراکتر برای ماه، یک رقم برای روز و چهار رقم برای سال مشخص می‌کند. فرمت‌بند ساخته‌شده با این الگو رشته‌هایی مانند «Jan 3 2003» یا «Mar 23 1994» را تشخیص می‌دهد. اما اگر الگو را MMM dd yyyy (با دو رقم برای روز) تعریف کنید، همیشه باید از دو رقم استفاده کنید و روزهای یک‌رقمی را با صفر پر کنید: «Jun 03 2003».

String input = ...;
try {
    DateTimeFormatter formatter =
                      DateTimeFormatter.ofPattern("MMM d yyyy");
    LocalDate date = LocalDate.parse(input, formatter);
    System.out.printf("%s%n", date);
}
catch (DateTimeParseException exc) {
    System.out.printf("%s is not parsable!%n", input);
    throw exc;      // پرتاب مجدد Exception
}
// 'date' با موفقیت پارس شده است

مستندات کلاس DateTimeFormatter فهرست کامل نمادها را برای تعریف الگوی فرمت‌بندی یا پارس ارائه می‌دهد.

مثال StringConverter در صفحه‌ی تبدیل تاریخ غیر-ISO نمونه‌ی دیگری از فرمت‌بند تاریخ ارائه می‌دهد.

فرمت‌بندی (Formatting)

متد ZonedDateTime.format() یک شیء مبتنی بر Temporal را با استفاده از قالب مشخص‌شده به رشته تبدیل می‌کند.

کد زیر یک نمونه‌ی ZonedDateTime را با قالب MMM d yyy hh:mm a تبدیل می‌کند. تاریخ به همان شکل مثال پارس قبلی تعریف شده اما این الگو شامل ساعت، دقیقه و اجزای a.m. و p.m. نیز هست.

DateTimeFormatter format = DateTimeFormatter.ofPattern("MMM d yyyy  hh:mm a");

// حرکت از سان‌فرانسیسکو در ۲۰ ژوئیه ۲۰۱۳ ساعت ۱۹:۳۰
LocalDateTime leaving = LocalDateTime.of(2013, Month.JULY, 20, 19, 30);
ZoneId leavingZone = ZoneId.of("America/Los_Angeles");
ZonedDateTime departure = ZonedDateTime.of(leaving, leavingZone);

try {
    String out1 = departure.format(format);
    System.out.printf("LEAVING:  %s (%s)%n", out1, leavingZone);
} catch (DateTimeException exc) {
    System.out.printf("%s can't be formatted!%n", departure);
    throw exc;
}

// پرواز ۱۰ ساعت و ۵۰ دقیقه، یعنی ۶۵۰ دقیقه
ZoneId arrivingZone = ZoneId.of("Asia/Tokyo");
ZonedDateTime arrival = departure.withZoneSameInstant(arrivingZone)
                                 .plusMinutes(650);

try {
    String out2 = arrival.format(format);
    System.out.printf("ARRIVING: %s (%s)%n", out2, arrivingZone);
} catch (DateTimeException exc) {
    System.out.printf("%s can't be formatted!%n", arrival);
    throw exc;
}

if (arrivingZone.getRules().isDaylightSavings(arrival.toInstant()))
    System.out.printf("  (%s daylight saving time will be in effect.)%n",
                      arrivingZone);
else
    System.out.printf("  (%s standard time will be in effect.)%n",
                      arrivingZone);

خروجی این مثال که زمان رسیدن و حرکت را چاپ می‌کند به صورت زیر است:

LEAVING:  Jul 20 2013  07:30 PM (America/Los_Angeles)
ARRIVING: Jul 21 2013  10:20 PM (Asia/Tokyo)
  (Asia/Tokyo standard time will be in effect.)

توجه کنید که متد format() روی سایر اشیاء API نیز وجود دارد:

• OffsetDateTime.format(DateTimeFormatter)
• OffsetTime.format(DateTimeFormatter)
• LocalDateTime.format(DateTimeFormatter)
• LocalDate.format(DateTimeFormatter)
• LocalTime.format(DateTimeFormatter)