Java8 以後的 LocalDateTime，你真的會用嗎？

2024-02-21碼農

LocalDateTime 是 Java 8 中日期時間 API 提供的一個類，在日期和時間的表示上提供了更加豐富和靈活的支持。

LocalDateTime 類相比於早期的 Date 和 Calendar 類來說有以下幾個優勢：

更加豐富的日期時間型別支持： LocalDateTime 類封裝了 LocalDate 和 LocalTime 兩個類，支持更加細化的日期時間操作，例如獲取某一天的開始和結束時間、獲取某個時間段內的所有日期等。
執行緒安全性： LocalDateTime 類是不可變物件，執行緒安全性較高，可以在多執行緒環境下安全使用。
時區支持： LocalDateTime 類在處理時區相關的操作時有著很好的支持，例如可以將一個 LocalDateTime 物件轉換成 ZonedDateTime 物件，以支持更加復雜的時區計算。

LocalDateTime 類的實作原理是基於 Java 的時間 API，其內部實作主要依賴於 Java 中的 long 型別和標準 Unix 時間戳來表示日期時間。具體來說，LocalDateTime 內部包含了一個 long 型別的欄位，用於表示自 UTC（協調世界時）1970 年 1 月 1 日 00:00:00 開始經過的毫秒數（即 Unix 時間戳），透過對這個時間戳的操作來實作 LocalDateTime 類的各種功能。

同時，在實作時區相關的操作時，LocalDateTime 類還依賴於 Java 中的時區類（例如 ZoneId 和 ZoneOffset），透過將 LocalDateTime 轉換為 ZonedDateTime 或 OffsetDateTime 物件來實作時區相關的計算。

一、LocalDateTime 的建立

LocalDateTime 類透過提供許多靜態方法來建立物件，這些方法包括：

1. of() 方法

of() 方法用於根據指定的年、月、日、時、分、秒和納秒值建立一個 LocalDateTime 物件，其語法如下：

publicstatic LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond)

其中，year、month、dayOfMonth、hour、minute、second 和 nanoOfSecond 分別表示年、月、日、時、分、秒和納秒值。

例如，以下程式碼建立了一個 LocalDateTime 物件，表示 2019 年 10 月 30 日 14 點 30 分 0 秒：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0);

2. now() 方法

now() 方法用於獲取當前系統時間的 LocalDateTime 物件，其語法如下：

publicstatic LocalDateTime now()

例如，以下程式碼建立了一個 LocalDateTime 物件，表示當前系統時間：

LocalDateTime dateTime = LocalDateTime.now();

3. parse() 方法

parse() 方法用於將一個字串解析成 LocalDateTime 物件，其語法如下：

publicstatic LocalDateTime parse(CharSequence text) publicstatic LocalDateTime parse(CharSequence text, DateTimeFormatter formatter)

其中，text 表示要解析的字串，formatter 表示日期時間格式化物件。如果不指定 formatter，則預設使用 ISO_LOCAL_DATE_TIME 格式。

例如，以下程式碼建立了一個 LocalDateTime 物件，表示 2019 年 10 月 30 日 14 點 30 分 0 秒：

LocalDateTime dateTime = LocalDateTime.parse("2019-10-30T14:30:00");

4. from() 方法

from() 方法用於將一個 TemporalAccessor 物件轉換成 LocalDateTime 物件，其語法如下：

publicstatic LocalDateTime from(TemporalAccessor temporal)

例如，以下程式碼將一個 ZonedDateTime 物件轉換成 LocalDateTime 物件：

ZonedDateTime zonedDate = ZonedDateTime.of(2019, 10, 30, 14, 30, 0, 0, ZoneId.systemDefault()); LocalDateTime localDateTime = LocalDateTime.from(zonedDate);

二、LocalDateTime 的轉換

LocalDateTime 類提供了許多方便的轉換方法，我們可以把 LocalDateTime 轉換成其他型別，或者把其他型別轉換成 LocalDateTime。這些方法包括：

1. toLocalDate() 方法

toLocalDate() 方法用於把 LocalDateTime 物件轉換成 LocalDate 物件，其語法如下：

public LocalDate toLocalDate()

例如，以下程式碼將一個 LocalDateTime 物件轉換成 LocalDate 物件：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); LocalDate date = dateTime.toLocalDate();

2. toLocalTime() 方法

toLocalTime() 方法用於把 LocalDateTime 物件轉換成 LocalTime 物件，其語法如下：

public LocalTime toLocalTime()

例如，以下程式碼將一個 LocalDateTime 物件轉換成 LocalTime 物件：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); LocalTime time = dateTime.toLocalTime();

3. atOffset() 方法

atOffset() 方法用於把 LocalDateTime 物件轉換成帶偏移量的 OffsetDateTime 物件，其語法如下：

public OffsetDateTime atOffset(ZoneOffset offset)

其中，offset 表示要添加的時區偏移量。

例如，以下程式碼將一個 LocalDateTime 物件轉換成帶偏移量的 OffsetDateTime 物件：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); ZoneOffset offset = ZoneOffset.of("+08:00"); OffsetDateTime offsetDateTime = dateTime.atOffset(offset);

4. toEpochSecond() 方法

toEpochSecond() 方法用於把 LocalDateTime 物件轉換成 Unix 時間戳，其語法如下：

publiclongtoEpochSecond(ZoneOffset offset)

其中，offset 表示要添加的時區偏移量。

例如，以下程式碼把一個 LocalDateTime 物件轉換成 Unix 時間戳：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); ZoneOffset offset = ZoneOffset.of("+08:00"); long epochSecond = dateTime.toEpochSecond(offset);

5. from() 方法

from() 方法用於將一個 TemporalAccessor 物件轉換成 LocalDateTime 物件，其語法與前面講解的相同，這裏不再贅述。

三、LocalDateTime 的格式化與解析

日期時間的格式化與解析是 Java 8 中日期時間 API 中的重要功能。LocalDateTime 類透過內建的 DateTimeFormatter 類以及一些方法來實作格式化和解析。下面我們將詳細介紹 LocalDateTime 類的格式化和解析方法。

1. format() 方法

format() 方法用於將 LocalDateTime 物件格式化成字串，其語法如下：

public String format(DateTimeFormatter formatter)

其中，formatter 表示日期時間格式化物件。

例如，以下程式碼將一個 LocalDateTime 物件格式化成 " yyyy-MM-dd HH:mm:ss " 格式的字串：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); String strDate = dateTime.format(formatter);

2. parse() 方法

parse() 方法用於將一個字串解析成 LocalDateTime 物件，其語法在前面已經介紹過，這裏不再贅述。

例如，以下程式碼將一個字串解析成 LocalDateTime 物件：

LocalDateTime dateTime = LocalDateTime.parse("2019-10-30T14:30:00");

3. DateTimeFormatter 類

DateTimeFormatter 類是 Java 8 中提供的日期時間格式化類，它提供了多種內建的格式化方式，同時也可以自訂日期時間格式。常用的幾種內建格式化方式包括：

ofPattern() 方法 ：使用指定的模式字串建立一個 DateTimeFormatter 物件。

public static DateTimeFormatter ofPattern(String pattern)

例如，以下程式碼建立了一個 " yyyy-MM-dd HH:mm:ss " 格式的 DateTimeFormatter 物件：

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

ISO_LOCAL_DATE_TIME ：表示格式為 "yyyy-MM-ddTHH:mm:ss" 的日期時間。

public static final DateTimeFormatter ISO_LOCAL_DATE_TIME

例如，以下程式碼建立了一個 " yyyy-MM-ddTHH:mm:ss " 格式的 DateTimeFormatter 物件：

DateTimeFormatter formatter = DateTimeFormatter.ISO_LOCAL_DATE_TIME;

ISO_LOCAL_DATE ：表示格式為 "yyyy-MM-dd" 的日期。

public static final DateTimeFormatter ISO_LOCAL_DATE

例如，以下程式碼建立了一個 " yyyy-MM-dd " 格式的 DateTimeFormatter 物件：

DateTimeFormatter formatter = DateTimeFormatter.ISO_LOCAL_DATE;

四、LocalDateTime 的計算與比較

LocalDateTime 類還提供了一些方法來進行日期時間的計算和比較。這些方法包括：

1. plusXxx() 和 minusXxx() 方法

plusXxx() 和 minusXxx() 方法分別用於在當前 LocalDateTime 物件上加上或減去指定的日期時間量，其中 Xxx 表示日期時間單位，如：Years、Months、Days、Hours、Minutes、Seconds 和 Nanos。

例如，以下程式碼將一個 LocalDateTime 物件加上 1 年並減去 1 月：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); dateTime = dateTime.plusYears(1).minusMonths(1);

2. withXxx() 方法

withXxx() 方法用於以指定的日期時間量來修改 LocalDateTime 物件的對應欄位，其他欄位不變，其中 Xxx 表示日期時間單位，如：Year、Month、DayOfMonth、Hour、Minute、Second 和 Nano。

例如，以下程式碼將 LocalDateTime 物件的年份修改為 2020 年：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); dateTime = dateTime.withYear(2020);

3. isBefore() 和 isAfter() 方法

isBefore() 和 isAfter() 方法分別用於判斷兩個 LocalDateTime 物件的先後順序。其中， isBefore() 方法用於判斷當前 LocalDateTime 物件是否在參數物件之前， isAfter() 方法用於判斷當前 LocalDateTime 物件是否在參數物件之後。

例如，以下程式碼判斷兩個 LocalDateTime 物件的先後順序：

LocalDateTime dateTime1 = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); LocalDateTime dateTime2 = LocalDateTime.of(2020, 10, 30, 14, 30, 0, 0); boolean before = dateTime1.isBefore(dateTime2); // true boolean after = dateTime1.isAfter(dateTime2); // false

五、LocalDateTime 的其他操作

LocalDateTime 類還提供了一些其他操作，這些操作包括：

1. with() 方法

with() 方法用於以指定的 TemporalAdjuster 物件或者方法來修改 LocalDateTime 物件，例如，以下程式碼將 LocalDateTime 物件的日期調整為當前月份的第一天：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); dateTime = dateTime.with(TemporalAdjusters.firstDayOfMonth());

其中，TemporalAdjusters 是 Java 8 中提供的一個類，它提供了許多方便的日期時間調整器，如： firstDayOfMonth() 、 lastDayOfMonth() 、 next() 、 previous() 等。透過呼叫這些方法可以生成對應的 TemporalAdjuster 物件。

2. getXXX() 方法

getXXX() 方法用於獲取 LocalDateTime 物件的指定欄位值，其中 Xxx 表示日期時間單位，如：Year、Month、DayOfMonth、Hour、Minute、Second 和 Nano。

例如，以下程式碼獲取 LocalDateTime 物件的月份和分鐘數：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); int month = dateTime.getMonthValue(); // 10 int minute = dateTime.getMinute(); // 30

3. getDayOfWeek() 和 getDayOfMonth() 方法

getDayOfWeek() 和 getDayOfMonth() 方法分別用於獲取 LocalDateTime 物件所表示日期的星期幾和哪一天。例如，以下程式碼獲取 LocalDateTime 物件的星期幾和哪一天：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); DayOfWeek dayOfWeek = dateTime.getDayOfWeek(); // WEDNESDAY int dayOfMonth = dateTime.getDayOfMonth(); // 30

4. toInstant() 方法

toInstant() 方法用於獲取 LocalDateTime 物件的 Instant 物件，其中 Instant 物件表示了從 1970 年 1 月 1 日 00:00:00 GMT 開始的毫秒數例如，以下程式碼獲取 LocalDateTime 物件的 Instant 物件：

LocalDateTime dateTime = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); Instant instant = dateTime.toInstant();

5. compareTo() 方法

compareTo() 方法用於比較兩個 LocalDateTime 物件的順序大小，如果當前物件在參數物件之前，則返回負數，如果當前物件在參數物件之後，則返回正數，如果兩個物件相等，則返回 0。

例如，以下程式碼比較兩個 LocalDateTime 物件的順序：

LocalDateTime dateTime1 = LocalDateTime.of(2019, 10, 30, 14, 30, 0, 0); LocalDateTime dateTime2 = LocalDateTime.of(2020, 10, 30, 14, 30, 0, 0); int result = dateTime1.compareTo(dateTime2); // -1