LocalDate详解API
在Java 8中引入的LocalDate表示一个格式为yyyy-MM-dd的日期，如2021-06-13。
它不存储时间或时区。
LocalDate是一个不可变的类，它是对日期的描述，如生日。
LocalDate是一个基于值的类，要比较LocalDate的两个实例，我们应该使用它的equals 方法。
我们可以从LocalDate中获取许多其他的日期字段，如年日(day-of-year)、周日(day-of-week)、月日(month-of-year)等等。
LocalDate的格式可以通过DateTimeFormatter的格式方法来改变。
现在LocalDate的方法有：atTime、format、getDayOfMonth、getDayOfWeek、minus、plus、equals、compareTo等。
例如，获取当前日期。
输出是2021-06-13。
现在改变格式。
String formattedDate = localDate.format(DateTimeFormatter.ofPattern("MMM dd, yyyy"));
输出是 六月 13, 2021。
在Java 9中，LocalDate被添加了更多的方法，如ofInstant、datesUntil、toEpochSecond。在这一页，我们将讨论LocalDate和它的方法，并举例说明。
LocalDate - 初始化
LocalDate以年月日的格式输出，即yyyy-MM-dd。
我们可以使用LocalDate的下列静态方法来初始化LocalDate。
1. now(): 给出LocalDate实例，该实例包含默认时区的系统时钟的当前日期。
LocalDate localDate = LocalDate.now();
System.out.println(localDate);
输出
2021-06-13
2. now(Clock clock): 提供LocalDate实例，该实例具有从指定时钟获得的当前日期。
LocalDate localDate = LocalDate.now(Clock.systemUTC());
Clock.systemUTC()将返回Clock实例。
3. now(ZoneId zone): 给出当前日期的LocalDate实例，该日期来自指定时区的系统时钟。
LocalDate localDate = LocalDate.now(ZoneId.systemDefault());
4. of(int year, int month, int dayOfMonth: 从给定的年、月、日中获得LocalDate实例，输入数据类型为int。
LocalDate localDate = LocalDate.of(2018, 11, 30);
输出为2018-11-30。
5. of(int year, Month month, int dayOfMonth): 从给定的年（int）、月（Month）和日（int）给出LocalDate实例。
LocalDate localDate = LocalDate.of(2018, Month.NOVEMBER, 30);
输出为2018-11-30。
6. ofEpochDay(long epochDay): 从给定的纪元日数中给出LocalDate实例。
LocalDate localDate = LocalDate.ofEpochDay(500);
输出为1971-05-16。
7. ofInstant(Instant instant, ZoneId zone): 从给定的Instant和ZoneId给出LocalDate实例。
LocalDate localDate = LocalDate.ofInstant(Instant.now(), ZoneId.systemDefault());
注：ofInstant在Java 9中被引入。
8. ofYearDay(int year, int dayOfYear): 从给定的年份和年份中的天数给出LocalDate实例，输入数据类型为int。
LocalDate localDate = LocalDate.ofYearDay(2018, 02);
输出为2018-01-02，即2018年第二天的日期。
9. parse(CharSequence text): 从给定的文本字符串，如 "2018-10-01"，给出LocalDate实例。
LocalDate localDate = LocalDate.parse("2018-10-01");
输出为2018-10-01。
10. parse(CharSequence text, DateTimeFormatter formatter): 从给定格式的文本字符串中获得LocalDate实例。输出的LocalDate将是yyyy-MM-dd格式。
LocalDate localDate = LocalDate.parse("15-03-2018", DateTimeFormatter.ofPattern("dd-MM-yyyy"));
输出为2018-03-15。
11. from(TemporalAccessor temporal): 从给定的时间对象中获得LocalDate实例。
LocalDate localDate = LocalDate.from(LocalDate.now());
plus - 按给定数量增加日期值
1. plus(long amountToAdd, TemporalUnit unit): 通过增加给定的数量返回LocalDate实例。
import java.time.LocalDate;
import java.time.temporal.ChronoUnit;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.plus(15, ChronoUnit.DAYS);
System.out.println(localDate2);
}
}
输出
2021-06-13
2021-06-28
在上面的例子中，我们在当前日期中增加了15天。
2. plus(TemporalAmount amountToAdd): 通过添加指定的TemporalAmount返回LocalDate实例。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.plus(Period.ofDays(15));
System.out.println(localDate2);
输出
2021-06-13
2021-06-28
在上面的代码中，我们给localDate1增加了15天，得到localDate2作为LocalDate的实例。
3. plusDays(long daysToAdd): 通过添加指定的天数返回LocalDate实例。
LocalDate localDate1 = LocalDate.parse("2018-11-05");
LocalDate localDate2 = localDate1.plusDays(15);
System.out.println(localDate2);
输出为2018-11-20。
4. plusWeeks(long weeksToAdd): 通过添加指定的周数返回 LocalDate 实例，用法与plusDays类似。
5. plusMonths(long monthsToAdd): 通过添加指定的月数返回 LocalDate 实例，用法与plusDays类似。
6. plusYears(long yearsToAdd): ，通过添加指定的年数返回 LocalDate 实例，用法与plusDays类似。
minus - 按给定数量减去日期值
1. minus(long amountToSubtract, TemporalUnit unit): 通过减去给定的数量返回LocalDate实例。
import java.time.LocalDate;
import java.time.temporal.ChronoUnit;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.minus(15, ChronoUnit.DAYS);
System.out.println(localDate2);
}
}
输出
2018-12-02
2018-11-17
在上面的例子中，我们在当前日期中减少了15天。
2. minus(TemporalAmount amountToSubtract): 通过减去指定的TemporalAmount返回LocalDate实例。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.minus(Period.ofDays(15));
System.out.println(localDate2);
输出
2018-12-02
2018-11-17
在上面的代码中，我们给localDate1减少了15天，得到localDate2作为LocalDate的实例。
3. minusDays(long daysToSubtract): 通过减少指定的天数返回LocalDate实例。
LocalDate localDate1 = LocalDate.parse("2018-11-05");
LocalDate localDate2 = localDate1.minusDays(15);
System.out.println(localDate2);
输出为2018-10-21。
4. minusWeeks(long weeksToSubtract): 通过减少指定的周数返回 LocalDate 实例，用法与minusDays相似。
5. minusMonths(long monthsToSubtract): 通过减少指定的月数返回 LocalDate 实例，用法与minusDays相似。
6. minusYears(long yearsToSubtract): ，通过减少指定的年数返回 LocalDate 实例，用法与minusDays相似。
with - 调整日期
查看LocalDate方法，这些方法将返回具有指定值的LocalDate调整，或为给定的日期字段设置一个新值。
1. with(TemporalAdjuster adjuster): 返回用给定的TemporalAdjuster调整的LocalDate实例。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.with(DayOfWeek.SUNDAY);
System.out.println(localDate2);
输出
2018-12-03
2018-12-09
在上面的代码中，我们使用with方法改变了当前日期的日期。在当前日期的输出中，它是星期一。
通过调整星期日，我们得到一个新的日期。
2. with(TemporalField field, long newValue): 将指定字段的LocalDate实例返回到一个新值。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.with(ChronoField.YEAR, 2017);
System.out.println(localDate2);
输出
2018-12-03
2017-12-03
在上面的代码中，我们为年份设置了新的值。
3. withDayOfMonth(int dayOfMonth): 通过用给定的值改变月份中的号数来返回LocalDate实例。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.withDayOfMonth(10);
System.out.println(localDate2);
输出
2018-12-03
2018-12-10
4. withDayOfYear(int dayOfYear): 通过使用给定值更改一年中的某一天来返回 LocalDate 实例。一年中的第几天的有效值为 1 到 365，闰年的有效值为 1 到 366。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.withDayOfYear(110);
System.out.println(localDate2);
输出
2018-12-03
2018-04-20
在上面的例子中，我们想在当前日期中设置110。输出的方式是，年不会改变，月和日将从1月开始的第110天中获得。
5. withMonth(int month): 通过用给定的值改变年的月份来返回LocalDate实例。有效值是1到12。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.withMonth(6);
System.out.println(localDate2);
输出
2018-12-03
2018-06-03
6. withYear(int year): 通过用给定值改变年份来返回LocalDate实例。
LocalDate localDate1 = LocalDate.now();
System.out.println(localDate1);
LocalDate localDate2 = localDate1.withYear(2017);
System.out.println(localDate2);
输出
2018-12-03
2017-12-03
get - 获取日期信息
创建一个LocalDate实例，如下所示。
LocalDate localDate = LocalDate.now();
System.out.println(localDate);
假设它给出了以下数值。
2018-12-03
1. get(TemporalField field): 获取指定字段的int值。
int val = localDate.get(ChronoField.YEAR);
System.out.println(val);
输出为2018。
2. getChronology(): 获取该日期格式，例如：ISO。
3. getDayOfMonth(): 获取一个月中的第几号，为int类型。
int val = localDate.getDayOfMonth();
System.out.println(val);
输出为3。
4. getDayOfWeek(): 获取星期字段，返回DayOfWeek。
DayOfWeek val = localDate.getDayOfWeek();
System.out.println(val.name());
输出为MONDAY。
5. getDayOfYear(): 以 int 格式获取一年中的第几天。它可以返回从 1 到 365 或 366 (闰年)。
int val = localDate.getDayOfYear();
System.out.println(val);
输出为337。
6. getEra(): 获取在此日期适用的时代。例如："CE "从第一年开始，"BCE "从零年开始。
IsoEra val = localDate.getEra();
7. getLong(TemporalField field): 获取指定字段的值，返回long类型。
long val = localDate.getLong(ChronoField.YEAR);
System.out.println(val);
输出为2018。
8. getMonth(): 从这个日期获取一年中的月份，返回值为Month类型。
Month val = localDate.getMonth();
System.out.println(val.name());
输出为DECEMBER。
9. getMonthValue(): 获取月份，取值范围为1-12的int类型。
int val = localDate.getMonthValue();
System.out.println(val);
输出为12。
10. getYear(): 获取年份，返回int类型。
int val = localDate.getYear();
System.out.println(val);
输出为2018。
LocalDate format() 转换格式
LocalDate 的默认日期格式为 yyyy-MM-dd。
format 方法使用指定的格式化程序格式化日期。
找到它的声明。
String format(DateTimeFormatter formatter)
示例
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-02-18");
String formattedDate = localDate.format(DateTimeFormatter.ofPattern("MMM dd, yyyy"));
System.out.println(formattedDate);
}
}
输出
二月 18, 2018
atTime() - 将 LocalDate 与时间结合转化为 LocalDateTime
atTime 方法将 LocalDate 与给定时间结合起来，并返回 LocalDateTime 实例。
我们可以将以下参数传递给 atTime 方法。
atTime(int hour, int minute)
atTime(int hour, int minute, int second)
atTime(int hour, int minute, int second, int nanoOfSecond)
atTime(LocalTime time)
示例
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-05-02");
System.out.println(localDate);
//hour and minute
LocalDateTime localDateTime = localDate.atTime(16, 50);
System.out.println(localDateTime);
//hour, minute and second
localDateTime = localDate.atTime(16, 50, 20);
System.out.println(localDateTime);
//hour, minute, second and nanoOfSecond
localDateTime = localDate.atTime(16, 50, 20, 300);
System.out.println(localDateTime);
//Using LocalTime
localDateTime = localDate.atTime(LocalTime.now());
System.out.println(localDateTime);
}
}
输出
2018-05-02
2018-05-02T16:50
2018-05-02T16:50:20
2018-05-02T16:50:20.000000300
2018-05-02T17:53:24.952
我们还可以将 OffsetTime 传递给将返回 OffsetDateTime 实例的 atTime。
OffsetDateTime offsetDateTime = localDate.atTime(OffsetTime.now());
System.out.println(offsetDateTime)
输出为2018-05-02T17:54:37.104+08:00。
atStartOfDay() 将 LocalDate 转化为 LocalDateTime
atStartOfDay方法将LocalDate与00:00的时间结合起来，在这个日期的开始创建LocalDateTime实例。
为了得到ZonedDateTime实例，我们需要将ZoneId实例传递给atStartOfDay方法。
找到atStartOfDay方法的声明。
LocalDateTime atStartOfDay()
ZonedDateTime atStartOfDay(ZoneId zone)
示例
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.now();
LocalDateTime localDateTime = localDate.atStartOfDay();
System.out.println(localDateTime);
ZonedDateTime zonedDateTime = localDate.atStartOfDay(ZoneId.systemDefault());
System.out.println(zonedDateTime);
}
}
输出
2021-06-13T00:00
2021-06-13T00:00+08:00[Asia/Shanghai]
我们可以看到，时间值是一天的开始。
LocalDate isAfter(), isBefore() and isEqual() 比较日期
isAfter(ChronoLocalDate other): 检查此日期是否在给定日期之后。
isBefore(ChronoLocalDate other): 检查此日期是否在给定日期之前。
isEqual(ChronoLocalDate other): 检查此日期是否等于给定日期。
示例
import java.time.LocalDate;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate1 = LocalDate.parse("2018-03-18");
LocalDate localDate2 = LocalDate.parse("2018-05-12");
System.out.println(localDate1.isAfter(localDate2));
System.out.println(localDate1.isBefore(localDate2));
System.out.println(localDate1.isEqual(localDate2));
}
}
输出
false
true
false
LocalDate isLeapYear(), isSupported() 检查闰年和输入域
isLeapYear(): 检查年份是否为闰年。
isSupported(TemporalField field): 检查是否支持给定字段。在从日期获取任何字段之前，我们可以检查该字段是否受支持，否则我们可能会出错。
isSupported(TemporalUnit unit): 检查是否支持给定的单位。在使用加减之前，我们可以检查是否支持给定的单位，否则我们可能会出错。
示例
import java.time.LocalDate;
import java.time.temporal.ChronoField;
import java.time.temporal.ChronoUnit;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2016-03-18");
System.out.println(localDate.isLeapYear());
System.out.println(localDate.isSupported(ChronoField.DAY_OF_MONTH));
System.out.println(localDate.isSupported(ChronoUnit.HOURS));
}
}
输出
true
true
false
LocalDate lengthOfMonth(), lengthOfYear() 检查月份和年份天数最大值
lengthOfMonth(): 给出月份的最大天数，例如 28、29、30、31。
lengthOfYear(): 给出年份的最大天数 365 或 366（闰年）。
示例
import java.time.LocalDate;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-02-18");
System.out.println(localDate.lengthOfMonth());
System.out.println(localDate.lengthOfYear());
}
}
输出
28
365
LocalDate datesUntil() 返回指定时间段
Java 9 中引入了LocalDate 中的datesUntil 方法。
datesUntil 方法返回不包括给定日期的有序的日期流。
我们也可以通过 period 来设置增量步长。
我们获取从该日期开始到指定日期的日期流。
指定的日期将被排除在结果中。
dateUntil 声明如下。
Stream<LocalDate> datesUntil(LocalDate endExclusive)
Stream<LocalDate> datesUntil(LocalDate endExclusive, Period step)
示例
import java.time.LocalDate;
import java.time.Period;
import java.util.stream.Stream;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-02-18");
System.out.println("--- With LocalDate ---");
Stream<LocalDate> localDateStream = localDate.datesUntil(LocalDate.parse("2018-02-22"));
localDateStream.forEach(date -> System.out.println(date));
System.out.println("--- With LocalDate and Period ---");
localDateStream = localDate.datesUntil(LocalDate.parse("2018-02-22"), Period.ofDays(2));
localDateStream.forEach(date -> System.out.println(date));
}
}
输出
--- With LocalDate ---
2018-02-18
2018-02-19
2018-02-20
2018-02-21
--- With LocalDate and Period ---
2018-02-18
2018-02-20
LocalDate until() 计算两个日期之间的时间量
1.计算此日期和指定日期之间的时期为Period
Period until(ChronoLocalDate endDateExclusive)
2.计算距指定日期（不包括）的时间量。
long until(Temporal endExclusive, TemporalUnit unit)
示例
import java.time.LocalDate;
import java.time.Period;
import java.time.temporal.ChronoUnit;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-02-18");
Period period = localDate.until(LocalDate.parse("2018-03-28"));
System.out.println(period.getDays());
long val = localDate.until(LocalDate.parse("2018-03-28"), ChronoUnit.DAYS);
System.out.println(val);
}
}
123456789101112131415
输出
10
38
LocalDate compareTo() and equals() 比较日期
compareTo(ChronoLocalDate other): 将此日期与指定日期进行比较。
equals(Object obj): 检查此日期是否等于指定日期。
示例
LocalDate localDate = LocalDate.parse("2018-02-18");
System.out.println(localDate.equals(LocalDate.parse("2018-02-18")));
System.out.println(localDate.compareTo(LocalDate.parse("2018-02-25")));
输出
true
-7
LocalDate adjustInto() 复制日期
adjustInto方法将指定的时间对象调整为与此对象具有相同的日期。
找到这个例子。
import java.time.LocalDate;
import java.time.temporal.Temporal;
public class LocalDateDemo {
public static void main(String[] args) {
LocalDate localDate = LocalDate.parse("2018-02-18");
Temporal temporalObj = LocalDate.parse("2017-03-20");
temporalObj = localDate.adjustInto(temporalObj);
System.out.println(temporalObj);
}
}
输出
2018-02-18
我们可以看到temporalObj的日期值与localDate不同。
但在用localDate调整temporalObj后，两者是一样的。
LocalDate query() 查询日期
query方法使用指定的查询方式查询这个日期。
TemporalUnit unit = localDate.query(TemporalQueries.precision());
输出为Days。
TemporalQueries.precision()查询最小的支持单位。
它返回TemporalQuery的实例。
LocalDate range() 字段有效值范围。
range给出指定字段的有效值范围。
LocalDate localDate = LocalDate.parse("2018-02-18");
ValueRange vrange = localDate.range(ChronoField.DAY_OF_MONTH);
System.out.println(vrange);
vrange = localDate.range(ChronoField.DAY_OF_WEEK);
System.out.println(vrange);
输出
1 - 28
1 – 7
在上面的代码中，日期是“2018-02-18”。
我们可以看到这个日期年二月的日期范围可以是 1 – 28，星期几是 1 – 7。
LocalDate toEpochDay() and toEpochSecond()
toEpochDay(): 将此日期转换为历法日，并返回long值。
toEpochSecond(LocalTime time, ZoneOffset offset): 此日期转换为自1970-01-01T00:00:00Z纪元以来的秒数，并返回long值。在Java 9中引入。
示例
LocalDate localDate = LocalDate.parse("2018-02-18");
System.out.println(localDate.toEpochDay());
System.out.println(localDate.toEpochSecond(LocalTime.now(), ZoneOffset.MAX));
123
输出
17580
1518921065
参考文献
【1】Class LocalDate
【2】Java LocalDate