Методы ZonedDateTime

Создание экземпляров ZonedDateTime

ZonedDateTime.now(zone?) Создаёт объект, соответствующий текущему моменту времени в указанной временной зоне. Если зона не передана, используется системная.

  • ZonedDateTime.now() — текущий момент в системной зоне
  • ZonedDateTime.now(ZoneId.of("Europe/Paris")) — текущий момент в зоне Парижа

Особенность: формирование происходит на основе системного Instant, который затем интерпретируется в заданной зоне.

ZonedDateTime.of(localDateTime, zone) Создание через локальную дату и время с привязкой к зоне.

  • не выполняет сложной коррекции времени
  • просто интерпретирует LocalDateTime как время в зоне

Пример логики:

  • 2025-05-01T10:00 + Europe/Berlin → фиксированное зональное представление

ZonedDateTime.of(year, month, day, hour, minute, second, nano, zone) Построение объекта из примитивных компонентов даты и времени.

Используется для явного конструирования значений без промежуточных объектов.

ZonedDateTime.ofStrict(localDateTime, zone, zoneOffset) Более строгий вариант создания, требующий согласованности между локальным временем, зоной и смещением.

Если данные не соответствуют правилам зоны (например, при переходе на летнее время), метод выбрасывает исключение.

ZonedDateTime.parse(text, formatter?) Парсинг строки в ZonedDateTime.

  • поддерживает ISO-8601 по умолчанию
  • позволяет использовать кастомные DateTimeFormatter

Примеры формата:

  • 2025-03-10T12:30+03:00[Europe/Moscow]
  • 2025-03-10T12:30Z[UTC]

ZonedDateTime.from(temporal) Создание из любого совместимого временного объекта.

Поддерживает:

  • Instant
  • OffsetDateTime
  • LocalDateTime (с зоной по умолчанию или явно заданной)

Получение компонентов времени

toInstant() Преобразует ZonedDateTime в абсолютный момент времени (UTC).

Ключевая особенность:

  • зона полностью устраняется
  • остаётся только точка на временной шкале

toLocalDateTime() Возвращает локальную дату и время без информации о зоне.

Используется, когда важна только календарная составляющая без смещения.

toLocalDate() Извлекает только дату.

toLocalTime() Извлекает только время суток без даты и зоны.

getZone() Возвращает текущую временную зону объекта (ZoneId).

getOffset() Возвращает смещение относительно UTC, соответствующее зоне в конкретный момент времени.

Работа с временными зонами

withZoneSameInstant(zone) Переводит время в другую зону, сохраняя абсолютный момент времени.

Принцип работы:

  • сохраняется Instant
  • изменяется только представление

Пример логики:

  • 10:00 Europe/Moscow → 09:00 Europe/Berlin (если эквивалентный момент)

Это основной метод корректной конвертации между зонами.

withZoneSameLocal(zone) Меняет зону без изменения локального времени.

Это означает:

  • сохраняется «визуальное» время
  • изменяется интерпретация

Пример:

  • 10:00 Europe/Moscow → 10:00 Europe/Berlin (но это уже другой instant)

Используется редко, в основном для специальных сценариев интерпретации данных.

withFixedOffsetZone() Преобразует ZonedDateTime в представление с фиксированным смещением (Offset), устраняя правила временной зоны.

Результат:

  • теряется информация о DST и правилах региона
  • остаётся только числовое смещение (например +03:00)

Изменение компонентов даты и времени

ZonedDateTime наследует поведение неизменяемых типов: каждый метод возвращает новый объект.

Методы изменения даты:

  • withYear(year)
  • withMonth(month)
  • withDayOfMonth(day)
  • withDayOfYear(dayOfYear)

Методы изменения времени:

  • withHour(hour)
  • withMinute(minute)
  • withSecond(second)
  • withNano(nano)

Особенность: изменение компонентов может повлиять на валидность времени в зоне (например, при переходе на летнее время), что иногда приводит к сдвигу или исключению.

Арифметика времени

Все методы возвращают новый ZonedDateTime и работают через корректировку Instant.

Добавление времени:

  • plusYears(value)
  • plusMonths(value)
  • plusWeeks(value)
  • plusDays(value)
  • plusHours(value)
  • plusMinutes(value)
  • plusSeconds(value)
  • plusNanos(value)

Вычитание времени:

  • minusYears(value)
  • minusMonths(value)
  • minusWeeks(value)
  • minusDays(value)
  • minusHours(value)
  • minusMinutes(value)
  • minusSeconds(value)
  • minusNanos(value)

Особенность ZonedDateTime:

  • при арифметике учитываются правила временной зоны
  • переходы DST корректируют результат автоматически

Сравнение и проверка времени

isBefore(other) Проверяет, происходит ли момент раньше другого.

isAfter(other) Проверяет, происходит ли момент позже другого.

compareTo(other) Возвращает:

  • отрицательное число — раньше
  • 0 — равны
  • положительное — позже

Сравнение выполняется по Instant, а не по локальному времени.

equals(other) Сравнивает точное совпадение:

  • момент времени
  • зона
  • локальные значения

Важно: два объекта с одинаковым instant, но разными зонами могут быть не равны.

Форматирование

format(formatter) Преобразует ZonedDateTime в строку.

Использует DateTimeFormatter.

Примеры использования:

  • ISO форматирование
  • пользовательские шаблоны (день, месяц, зона)

Особенности:

  • можно включать идентификатор зоны
  • можно отображать смещение или полное имя зоны

Внутренние преобразования и совместимость

toOffsetDateTime() Преобразует ZonedDateTime в OffsetDateTime.

Отличие:

  • сохраняется только фиксированное смещение
  • теряется региональная зона

truncatedTo(unit) Обрезает время до указанной точности:

  • часы
  • минуты
  • секунды

Пример:

  • 12:34:56 → 12:00:00 (при обрезке до часов)

Работа с временными интервалами и корректировками

ZonedDateTime поддерживает TemporalAdjuster, что позволяет выполнять сложные трансформации:

  • переход к первому дню месяца
  • переход к последнему дню года
  • вычисление ближайшего рабочего дня

Метод:

  • with(adjuster)

Особенности поведения в контексте временных зон

ZonedDateTime объединяет три слоя:

  • LocalDateTime — календарное представление
  • ZoneId — правила региона
  • Instant — абсолютная точка времени

При каждом изменении происходит пересчёт одного из слоёв относительно других.

Ключевые последствия:

  • арифметика всегда приводит к корректировке instant

  • смена зоны может изменить локальное время

  • переходы DST могут вызывать:

    • пропущенные часы
    • повторяющиеся интервалы времени

Ключевые группы методов

Конструкторы и парсинг

  • now
  • of
  • ofStrict
  • parse
  • from

Преобразования

  • toInstant
  • toLocalDateTime
  • toLocalDate
  • toLocalTime
  • toOffsetDateTime

Работа с зонами

  • getZone
  • withZoneSameInstant
  • withZoneSameLocal
  • withFixedOffsetZone

Арифметика

  • plus*
  • minus*

Модификация

  • with* (дата, время)

Сравнение

  • isBefore
  • isAfter
  • compareTo
  • equals

Форматирование

  • format
Оглавление