Классы Duration и Period в Java

Duration — это класс java.time.Duration, который хранит точный промежуток времени в секундах и наносекундах, например PT1H30M (1 час 30 минут) или PT12.87656S. Его пара — Period (java.time.Period): промежуток в календарных годах, месяцах и днях, например P5Y2M9D. Оба класса появились в Java 8, неизменяемы и потокобезопасны.

Прибавьте к полудню субботы 30 марта 2024 года в Берлине Period.ofDays(1) и Duration.ofDays(1): первый вариант даст воскресенье 12:00, второй — 13:00. В ночь на 31 марта часы перевели вперёд, в календарных сутках оказалось 23 часа, и только Period это учёл. Поэтому выбор между классами — не вопрос вкуса.

Duration и Period: в чём разница

Duration измеряет физическое время: сутки в нём — ровно 86 400 секунд. Period измеряет календарное время: месяц может длиться 28–31 день, а день — 23 или 25 часов при переводе часов. Используйте Duration для тайм-аутов и длительности операций, Period — для возраста, сроков договора и «через 2 месяца».

Пример из начала урока целиком — 31 марта 2024 года в Германии часы перевели с 02:00 на 03:00:

import java.time.Duration;
import java.time.Period;
import java.time.ZoneId;
import java.time.ZonedDateTime;

public class DurationVsPeriodExample {
    public static void main(String[] args) {
        ZonedDateTime base = ZonedDateTime.of(2024, 3, 30, 12, 0, 0, 0, ZoneId.of("Europe/Berlin"));

        System.out.println(base);
        System.out.println(base.plus(Period.ofDays(1)));
        System.out.println(base.plus(Duration.ofDays(1)));
    }
}

2024-03-30T12:00+01:00[Europe/Berlin]
2024-03-31T12:00+02:00[Europe/Berlin]
2024-03-31T13:00+02:00[Europe/Berlin]

Period.ofDays(1) сдвинул календарную дату и оставил 12:00, а Duration.ofDays(1) прибавил 24 реальных часа, которые из-за пропущенного часа закончились в 13:00. Оба класса реализуют интерфейс TemporalAmount, поэтому передаются в один и тот же метод plus(). Обзор всех классов пакета — в уроке Дата и время в Java.

Класс Duration: создание через of*()

Объект Duration создают статическими методами: ofDays(), ofHours(), ofMinutes(), ofSeconds(), ofMillis(), ofNanos() и универсальным of(количество, ChronoUnit). Конструктора у класса нет. Значение может быть отрицательным, а нулевая длительность доступна как константа Duration.ZERO.

Пример создания объектов класса java.time.Duration:

import java.time.Duration;
import java.time.temporal.ChronoUnit;

public class DurationExample1 {
    public static void main(String[] args) {
        Duration oneDay = Duration.ofDays(1);
        Duration oneHour = Duration.ofHours(1);
        Duration oneMin = Duration.ofMinutes(1);
        Duration tenSeconds = Duration.ofSeconds(10);
        Duration twoSeconds = Duration.ofSeconds(1, 1_000_000_000);
        Duration oneSecondFromMillis = Duration.ofMillis(1000);
        Duration oneSecondFromNanos = Duration.ofNanos(1_000_000_000);
        Duration oneSecond = Duration.of(1, ChronoUnit.SECONDS);
        Duration ninetySeconds = Duration.ofSeconds(90);
        Duration oneAndHalfSeconds = Duration.ofMillis(1500);
        Duration minusNinety = Duration.ofSeconds(-90);

        System.out.println("oneDay: " + oneDay);
        System.out.println("oneHour: " + oneHour);
        System.out.println("oneMin: " + oneMin);
        System.out.println("tenSeconds: " + tenSeconds);
        System.out.println("twoSeconds: " + twoSeconds);
        System.out.println("oneSecondFromMillis: " + oneSecondFromMillis);
        System.out.println("oneSecondFromNanos: " + oneSecondFromNanos);
        System.out.println("oneSecond: " + oneSecond);
        System.out.println("ninetySeconds: " + ninetySeconds);
        System.out.println("oneAndHalfSeconds: " + oneAndHalfSeconds);
        System.out.println("minusNinety: " + minusNinety);
    }
}

oneDay: PT24H
oneHour: PT1H
oneMin: PT1M
tenSeconds: PT10S
twoSeconds: PT2S
oneSecondFromMillis: PT1S
oneSecondFromNanos: PT1S
oneSecond: PT1S
ninetySeconds: PT1M30S
oneAndHalfSeconds: PT1.5S
minusNinety: PT-1M-30S

Обратите внимание на первую строку: Duration.ofDays(1) выводится как PT24H. Внутри хранятся только секунды, и toString() никогда не показывает дни. Во второй форме ofSeconds(1, 1_000_000_000) лишний миллиард наносекунд превращается в целую секунду — получается PT2S.

Метод of() принимает только единицы с точной длиной — от NANOS до DAYS. Месяц или год разной длины в Duration не помещается:

Duration.of(1, ChronoUnit.DAYS);   // PT24H
Duration.of(1, ChronoUnit.MONTHS); // UnsupportedTemporalTypeException: Unit must not have an estimated duration

Duration.between: длительность между двумя моментами

Duration.between(start, end) возвращает точное время между двумя значениями, у которых есть время суток: LocalTime, LocalDateTime, ZonedDateTime или Instant. Если end раньше start, длительность будет отрицательной. Для LocalDate метод не работает — у даты нет секунд.

Пример расчёта длительности рабочего дня:

import java.time.Duration;
import java.time.LocalDate;
import java.time.LocalTime;

public class DurationBetweenExample {
    public static void main(String[] args) {
        LocalTime start = LocalTime.of(9, 15);
        LocalTime end = LocalTime.of(17, 45, 30);

        Duration work = Duration.between(start, end);
        System.out.println(work);                         // PT8H30M30S
        System.out.println(work.toMinutes());             // 510
        System.out.println(Duration.between(end, start)); // PT-8H-30M-30S

        LocalDate d1 = LocalDate.of(2024, 1, 1);
        LocalDate d2 = LocalDate.of(2024, 1, 2);
        System.out.println(Duration.between(d1.atStartOfDay(), d2.atStartOfDay())); // PT24H
        Duration.between(d1, d2); // UnsupportedTemporalTypeException: Unsupported unit: Seconds
    }
}

Если нужно одно число в конкретных единицах, а не объект, подойдёт ChronoUnit.MINUTES.between(start, end) — он тоже вернёт 510. Разница между двумя Instant разобрана в уроке Класс Instant, между LocalDateTime — в уроке LocalDateTime. Для замера времени выполнения кода берут System.nanoTime() — см. LocalTime.now() и System.nanoTime().

Получение секунд и минут, формат «чч:мм:сс»

Методы to*() переводят всю длительность в одну единицу: toHours(), toMinutes(), toMillis(), toNanos(), а также getSeconds(). Методы to*Part() (Java 9+) возвращают отдельную часть: toHoursPart(), toMinutesPart(), toSecondsPart(). Дробная часть при переводе отбрасывается.

Пример для длительности 2 часа 30 минут 30,5 секунды:

import java.time.Duration;
import java.time.temporal.ChronoUnit;

public class DurationGetExample {
    public static void main(String[] args) {
        Duration d = Duration.ofSeconds(9030, 500_000_000);

        System.out.println(d);                          // PT2H30M30.5S
        System.out.println(d.getSeconds());             // 9030
        System.out.println(d.getNano());                // 500000000
        System.out.println(d.toDays());                 // 0
        System.out.println(d.toHours());                // 2
        System.out.println(d.toMinutes());              // 150
        System.out.println(d.toMillis());               // 9030500
        System.out.println(d.get(ChronoUnit.SECONDS));  // 9030

        // Java 9+
        System.out.println(d.toSeconds());              // 9030
        System.out.println(d.toHoursPart());            // 2
        System.out.println(d.toMinutesPart());          // 30
        System.out.println(d.toSecondsPart());          // 30
        System.out.println(d.toMillisPart());           // 500
    }
}

getSeconds() — это все 9030 секунд, а не «секунды на циферблате». Универсальный get() поддерживает только ChronoUnit.SECONDS и ChronoUnit.NANOS: d.get(ChronoUnit.MINUTES) выбросит UnsupportedTemporalTypeException: Unsupported unit: Minutes.

Готового форматтера для Duration нет: DateTimeFormatter работает с датами и временем суток, а не с промежутками. Строку вида «02:30:30» собирают из частей:

Duration d = Duration.ofSeconds(9030);
Duration big = Duration.ofSeconds(100_000);

// Java 9+
String hms = String.format("%02d:%02d:%02d", d.toHours(), d.toMinutesPart(), d.toSecondsPart());
// Java 8
String hms8 = String.format("%02d:%02d:%02d", d.toHours(), d.toMinutes() % 60, d.getSeconds() % 60);
String bigHms = String.format("%02d:%02d:%02d", big.toHours(), big.toMinutesPart(), big.toSecondsPart());

System.out.println(hms);    // 02:30:30
System.out.println(hms8);   // 02:30:30
System.out.println(big);    // PT27H46M40S
System.out.println(bigHms); // 27:46:40

Иногда советуют трюк LocalTime.MIDNIGHT.plus(d).format(...). Он работает только для длительностей меньше суток: для big время «перевалит» через полночь и покажет 03:46:40. Шаблоны дат и времени разобраны в уроке Класс DateTimeFormatter.

Изменение и сравнение Duration

Длительность изменяют методами plus*() и minus*() (дни, часы, минуты, секунды, миллисекунды, наносекунды или другой Duration), а также multipliedBy(), dividedBy(), negated() и abs(). Методы withSeconds() и withNanos() заменяют значение целиком. Каждый вызов возвращает новый объект — результат нужно присвоить.

Пример арифметики с длительностью в 1 час:

import java.time.Duration;

public class DurationPlusExample {
    public static void main(String[] args) {
        Duration base = Duration.ofHours(1);

        System.out.println(base.plusMinutes(30));              // PT1H30M
        System.out.println(base.plusSeconds(15));              // PT1H15S
        System.out.println(base.plusMillis(500));              // PT1H0.5S
        System.out.println(base.plusDays(1));                  // PT25H
        System.out.println(base.plus(Duration.ofMinutes(45))); // PT1H45M
        System.out.println(base.minusMinutes(90));             // PT-30M
        System.out.println(base.multipliedBy(3));              // PT3H
        System.out.println(base.dividedBy(4));                 // PT15M
        System.out.println(base.negated());                    // PT-1H
        System.out.println(base.minusMinutes(90).abs());       // PT30M

        // Сколько 15-минутных слотов в 2 часах (Java 9+)
        System.out.println(Duration.ofHours(2).dividedBy(Duration.ofMinutes(15))); // 8

        System.out.println(Duration.ofMinutes(5).withSeconds(10));        // PT10S
        System.out.println(Duration.ofMinutes(5).withNanos(500_000_000)); // PT5M0.5S
    }
}

Неочевидный момент — withSeconds(10): он не меняет «секунды» внутри 5 минут, а заменяет всю длительность на 10 секунд. Нулевые минуты toString() пропускает, поэтому 1 час 15 секунд выводится как PT1H15S.

Для сравнения длительностей служат equals(), compareTo() (класс реализует Comparable<Duration>), isZero(), isNegative() и с Java 18 — isPositive():

import java.time.Duration;

public class DurationCompareExample {
    public static void main(String[] args) {
        Duration a = Duration.ofMinutes(90);
        Duration b = Duration.ofHours(1).plusMinutes(30);
        Duration c = Duration.ofHours(2);

        System.out.println(a.equals(b));                      // true
        System.out.println(a.compareTo(c) < 0);              // true
        System.out.println(a.minus(c).isNegative());          // true
        System.out.println(a.minus(b).isZero());              // true
        System.out.println(Duration.ofHours(1).equals(Duration.ofMinutes(60))); // true
    }
}

Две длительности равны, если равно общее количество секунд и наносекунд, — неважно, каким методом их создали. Результат compareTo() сравнивайте с нулём, а не с -1.

Класс Period: создание через of*()

java.time.Period хранит промежуток в годах, месяцах и днях, например 5 лет, 2 месяца и 9 дней (P5Y2M9D). Создают его методами of(годы, месяцы, дни), ofYears(), ofMonths(), ofWeeks(), ofDays(); нулевой период — Period.ZERO. Значения не нормализуются: 14 месяцев так и останутся 14 месяцами.

Пример создания объектов класса Period:

import java.time.Period;

public class PeriodExample1 {
    public static void main(String[] args) {
        Period period5y4m3d = Period.of(5, 4, 3);
        Period period2d = Period.ofDays(2);
        Period period2m = Period.ofMonths(2);
        Period period14d = Period.ofWeeks(2);
        Period period2y = Period.ofYears(2);
        Period period14m40d = Period.of(0, 14, 40);

        System.out.println(period5y4m3d);   // P5Y4M3D
        System.out.println(period2d);       // P2D
        System.out.println(period2m);       // P2M
        System.out.println(period14d);      // P14D
        System.out.println(period2y);       // P2Y
        System.out.println(period14m40d);   // P14M40D
        System.out.println(Period.ZERO);    // P0D
    }
}

Недель внутри Period нет: ofWeeks(2) сразу превращается в 14 дней. Дни, в свою очередь, никогда не пересчитываются в месяцы, потому что длина месяца заранее неизвестна.

Period.between и ChronoUnit.between

Period.between(начало, конец) возвращает разницу между двумя LocalDate в виде «N лет, M месяцев, K дней»: сначала считаются полные месяцы, затем оставшиеся дни. Конечная дата в подсчёт не входит. Если нужно одно число — всего дней или месяцев, — используйте ChronoUnit.DAYS.between() или ChronoUnit.MONTHS.between().

Пример: разница между датами и расчёт возраста:

import java.time.LocalDate;
import java.time.Period;
import java.time.temporal.ChronoUnit;

public class PeriodExample2 {
    public static void main(String[] args) {
        LocalDate march2003 = LocalDate.of(2003, 3, 1);
        LocalDate may2003 = LocalDate.of(2003, 5, 1);
        System.out.println(Period.between(march2003, may2003)); // P2M
        System.out.println(Period.between(may2003, march2003)); // P-2M

        LocalDate birthday = LocalDate.of(1990, 8, 25);
        LocalDate today = LocalDate.of(2024, 3, 15);
        Period age = Period.between(birthday, today);
        System.out.println(age);                                    // P33Y6M19D
        System.out.println("Полных лет: " + age.getYears());        // Полных лет: 33
        System.out.println(ChronoUnit.YEARS.between(birthday, today)); // 33
    }
}

Что выведет этот код? С 31 января до 1 марта 2024 года прошло 30 дней, но Period видит это иначе:

LocalDate start = LocalDate.of(2024, 1, 31);
LocalDate end = LocalDate.of(2024, 3, 1);

Period p = Period.between(start, end);
System.out.println(p);                                    // P1M1D
System.out.println(p.getDays());                          // 1
System.out.println(ChronoUnit.DAYS.between(start, end));  // 30
System.out.println(ChronoUnit.MONTHS.between(start, end)); // 1
System.out.println(start.until(end));                     // P1M1D

От 31 января один месяц — это 29 февраля (последний день короткого месяца), и до 1 марта остаётся 1 день. Поэтому getDays() возвращает только «хвост» дней, а не общее количество. Для «сколько дней между датами» нужен ChronoUnit.DAYS.between() — подробнее в уроке LocalDate: сколько дней между двумя датами. Метод Period.between() принимает только LocalDate; для LocalDateTime сначала вызовите toLocalDate().

Методы Period: get, with, plus, minus, normalized

Части периода читают методами getYears(), getMonths(), getDays() и get(ChronoUnit), заменяют — withYears(), withMonths(), withDays(), сдвигают — plus*() и minus*(). Метод normalized() переводит лишние месяцы в годы, а toTotalMonths() возвращает общее число месяцев.

Пример использования методов get класса Period:

import java.time.Period;
import java.time.temporal.ChronoUnit;

public class PeriodExample3 {
    public static void main(String[] args) {
        Period period5y4m3d = Period.of(5, 4, 3);
        int days = period5y4m3d.getDays();
        int months = period5y4m3d.getMonths();
        int years = period5y4m3d.getYears();
        long days2 = period5y4m3d.get(ChronoUnit.DAYS);

        System.out.println("Дни: " + days);
        System.out.println("Месяцы: " + months);
        System.out.println("Годы: " + years);
        System.out.println("Дни: " + days2);
        System.out.println("Всего месяцев: " + period5y4m3d.toTotalMonths());
        System.out.println("Единицы: " + period5y4m3d.getUnits());
    }
}

Дни: 3
Месяцы: 4
Годы: 5
Дни: 3
Всего месяцев: 64
Единицы: [Years, Months, Days]

get() понимает только YEARS, MONTHS и DAYS: period.get(ChronoUnit.WEEKS) выбросит UnsupportedTemporalTypeException: Unsupported unit: Weeks.

Для изменения года, месяца или дня используются методы with класса Period:

import java.time.Period;

public class PeriodExample4 {
    public static void main(String[] args) {
        Period period2d = Period.ofDays(2);
        Period period8d = period2d.withDays(8);
        Period period2y1m2d = period2d.withYears(2).withMonths(1);

        System.out.println(period2d);      // P2D
        System.out.println(period8d);      // P8D
        System.out.println(period2y1m2d);  // P2Y1M2D
    }
}

Для добавления или вычитания лет, месяцев или дней используются методы plus и minus класса Period:

import java.time.Period;

public class PeriodExample5 {
    public static void main(String[] args) {
        Period period5y4m3d = Period.of(5, 4, 3);
        Period period2y = Period.ofYears(2);

        // Добавление
        System.out.println(period5y4m3d.plusYears(4));    // P9Y4M3D
        System.out.println(period5y4m3d.plusMonths(3));   // P5Y7M3D
        System.out.println(period5y4m3d.plusDays(3));     // P5Y4M6D
        System.out.println(period5y4m3d.plus(period2y));  // P7Y4M3D

        // Вычитание
        System.out.println(period5y4m3d.minusYears(2));   // P3Y4M3D
        System.out.println(period5y4m3d.minusMonths(1));  // P5Y3M3D
        System.out.println(period5y4m3d.minusDays(1));    // P5Y4M2D
        System.out.println(period5y4m3d.minus(period2y)); // P3Y4M3D

        // Умножение и смена знака
        System.out.println(period5y4m3d.multipliedBy(2)); // P10Y8M6D
        System.out.println(period5y4m3d.negated());       // P-5Y-4M-3D
    }
}

В plus() можно передать только «календарную» величину: Period.ofDays(1).plus(Duration.ofHours(2)) выбросит DateTimeException: Unit must be Years, Months or Days, but was Seconds.

Метод normalized() пересчитывает месяцы сверх 12 в годы, но дни не трогает:

System.out.println(Period.of(1, 14, 40).normalized());              // P2Y2M40D
System.out.println(Period.of(1, -1, 0).normalized());               // P11M
System.out.println(Period.ofMonths(12).equals(Period.ofYears(1)));  // false
System.out.println(Period.ofMonths(12).normalized().equals(Period.ofYears(1))); // true

В отличие от Duration, equals() у Period сравнивает поля по отдельности: 12 месяцев и 1 год — разные периоды, пока не вызван normalized(). А compareTo() у Period нет совсем — без опорной даты нельзя сказать, что больше: 1 месяц или 30 дней.

parse() и toString(): формат ISO-8601 PT… и P…

Оба класса выводятся и разбираются в формате ISO-8601. Duration записывается как PT + часы H, минуты M, секунды S (например, PT1H30M), Period — как P + годы Y, месяцы M, недели W, дни D (например, P1Y2M3D). Буква T отделяет время от дат: P1M — месяц, PT1M — минута.

Пример разбора строк методами Duration.parse() и Period.parse():

import java.time.Duration;
import java.time.Period;

public class ParseExample {
    public static void main(String[] args) {
        System.out.println(Duration.parse("PT1H30M"));  // PT1H30M
        System.out.println(Duration.parse("PT90M"));    // PT1H30M
        System.out.println(Duration.parse("P2DT3H"));   // PT51H
        System.out.println(Duration.parse("PT-1.5S"));  // PT-1.5S
        System.out.println(Duration.parse("-PT6H3M"));  // PT-6H-3M

        System.out.println(Period.parse("P1Y2M3D"));    // P1Y2M3D
        System.out.println(Period.parse("P2W"));        // P14D
        System.out.println(Period.parse("P1Y2W3D"));    // P1Y17D
        System.out.println(Period.parse("-P1M"));       // P-1M
    }
}

Duration.parse() принимает дни (P2DT3H), но сразу переводит их в часы по 24, поэтому toString() покажет PT51H. Годы и месяцы в Duration недопустимы, а время — в Period. Строки другого вида не разбираются:

Duration.parse("1:30");  // DateTimeParseException: Text cannot be parsed to a Duration
Duration.parse("P1M");   // DateTimeParseException: Text cannot be parsed to a Duration
Period.parse("PT1H");    // DateTimeParseException: Text cannot be parsed to a Period

Где чаще всего ошибаются

Большинство промахов с Duration и Period возникает, когда классы путают между собой или принимают «часть» значения за всё значение. Объекты неизменяемы, поэтому результат plus*() и with*() тоже нужно присваивать. Ниже — типичные случаи и исправления.