Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

Criar, somar e converter valores Duration

Cria uma duração a partir de um número de minutos ou de dois instantes, soma outra duração e obtém o total em minutos ou horas.

Versão: Java SE 21

Sintaxe

import java.time.Duration;
import java.time.temporal.Temporal;
import java.time.temporal.TemporalUnit;

// Static methods declared by Duration
public static Duration between(Temporal startInclusive, Temporal endExclusive)
public static Duration ofMinutes(long minutes)

// Instance methods declared by Duration
public Duration plus(Duration duration)
public Duration plus(long amountToAdd, TemporalUnit unit)
public long toHours()
public long toMinutes()

Em Java SE 21, java.time.Duration representa uma duração imutável com sinal, não uma data nem uma hora do dia. O método de criação estático Duration.ofMinutes(long minutes) cria uma duração a partir de um número de minutos, que pode ser negativo. Cada minuto corresponde a exatamente 60 segundos.

O método estático Duration.between(start, end) calcula a diferença desde o início, incluído, até ao fim, excluído. O resultado é negativo se o fim anteceder o início. Ambos os argumentos têm de suportar a unidade SECONDS. Se os tipos forem diferentes, o cálculo baseia-se no tipo do primeiro argumento. Se não for possível obter a diferença em segundos, o método lança DateTimeException.

Para dois valores Duration, a.plus(b) devolve a soma sem alterar nenhum dos dois; guarda o valor devolvido para usares a soma. A sobrecarga plus(long, TemporalUnit) recebe uma quantidade e uma unidade de duração exata, como ChronoUnit.MINUTES. A exceção é ChronoUnit.DAYS, em que cada dia conta como 24 horas. Uma unidade não suportada provoca UnsupportedTemporalTypeException. ofMinutes, between e ambas as sobrecargas de plus lançam ArithmeticException se o resultado não for representável por Duration.

toMinutes() e toHours() devolvem totais do tipo long, não as componentes de minutos ou horas. Dividem os segundos armazenados por 60 ou 3600, respetivamente, com divisão inteira em direção a zero e sem considerar o campo dos nanossegundos. Para 95 minutos, os totais são 95 e 1, respetivamente, enquanto toMinutesPart() devolve 35.

Exemplos

import java.time.Duration;
import java.time.Instant;

public class Main {
    public static void main(String[] args) {
        Instant start = Instant.parse("2025-01-01T09:00:00Z");
        Instant end = Instant.parse("2025-01-01T10:15:00Z");
        Duration elapsed = Duration.between(start, end);
        Duration extra = Duration.ofMinutes(20);
        Duration total = elapsed.plus(extra);

        System.out.println("elapsed.toMinutes() = " + elapsed.toMinutes());
        System.out.println("total.toMinutes() = " + total.toMinutes());
        System.out.println("total.toHours() = " + total.toHours());
    }
}

Resultado

elapsed.toMinutes() = 75
total.toMinutes() = 95
total.toHours() = 1

Entre os instantes fixados passam 75 minutos. Ao somar 20 minutos, obtêm-se 95 minutos, ou seja, 1 hora inteira. `elapsed` continua a representar 75 minutos.

Lições relacionadas

  • Java · Lição 68 · Básico · Versão: 2

Fontes