betacode

Руководство Java ChronoUnit

  1. ChronoUnit
  2. ChronoUnit Values
  3. ChronoUnit methods
  4. CENTURIES
  5. DAYS
  6. DECADES
  7. ERAS
  8. FOREVER
  9. HALF_DAYS
  10. HOURS
  11. MICROS
  12. MILLENNIA
  13. MILLIS
  14. MINUTES
  15. MONTHS
  16. NANOS
  17. SECONDS
  18. WEEKS
  19. YEARS
  20. getDuration()
  21. isDurationEstimated()
  22. isDateBased()
  23. isTimeBased()
  24. isSupportedBy(Temporal)
  25. addTo(R temporal, long amount)
  26. between(Temporal, Temporal)

1. ChronoUnit

ChronoUnit - это enum, реализующее интерфейс TemporalUnit, который предоставляет стандартные единицы измерения, используемые в Java Date Time API. В основном этих единиц достаточно для использования. Однако, если вам нужена пользовательская единица измерения, напишите класс, реализующий интерфейс TemporalUnit.
public enum ChronoUnit implements TemporalUnit
  • TemporalField
  • TemporalUnit
  • ChronoField
Эти единицы предназначены для применения в нескольких календарных системах. Например, большинство календарных систем, "не относящихся к ISO", определяют единицы измерения лет, месяцев и дней, просто с немного другими правилами. Документация каждой единицы измерения объясняет, как она работает.

2. ChronoUnit Values

Enum
Display Name
Estimated Duration
NANOS
Nanos
Duration.ofNanos(1)
MICROS
Micros
Duration.ofNanos(1000)
MILLIS
Millis
Duration.ofNanos(1000_000)
SECONDS
Seconds
Duration.ofSeconds(1)
MINUTES
Minutes
Duration.ofSeconds(60)
HOURS
Hours
Duration.ofSeconds(3600)
HALF_DAYS
HalfDays
Duration.ofSeconds(43200)
DAYS
Days
Duration.ofSeconds(86400)
WEEKS
Weeks
Duration.ofSeconds(7 * 86400L)
MONTHS
Months
Duration.ofSeconds(31556952L / 12)
YEARS
Years
Duration.ofSeconds(31556952L)
DECADES
Decades
Duration.ofSeconds(31556952L * 10L)
CENTURIES
Centuries
Duration.ofSeconds(31556952L * 100L)
MILLENNIA
Millennia
Duration.ofSeconds(31556952L * 1000L)
ERAS
Eras
Duration.ofSeconds(31556952L * 1000_000_000L)
FOREVER
Forever
Duration.ofSeconds(Long.MAX_VALUE, 999_999_999)

3. ChronoUnit methods

public Duration getDuration()   

public boolean isDurationEstimated()  

public boolean isDateBased()  

public boolean isTimeBased()  

public boolean isSupportedBy(Temporal temporal)  

public <R extends Temporal> R addTo(R temporal, long amount)  

public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)

4. CENTURIES

Единица измерения, представляющая концепцию века. Для календарной системы ISO это равно 100 годам.
Вышесказанное также верно для календарных систем Hijrah, Japanese, Minguo и ThaiBuddhist.
When used with other calendar systems it must correspond to an integral number of days and is normally an integral number of years.

5. DAYS

Единица измерения, представляющая концепцию дня. Для календарной системы ISO это стандартный день с полуночи до полуночи. Расчетная продолжительность одного дня составляет 24 часа.
Вышесказанное также верно для календарных систем Hijrah, Japanese, Minguo и ThaiBuddhist.
При использовании с другими календарными системами он должен соответствовать дню, определяемому восходом и заходом Солнца на Земле. Не обязательно, чтобы дни начинались в полночь - при преобразовании между календарными системами они должны пересекаться в полдень.
Например: Найдите количество дней между 2 периодами времени.
ChronoUnit_DAYS_ex1.java
LocalDateTime localDateTime1 = LocalDateTime.of(2020, 3, 15, 0, 30, 45);
LocalDateTime localDateTime2 = LocalDateTime.of(2020, 3, 17, 13, 30, 45);

Duration duration = Duration.between(localDateTime1, localDateTime2);
System.out.println("duration: " + duration); // PT61H (61 Hours)

long days = ChronoUnit.DAYS.between(localDateTime1, localDateTime2);
System.out.println("days: " + days); // 2
Наример: Добавьте 2 дня.
ChronoUnit_DAYS_ex2.java
ZonedDateTime now = ZonedDateTime.now();
// Plus 2 days
ZonedDateTime after2Days = now.plus(2, ChronoUnit.DAYS);

System.out.println("Now is: " + now);
System.out.println("After 2 days: " + after2Days);
Output:
Now is: 2021-07-17T00:50:13.048263+06:00[Asia/Bishkek]
After 2 days: 2021-07-19T00:50:13.048263+06:00[Asia/Bishkek]

6. DECADES

Единица измерения, представляющая концепцию десятилетия. Для календарной системы ISO это равно 10 годам.
Вышесказанное также верно для календарных систем Hijrah, Japanese, Minguo и ThaiBuddhist.
При использовании с другими календарными системами он должен соответствовать целому числу дней и обычно является целым числом лет.

7. ERAS

Единица измерения, представляющая концепцию эры (Era).
Система календаря ISO не имеет понятия об эры, поэтому она не отображается в строках с форматами даты и времени. Искусственно оцененное время эры в этой системе составляет 1 миллиард лет.
Calendar system
Date Time String
ISO
1989-02-08
Japanese Imperial Calendar
Japanese Heisei 1-02-08
Эра связана с периодом правления короля или продолжительностью династии. Концепция эры наиболее очевидна в японской императорской календарной системе.
При использовании с другими календарными системами её значение не ограничено.
ChronoUnit_ERAS_ex1.java
LocalDate isoDate = LocalDate.of(2020, 3, 15);
System.out.printf("isoDate: %s%n%n", isoDate); // 2020-03-15

JapaneseDate japaneseDate = JapaneseDate.from(isoDate);
JapaneseEra era = japaneseDate.getEra();

System.out.printf("japaneseDate: %s%n", japaneseDate); // Japanese Reiwa 2-03-15
System.out.printf(" > era: %s", era); // Reiwa
Output:
isoDate: 2020-03-15

japaneseDate: Japanese Reiwa 2-03-15
 > era: Reiwa

8. FOREVER

Искусственная единица, представляющая концепцию вечности. Это в основном используется сTemporalField для представления неограниченных полей, таких как год или эра (era). Предполагаемая продолжительность этой единицы искусственно определяется как наибольшая продолжительность, поддерживаемая Duration.
Duration maxDuration = ChronoUnit.FOREVER.getDuration();
Например:
ChronoUnit_FOREVER_ex1.java
for (final ChronoUnit unit : ChronoUnit.values()) {
    final Duration duration = unit.getDuration();
    System.out.println(unit + ": " + duration + " (" + duration.getSeconds() + " seconds)");
}
Output:
Nanos: PT0.000000001S (0 seconds)
Micros: PT0.000001S (0 seconds)
Millis: PT0.001S (0 seconds)
Seconds: PT1S (1 seconds)
Minutes: PT1M (60 seconds)
Hours: PT1H (3600 seconds)
HalfDays: PT12H (43200 seconds)
Days: PT24H (86400 seconds)
Weeks: PT168H (604800 seconds)
Months: PT730H29M6S (2629746 seconds)
Years: PT8765H49M12S (31556952 seconds)
Decades: PT87658H12M (315569520 seconds)
Centuries: PT876582H (3155695200 seconds)
Millennia: PT8765820H (31556952000 seconds)
Eras: PT8765820000000H (31556952000000000 seconds)
Forever: PT2562047788015215H30M7.999999999S (9223372036854775807 seconds)

9. HALF_DAYS

Единица измерения, представляющая понятие половины дня, как используется в AM/PM. Для календарной системы ISO это равно 12 часам.
Например: Усеките (truncate) остаток, если разделить его на половину дня от LocalDateTime.
ChronoUnit_HALF_DAYS_ex1.java
LocalDateTime localDateTime1 = LocalDateTime.of(2020, 3, 15, 9, 30, 45);
LocalDateTime truncatedLDT1 = localDateTime1.truncatedTo(ChronoUnit.HALF_DAYS);

System.out.printf("localDateTime1: %s%n", localDateTime1); // 2020-03-15T09:30:45
System.out.printf(" > truncated: %s%n%n", truncatedLDT1);  // 2020-03-15T00:00

LocalDateTime localDateTime2 = LocalDateTime.of(2020, 3, 15, 13, 30, 45);
LocalDateTime truncatedLDT2 = localDateTime2.truncatedTo(ChronoUnit.HALF_DAYS);

System.out.printf("localDateTime2: %s%n", localDateTime2); // 2020-03-15T13:30:45
System.out.printf(" > truncated: %s", truncatedLDT2);      // 2020-03-15T12:00
Output:
localDateTime1: 2020-03-15T09:30:45
 > truncated: 2020-03-15T00:00

localDateTime2: 2020-03-15T13:30:45
 > truncated: 2020-03-15T12:00

10. HOURS

Единица измерения, представляющая понятие часа. Для календарной системы ISO это равно 60 минутам.
Например:
ChronoUnit_HOURS_ex1.java
ZonedDateTime parisNow = ZonedDateTime.now(ZoneId.of("Europe/Paris"));
System.out.println("Now in Paris: " + parisNow);
  
ZonedDateTime parisNowHour = parisNow.truncatedTo(ChronoUnit.HOURS);
System.out.println("Truncated to Hour: " + parisNowHour);
Output:
Now in Paris: 2021-07-17T05:40:15.939515+02:00[Europe/Paris]
Truncated to Hour: 2021-07-17T05:00+02:00[Europe/Paris]

11. MICROS

Единица измерения, представляющая понятие микросекунды. Для календарной системы ISO 1 секунда равна 1 миллиону микросекунд.

12. MILLENNIA

Единица измерения, представляющая концепцию тысячелетия. Для календарной системы ISO это равно 1000 годам.
Вышесказанное также верно для календарных систем Hijrah, Japanese, Minguo и ThaiBuddhist.
При использовании с другими календарными системами он должен соответствовать целому числу дней и обычно является целым числом лет.

13. MILLIS

Единица измерения, представляющая понятие миллисекунды. Для календарной системы ISO 1 секунда равна 1000 миллисекундам.

14. MINUTES

Единица измерения, представляющая понятие минуты. Для календарной системы ISO это равно 60 секундам.

15. MONTHS

Единица измерения, представляющая концепцию месяца. Для календарной системы ISO продолжительность месяца варьируется в зависимости от месяца года. Предполагаемая продолжительность месяца составляет одну двенадцатую часть 365,2425 дней.
При использовании с другими календарными системами он должен соответствовать целому числу дней.

16. NANOS

Единица измерения, представляющая концепцию наносекунды, наименьшей поддерживаемой единицы времени. Для календарной системы ISO 1 секунда равна 1 миллиарду наносекунд.

17. SECONDS

Единица измерения, представляющая собой понятие секунды. Для календарной системы ISO она равна второй в системе единиц SI, за исключением примерно високосной секунды.

18. WEEKS

Единица измерения, представляющая концепцию недели. Для календарной системы ISO это равно 7 дням.
Вышесказанное также верно для календарных систем Hijrah, Japanese, Minguo и ThaiBuddhist.
При использовании с другими календарными системами он должен соответствовать целому числу дней.

19. YEARS

Единица измерения, представляющая концепцию года. Для календарной системы ISO это равно 12 месяцам. Предполагаемая продолжительность года составляет 365,2425 дня.
Год в календарных системах Hijrah, Japanese, Minguo и ThaiBuddhist также равен 12 месяцам.
При использовании с другими календарными системами он должен соответствовать целому числу дней или месяцев, примерно равному году, определяемому движением Земли вокруг Солнца.

20. getDuration()

Возвращает расчетную продолжительность этой единицы измерения в системе календаря ISO.
public Duration getDuration()
Все единицы измерения этого класса имеют расчетную продолжительность. Дни различаются в зависимости от "летнего времени" (Daylight Saving Time - DST), в то время как месяцы имеют разную продолжительность.
Например: Месяц оценивается в 30 дней, но в часах он оценивается в 730 (30,41 дня).
ChronoUnit_getDuration_ex1.java
Duration monthDuration = ChronoUnit.MONTHS.getDuration();  
// to days: 30 days
System.out.println("monthDuration.toDays(): " + monthDuration.toDays());  

// to hours: 730 hours ~ 30.41 days.
System.out.println("monthDuration.toHours(): " + monthDuration.toHours());
Output:
monthDuration.toDays(): 30
monthDuration.toHours(): 730
Например: Оцените количество часов в "1 год 2 месяца 15 дней".
ChronoUnit_getDuration_ex2.java
Period period = Period.of(1, 2, 15); // 1 year 2 months 15 days.

int years = period.getYears(); // 1
int months = period.getMonths(); // 2
int days = period.getDays(); // 15

System.out.println("years: " + years); // 1
System.out.println("months: " + months);// 2
System.out.println("days: " + days); // 15

Duration yearsDuration = ChronoUnit.YEARS.getDuration().multipliedBy(years);
Duration monthsDuration = ChronoUnit.MONTHS.getDuration().multipliedBy(months);
Duration daysDuration = ChronoUnit.DAYS.getDuration().multipliedBy(days);

Duration totalDuration = yearsDuration.plus(monthsDuration).plus(daysDuration);

long estimatedDays = totalDuration.toDays();
long estimatedHours = totalDuration.toHours();
System.out.println("Estimated days: " + estimatedDays); // 441 days
System.out.println("Estimated hours: " + estimatedHours); // 10586 hours ~ 441.08 days.
Output:
years: 1
months: 2
days: 15
Estimated days: 441
Estimated hours: 10586

21. isDurationEstimated()

Проверяет, является ли продолжительность единицы измерения приблизительной.
public boolean isDurationEstimated()
Все единицы измерения времени в этом классе считаются точными, в то время как все единицы измерения даты в этом классе считаются оценочными. Смотрите дополнительные методы isTimeBased() и isDateBased().
Это определение игнорирует високосные секунды, но учитывает, что дни различаются из-за перехода на летнее время, а месяцы имеют разную продолжительность.
Например: Распечатайте список единиц точности этого класса.
ChronoUnit_isDurationEstimated_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isDurationEstimated()) {
        System.out.println(unit.name());
    }
}
Output:
DAYS
WEEKS
MONTHS
YEARS
DECADES
CENTURIES
MILLENNIA
ERAS
FOREVER

22. isDateBased()

Проверьте, основана ли эта единица измерения на дате?
public boolean isDateBased()
Все единицы измерения от DAYS и ERAS возвращают true. Единицы измерения, основанные на времени, и FOREVER возвращают значение false.
ChronoUnit_isDateBased_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isDateBased()) {
        System.out.println(unit.name());
    }
}
Output:
DAYS
WEEKS
MONTHS
YEARS
DECADES
CENTURIES
MILLENNIA
ERAS

23. isTimeBased()

Проверьте, основана ли эта единица измерения на времени?
public boolean isTimeBased()
Все единицы измерения от NANOS до HALF_DAYS возвращают значение true. Единицы измерения, основанные на дате и FOREVER, возвращают значение false.
ChronoUnit_isTimeBased_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isTimeBased()) {
        System.out.println(unit.name());
    }
}
Output:
NANOS
MICROS
MILLIS
SECONDS
MINUTES
HOURS
HALF_DAYS

24. isSupportedBy(Temporal)

Проверяет, поддерживается ли эта единица измерения указанным объектом Temporal.
public boolean isSupportedBy(Temporal temporal)
Например: Найдите единицы измерения, поддерживаемые LocalDate:
ChronoUnit_isSupportedBy_ex1.java
Temporal localDate = LocalDate.now();
System.out.println("Does LocalDate support: ");

for(ChronoUnit unit: ChronoUnit.values()) {
    System.out.println(unit.name() + "? " + unit.isSupportedBy(localDate));  
}
Output:
Does LocalDate support:
NANOS? false
MICROS? false
MILLIS? false
SECONDS? false
MINUTES? false
HOURS? false
HALF_DAYS? false
DAYS? true
WEEKS? true
MONTHS? true
YEARS? true
DECADES? true
CENTURIES? true
MILLENNIA? true
ERAS? true
FOREVER? false

25. addTo(R temporal, long amount)

Возвращает копию указанного объекта Temporal с добавлением указанного периода.
public <R extends Temporal> R addTo(R temporal, long amount)
Этот метод эквивалентен методу Temporal.plus(long,TemporalUnit). Такой подход рекомендуется.
// Defined in Temporal interface
public Temporal plus​(long amountToAdd, TemporalUnit unit)
Например:
ChronoUnit_addTo_ex1.java
Temporal ym = YearMonth.of(2020, 3); // 2020-03
// Add 10 monthds to ym.
YearMonth ym2 = (YearMonth) ChronoUnit.MONTHS.addTo(ym, 10);

System.out.println("ym2: " + ym2); // 2021-01

26. between(Temporal, Temporal)

Возвращает промежуток времени между двумя объектами Temporal. Эта единица должна поддерживаться обоими объектами Temporal, в противном случае будет выдано исключение.
public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
Этот метод эквивалентен использованию метода Temporal.until(Temporal,TemporalUnit),
// Defined in Temporal interface
public long until​(Temporal endExclusive, TemporalUnit unit)
Например:
ChronoUnit_between_ex1.java
LocalDate from = LocalDate.of(2020, 3, 15);
LocalDate to = LocalDate.of(2020, 3, 17);

long days = ChronoUnit.DAYS.between(from, to);
System.out.println("days: " + days); // 2
Например:
ChronoUnit_between_ex2.java
YearMonth from = YearMonth.of(2020, 7);
LocalDateTime to = LocalDateTime.of(2021, 3, 17, 13, 45, 30);

long months = ChronoUnit.MONTHS.between(from, to);
System.out.println("months: " + months); // 8