Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / Java

ZonedDateTime: creazione, conversione, formattazione e modifiche di calendario

Crea date e orari con fuso, convertili senza cambiare l’istante, formattali e modifica i campi locali tenendo conto dei cambi d’ora.

Versione: Java SE 21

Sintassi

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 memorizza data e ora locali, un identificatore di fuso e lo scostamento determinato rispetto a UTC. Il metodo statico ZonedDateTime.of accetta un LocalDateTime, una coppia LocalDate e LocalTime oppure sette interi (da year a nanoOfSecond), sempre con un ZoneId. Se l’ora locale cade in un intervallo saltato quando l’orologio avanza, viene spostata in avanti della durata dell’intervallo. Se l’ora locale si ripete, viene scelto lo scostamento corrispondente all’istante precedente. Campi numerici non validi o una data impossibile causano DateTimeException.

ZonedDateTime.ofInstant(Instant, ZoneId) ricava data, ora e scostamento dell’istante nel fuso di destinazione. L’overload (LocalDateTime, ZoneOffset, ZoneId) determina prima l’istante a partire da data, ora e scostamento forniti, poi lo rappresenta nel fuso di destinazione. L’ora locale e lo scostamento possono quindi essere diversi da quelli in ingresso. Il metodo ereditato ZonedDateTime.toInstant() restituisce lo stesso istante senza informazioni sul fuso. ZonedDateTime.withZoneSameInstant(ZoneId) conserva l’istante, ma può cambiare data e ora locali. Al contrario, withZoneSameLocal cerca di conservare data e ora locali e può cambiare l’istante.

ZonedDateTime.format(DateTimeFormatter) restituisce una String senza modificare l’oggetto. ISO_OFFSET_DATE_TIME mostra data e ora locali e scostamento, ma non l’identificatore del fuso regionale. Se la formattazione non riesce, il metodo genera DateTimeException.

ZonedDateTime.with(TemporalAdjuster) applica una regola, come TemporalAdjusters.lastDayOfMonth(). L’overload with(TemporalField, long) imposta un campo supportato, come ChronoField.MONTH_OF_YEAR. INSTANT_SECONDS imposta il secondo sulla linea temporale mantenendo il fuso e la frazione di secondo. OFFSET_SECONDS può solo selezionare l’altro scostamento valido quando l’ora locale si ripete. Un campo non supportato può causare UnsupportedTemporalTypeException; un valore non valido può causare DateTimeException.

ZonedDateTime.withHour(int) imposta l’ora (0–23) e ZonedDateTime.withMinute(int) il minuto (0–59); nessuno dei due aggiunge tempo trascorso. I valori fuori intervallo causano DateTimeException. Quando si modificano i campi locali, il fuso resta invariato, ma l’istante può cambiare. In un intervallo saltato, il risultato avanza della durata dell’intervallo. Se l’ora si ripete, si mantiene lo scostamento precedente se ancora valido; altrimenti si sceglie il primo istante. Gli oggetti sono immutabili: conserva il risultato restituito.

Esempi

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));
    }
}

Risultato

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

Le prime tre righe rappresentano lo stesso istante. `true` mostra che le due conversioni a `-05:00` coincidono. L’ultima riga mostra la modifica al 29 febbraio alle 14:45 con lo scostamento originale. Gli scostamenti fissi rendono l’esempio indipendente dalle regole dei fusi regionali.

Lezioni correlate

  • Java · Lezione 59 · Intermedio · Versione: 2

Fonti