Clase Period de Java

PeriodLa clase Period es parte de una API de fecha y hora introducida en Java 8, ubicada en eljava.timepaquete java.time.

La clase Period se utiliza principalmente para representar el intervalo de tiempo entre dos fechas, en unidades de años, meses y días. A diferencia de laDurationclase Duration (que representa intervalos basados en tiempo, como horas, minutos y segundos),Periodse centra en las diferencias a nivel de fecha.

Características principales

1. Inmutabilidad

PeriodLa clase Period es inmutable, lo que significa que una vez que se crea unPeriodobjeto Period, su valor no puede ser modificado. Cualquier operaciónPeriodsobre un Period (como suma o resta) devolverá una nuevaPeriodinstancia.

2. Cálculo basado en fechas

PeriodSe especializa en el cálculo de años, meses y días, adecuado para escenarios como cumpleaños, duración de contratos, etc.

3. Integración con LocalDate

PeriodNormalmente se usa junto con laLocalDateclase LocalDate para calcular la diferencia entre dos fechas o añadir/restar un período de tiempo a una fecha.

Métodos comunes

Crear objetos Period

1. Usando elof()método of().

Ejemplo

Period period = Period.of(1, 2, 3); // 1 año 2 meses 3 días

2. Usando elbetween()método between() para calcular el intervalo entre dos fechas.

Ejemplo

LocalDate startDate = LocalDate.of(2020, 1, 1);
LocalDate endDate = LocalDate.of(2021, 3, 4);
Period period = Period.between(startDate, endDate);

3. Usando elparse()método parse() para crear desde una cadena.

Ejemplo

Period period = Period.parse("P1Y2M3D"); // Formato ISO-8601

Obtener las partes de un Period

Ejemplo

int years = period.getYears();  // Obtener el número de años
int months = period.getMonths(); // Obtener el número de meses
int days = period.getDays();    // Obtener el número de días

Operaciones

1. Operaciones de suma y resta

Ejemplo

Period added = period.plusYears(1).plusMonths(2);
Period subtracted = period.minusDays(5);

2. Comprobar si es negativo

Ejemplo

boolean isNegative = period.isNegative();

3. Normalizar un Period

Ejemplo

Period normalized = period.normalized(); // Convertir los meses que superen 12 en años

Ejemplos de aplicación práctica

Calcular el intervalo entre dos fechas

Ejemplo

LocalDate birthDate = LocalDate.of(1990, 5, 15);
LocalDate currentDate = LocalDate.now();
Period age = Period.between(birthDate, currentDate);
System.out.printf("Edad: %d años %d meses %d días",
    age.getYears(), age.getMonths(), age.getDays());

Añadir un Period a una fecha

Ejemplo

LocalDate today = LocalDate.now();
Period twoMonths = Period.ofMonths(2);
LocalDate futureDate = today.plus(twoMonths);

Comprobar si el período está vacío

Ejemplo

Period zeroPeriod = Period.of(0, 0, 0);
if (zeroPeriod.isZero()) {
    System.out.println("Este es un período cero");
}

Ejemplo completo

Ejemplo

import java.time.Period;
import java.time.LocalDate;

public class PeriodDemo {
    public static void main(String[] args) {
        // Varias formas de crear un objeto Period
       
        // 1. Usando el método of()
        Period period1 = Period.of(1, 2, 15); // 1 año 2 meses 15 días
        System.out.println("Period 1: " + period1);
       
        // 2. Usando el método between() para calcular el período entre dos fechas
        LocalDate startDate = LocalDate.of(2020, 1, 1);
        LocalDate endDate = LocalDate.of(2023, 5, 15);
        Period period2 = Period.between(startDate, endDate);
        System.out.println("Period between dates: " + period2);
       
        // 3. Usando el método parse() para crear desde una cadena
        Period period3 = Period.parse("P1Y2M15D"); // Formato ISO-8601
        System.out.println("Parsed Period: " + period3);
    }
}

El resultado es:

Period 1: P1Y2M15D
Period between dates: P3Y4M14D
Parsed Period: P1Y2M15D

Notas

  1. Problemas de precisión：PeriodSolo calcula las diferencias de años, meses y días; no considera las diferencias de tiempo (horas, minutos, etc.).
  2. Manejo de valores negativos: si la fecha de finalización es anterior a la fecha de inicio,Period.between()devolverá un valor negativo.
  3. Diferencias en los días de los meses：PeriodEl cálculo considera las diferencias en el número de días de los distintos meses (por ejemplo, febrero tiene 28 o 29 días).
  4. Formato ISO-8601: al usar elparse()método parse(), la cadena debe seguir elPnYnMnDformato ISO-8601 (como "P1Y2M3D").

Resumen

PeriodLa clase Period es una herramienta poderosa en la API de fecha y hora de Java para manejar intervalos basados en fechas. A través de ella, los desarrolladores pueden realizar fácilmente cálculos de fechas a nivel de año, mes y día, especialmente adecuada para escenarios de negocio que requieren precisión a nivel de fecha. Dominar elPerioduso de la clase Period puede hacer que tu código de manejo de fechas sea más conciso y legible.

Otras extensiones