CKTIS / Java
ZonedDateTime: criação, conversão, formatação e alterações de calendário
Cria datas e horas com fuso horário, converte-as sem mudar o instante, formata-as e altera campos locais tendo em conta as mudanças da hora.
Versão: Java SE 21
Sintaxe
java.time.ZonedDateTime — Java SE 21
static ZonedDateTime of(LocalDateTime dateTime, ZoneId zone)
static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone)
static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
static ZonedDateTime ofInstant(Instant instant, ZoneId zone)
static ZonedDateTime ofInstant(LocalDateTime dateTime, ZoneOffset offset, ZoneId zone)
Instant toInstant() // inherited from ChronoZonedDateTime
ZonedDateTime withZoneSameInstant(ZoneId zone)
String format(DateTimeFormatter formatter)
ZonedDateTime with(TemporalAdjuster adjuster)
ZonedDateTime with(TemporalField field, long newValue)
ZonedDateTime withHour(int hour)
ZonedDateTime withMinute(int minute)java.time.ZonedDateTime guarda uma data e hora locais, um identificador de fuso horário e o desvio em relação a UTC determinado para esse valor. O método estático ZonedDateTime.of aceita um LocalDateTime, um par LocalDate e LocalTime ou sete inteiros (de year a nanoOfSecond), sempre com um ZoneId. Se o relógio avançar e a hora local cair num intervalo saltado, a data e hora locais avançam pela duração desse intervalo. Se a hora local se repetir, é escolhido o desvio que corresponde ao primeiro instante. Campos numéricos inválidos ou uma data impossível originam DateTimeException.
ZonedDateTime.ofInstant(Instant, ZoneId) determina a data, a hora e o desvio do instante no fuso de destino. A sobrecarga (LocalDateTime, ZoneOffset, ZoneId) determina primeiro o instante a partir da data e hora locais e do desvio indicados, e depois representa-o no fuso de destino. Tanto a hora local como o desvio podem diferir dos valores fornecidos. O método herdado ZonedDateTime.toInstant() devolve o mesmo instante sem informação sobre o fuso. ZonedDateTime.withZoneSameInstant(ZoneId) mantém o instante, mas pode alterar a data e hora locais. Já withZoneSameLocal tenta manter a data e hora locais e pode alterar o instante.
ZonedDateTime.format(DateTimeFormatter) devolve uma String sem modificar o objeto. ISO_OFFSET_DATE_TIME apresenta a data e hora locais e o desvio, mas não o identificador de um fuso regional. Se a formatação falhar, o método lança DateTimeException.
ZonedDateTime.with(TemporalAdjuster) aplica uma regra, como TemporalAdjusters.lastDayOfMonth(). A sobrecarga with(TemporalField, long) define um campo suportado, como ChronoField.MONTH_OF_YEAR. INSTANT_SECONDS define o segundo na linha temporal, mantendo o fuso e a fração de segundo. OFFSET_SECONDS só permite escolher o outro desvio válido quando a hora local se repete. Um campo não suportado pode originar UnsupportedTemporalTypeException; um valor inválido pode originar DateTimeException.
ZonedDateTime.withHour(int) define a hora (0–23) e ZonedDateTime.withMinute(int) define o minuto (0–59); nenhum destes métodos soma tempo decorrido. Valores fora dos limites originam DateTimeException. Ao alterar campos locais, o fuso mantém-se, mas o instante pode mudar. Num intervalo saltado, o resultado avança pela duração desse intervalo. Quando a hora se repete, conserva-se o desvio anterior se for válido; caso contrário, escolhe-se o primeiro instante. Os objetos são imutáveis, por isso guarda o resultado devolvido.
Exemplos
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoField;
import java.time.temporal.TemporalAdjusters;
public class Main {
public static void main(String[] args) {
ZoneOffset east = ZoneOffset.of("+01:00");
ZoneOffset west = ZoneOffset.of("-05:00");
DateTimeFormatter iso = DateTimeFormatter.ISO_OFFSET_DATE_TIME;
ZonedDateTime original = ZonedDateTime.of(
LocalDateTime.of(2024, 1, 15, 10, 30), east);
Instant instant = original.toInstant();
ZonedDateTime converted = original.withZoneSameInstant(west);
ZonedDateTime rebuilt = ZonedDateTime.ofInstant(instant, west);
ZonedDateTime edited = original.with(ChronoField.MONTH_OF_YEAR, 2)
.with(TemporalAdjusters.lastDayOfMonth())
.withHour(14)
.withMinute(45);
System.out.println(original.format(iso));
System.out.println(instant);
System.out.println(converted.format(iso));
System.out.println(converted.equals(rebuilt));
System.out.println(edited.format(iso));
}
}Resultado
2024-01-15T10:30:00+01:00 2024-01-15T09:30:00Z 2024-01-15T04:30:00-05:00 true 2024-02-29T14:45:00+01:00
As três primeiras linhas representam o mesmo instante. `true` mostra que as duas conversões para `-05:00` coincidem. A última linha mostra a alteração para 29 de fevereiro às 14:45 com o desvio original. Os desvios fixos tornam o exemplo independente das regras dos fusos regionais.
Lições relacionadas
- Java · Lição 59 · Intermédio · Versão: 2