devstory

Le Tutoriel de Java ChronoUnit

  1. ChronoUnit
  2. ChronoUnit Values
  3. ChronoUnit methods
  4. CENTURIES
  5. DAYS
  6. DECADES
  7. ERAS
  8. FOREVER
  9. HALF_DAYS
  10. HOURS
  11. MICROS
  12. MILLENNIA
  13. MILLIS
  14. MINUTES
  15. MONTHS
  16. NANOS
  17. SECONDS
  18. WEEKS
  19. YEARS
  20. getDuration()
  21. isDurationEstimated()
  22. isDateBased()
  23. isTimeBased()
  24. isSupportedBy(Temporal)
  25. addTo(R temporal, long amount)
  26. between(Temporal, Temporal)

1. ChronoUnit

ChronoUnit est une enum qui implémente l'interface TemporalUnit, laquelle fournit les unités standard utilisées dans le Java Date Time API. En règle générale, ces unités sont suffisantes pour être utilisées. Cependant, si vous souhaitez avoir une unité personnalisée, il faut écrire une classe qui implémente l'interface TemporalUnit.
public enum ChronoUnit implements TemporalUnit
  • TemporalField
  • TemporalUnit
  • ChronoField
Ces unités sont destinées à appliquer dans plusieurs systèmes de calendrier. Par exemple, la plupart des systèmes de calendrier «non-ISO» définissent des unités d'années, de mois et de jours, avec des règles légèrement différentes. La documentation de chaque unité explique son fonctionnement.

2. ChronoUnit Values

Enum
Display Name
Estimated Duration
NANOS
Nanos
Duration.ofNanos(1)
MICROS
Micros
Duration.ofNanos(1000)
MILLIS
Millis
Duration.ofNanos(1000_000)
SECONDS
Seconds
Duration.ofSeconds(1)
MINUTES
Minutes
Duration.ofSeconds(60)
HOURS
Hours
Duration.ofSeconds(3600)
HALF_DAYS
HalfDays
Duration.ofSeconds(43200)
DAYS
Days
Duration.ofSeconds(86400)
WEEKS
Weeks
Duration.ofSeconds(7 * 86400L)
MONTHS
Months
Duration.ofSeconds(31556952L / 12)
YEARS
Years
Duration.ofSeconds(31556952L)
DECADES
Decades
Duration.ofSeconds(31556952L * 10L)
CENTURIES
Centuries
Duration.ofSeconds(31556952L * 100L)
MILLENNIA
Millennia
Duration.ofSeconds(31556952L * 1000L)
ERAS
Eras
Duration.ofSeconds(31556952L * 1000_000_000L)
FOREVER
Forever
Duration.ofSeconds(Long.MAX_VALUE, 999_999_999)

3. ChronoUnit methods

public Duration getDuration()   

public boolean isDurationEstimated()  

public boolean isDateBased()  

public boolean isTimeBased()  

public boolean isSupportedBy(Temporal temporal)  

public <R extends Temporal> R addTo(R temporal, long amount)  

public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)

4. CENTURIES

L'unité qui représente le concept d'un siècle. Pour le système de calendrier ISO, il est égal à 100 ans.
Ce qui précède est également vrai pour les systèmes de calendrier Hijrah, Japonais, Minguo et ThaiBuddhist.
When used with other calendar systems it must correspond to an integral number of days and is normally an integral number of years.

5. DAYS

L'unité qui représente le concept d'une journée. Pour le système de calendrier ISO, c'est le jour standard de minuit à minuit. La durée estimée d'une journée est de 24 heures.
Ce qui précède est également vrai pour les systèmes de calendrier Hijrah, Japonais, Minguo et ThaiBuddhist.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il doit correspondre au jour défini par le lever et le coucher du Soleil sur Terre. Il n'est pas nécessaire que les jours commencent à minuit - lors de la conversion entre les systèmes de calendrier, ils doivent s'entrecroiser à midi.
Par exemple: Trouver le nombre de jours entre deux périodes de temps.
ChronoUnit_DAYS_ex1.java
LocalDateTime localDateTime1 = LocalDateTime.of(2020, 3, 15, 0, 30, 45);
LocalDateTime localDateTime2 = LocalDateTime.of(2020, 3, 17, 13, 30, 45);

Duration duration = Duration.between(localDateTime1, localDateTime2);
System.out.println("duration: " + duration); // PT61H (61 Hours)

long days = ChronoUnit.DAYS.between(localDateTime1, localDateTime2);
System.out.println("days: " + days); // 2
Par exemple: Ajouter deux jours
ChronoUnit_DAYS_ex2.java
ZonedDateTime now = ZonedDateTime.now();
// Plus 2 days
ZonedDateTime after2Days = now.plus(2, ChronoUnit.DAYS);

System.out.println("Now is: " + now);
System.out.println("After 2 days: " + after2Days);
Output:
Now is: 2021-07-17T00:50:13.048263+06:00[Asia/Bishkek]
After 2 days: 2021-07-19T00:50:13.048263+06:00[Asia/Bishkek]

6. DECADES

L'unité qui représente le concept d'une décennie. Pour le système de calendrier ISO, il est égal à 10 ans.
Ce qui précède est également vrai pour les systèmes de calendrier Hijrah, Japonais, Minguo et ThaiBuddhist.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il doit correspondre à un nombre entier de jours et est normalement un nombre entier d'années.

7. ERAS

L'unité qui représente le concept d'une ère (Era).
Le système de calendrier ISO ne dispose pas de concept d'ère, il n'apparaît donc pas dans les chaînes avec des formats de date et d'heure. Le temps de l'ère artificiellement estimé dans ce système est de 1 milliard d'années.
Calendar system
Date Time String
ISO
1989-02-08
Japanese Imperial Calendar
Japanese Heisei 1-02-08
L'ère est associée à la période de règne d'un roi ou à la durée d'une dynastie. Le concept d'ère est le plus évident dans le système de calendrier impérial japonais.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il n'y a aucune restriction sur sa valeur.
ChronoUnit_ERAS_ex1.java
LocalDate isoDate = LocalDate.of(2020, 3, 15);
System.out.printf("isoDate: %s%n%n", isoDate); // 2020-03-15

JapaneseDate japaneseDate = JapaneseDate.from(isoDate);
JapaneseEra era = japaneseDate.getEra();

System.out.printf("japaneseDate: %s%n", japaneseDate); // Japanese Reiwa 2-03-15
System.out.printf(" > era: %s", era); // Reiwa
Output:
isoDate: 2020-03-15

japaneseDate: Japanese Reiwa 2-03-15
 > era: Reiwa

8. FOREVER

Cette unité artificielle qui représente le concept d'éternité. Ceci est principalement utilisé avec TemporalField pour représenter des champs illimités tels que l'année ou l'ère. La durée estimée de cette unité est définie artificiellement comme la plus grande durée prise en charge par la Duration.
Duration maxDuration = ChronoUnit.FOREVER.getDuration();
Par exemple:
ChronoUnit_FOREVER_ex1.java
for (final ChronoUnit unit : ChronoUnit.values()) {
    final Duration duration = unit.getDuration();
    System.out.println(unit + ": " + duration + " (" + duration.getSeconds() + " seconds)");
}
Output:
Nanos: PT0.000000001S (0 seconds)
Micros: PT0.000001S (0 seconds)
Millis: PT0.001S (0 seconds)
Seconds: PT1S (1 seconds)
Minutes: PT1M (60 seconds)
Hours: PT1H (3600 seconds)
HalfDays: PT12H (43200 seconds)
Days: PT24H (86400 seconds)
Weeks: PT168H (604800 seconds)
Months: PT730H29M6S (2629746 seconds)
Years: PT8765H49M12S (31556952 seconds)
Decades: PT87658H12M (315569520 seconds)
Centuries: PT876582H (3155695200 seconds)
Millennia: PT8765820H (31556952000 seconds)
Eras: PT8765820000000H (31556952000000000 seconds)
Forever: PT2562047788015215H30M7.999999999S (9223372036854775807 seconds)

9. HALF_DAYS

L'unité qui représente le concept d'une demi-journée, tel qu'il est utilisé en AM/PM. Pour le système de calendrier ISO, il est égal à 12 heures.
Par exemple : Tronquer (truncate) le reste lorsqu'il est divisé par une demi-journée à partir d'un LocalDateTime.
ChronoUnit_HALF_DAYS_ex1.java
LocalDateTime localDateTime1 = LocalDateTime.of(2020, 3, 15, 9, 30, 45);
LocalDateTime truncatedLDT1 = localDateTime1.truncatedTo(ChronoUnit.HALF_DAYS);

System.out.printf("localDateTime1: %s%n", localDateTime1); // 2020-03-15T09:30:45
System.out.printf(" > truncated: %s%n%n", truncatedLDT1);  // 2020-03-15T00:00

LocalDateTime localDateTime2 = LocalDateTime.of(2020, 3, 15, 13, 30, 45);
LocalDateTime truncatedLDT2 = localDateTime2.truncatedTo(ChronoUnit.HALF_DAYS);

System.out.printf("localDateTime2: %s%n", localDateTime2); // 2020-03-15T13:30:45
System.out.printf(" > truncated: %s", truncatedLDT2);      // 2020-03-15T12:00
Output:
localDateTime1: 2020-03-15T09:30:45
 > truncated: 2020-03-15T00:00

localDateTime2: 2020-03-15T13:30:45
 > truncated: 2020-03-15T12:00

10. HOURS

L'unité qui représente le concept d'une heure. Pour le système de calendrier ISO, il est égal à 60 minutes.
Par exemple:
ChronoUnit_HOURS_ex1.java
ZonedDateTime parisNow = ZonedDateTime.now(ZoneId.of("Europe/Paris"));
System.out.println("Now in Paris: " + parisNow);
  
ZonedDateTime parisNowHour = parisNow.truncatedTo(ChronoUnit.HOURS);
System.out.println("Truncated to Hour: " + parisNowHour);
Output:
Now in Paris: 2021-07-17T05:40:15.939515+02:00[Europe/Paris]
Truncated to Hour: 2021-07-17T05:00+02:00[Europe/Paris]

11. MICROS

L'unité qui représente le concept d'une microseconde. Pour le système de calendrier ISO, 1 seconde équivaut à 1 million de microsecondes.

12. MILLENNIA

L'unité qui représente le concept d'un millénaire. Pour le système de calendrier ISO, il est égal à 1000 ans.
Ce qui précède est également vrai pour les systèmes de calendrier Hijrah, Japonais, Minguo et ThaiBuddhist.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il doit correspondre à un nombre entier de jours et est normalement un nombre entier d'années.

13. MILLIS

L'unité qui représente le concept de milliseconde. Pour le système de calendrier ISO, 1 seconde équivaut à 1000 millisecondes.

14. MINUTES

L'unité qui représente le concept d'une minute. Pour le système de calendrier ISO, il est égal à 60 secondes.

15. MONTHS

L'unité qui représente le concept d'un mois. Pour le système de calendrier ISO, la longueur du mois varie selon le mois de l'année. La durée estimée d'un mois est un douzième de 365,2425 Jours.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il doit correspondre à un nombre entier de jours.

16. NANOS

L'unité qui représente le concept de nanoseconde, la plus petite unité de temps prise en charge. Pour le système de calendrier ISO, 1 seconde équivaut à 1 milliard de nanosecondes.

17. SECONDS

Unité qui représente le concept de seconde. Pour le système de calendrier ISO, il est égal à la seconde dans le système d'unités SI, sauf environ une seconde intercalaire.

18. WEEKS

L'unité qui représente le concept d'une semaine. Pour le système de calendrier ISO, il est égal à 7 jours.
Ce qui précède est également vrai pour les systèmes de calendrier Hijrah, Japonais, Minguo et ThaiBuddhist.
Lorsqu'il est utilisé sur d'autres systèmes de calendrier, il doit correspondre à un nombre entier de jours.

19. YEARS

L'unité qui représente le concept d'une année. Pour le système de calendrier ISO, il est égal à 12 mois. La durée estimée d'une année est de 365,2425 jours.
Une année dans les systèmes de calendrier Hijrah, Japanese, Minguo et ThaiBuddhist est aussi égale à 12 mois.
Lorsqu'il est utilisé avec d'autres systèmes de calendrier, il doit correspondre à un nombre entier de jours ou de mois à peu près égal à une année définie par le passage de la Terre autour du Soleil.

20. getDuration()

Renvoyer la durée estimée de cette unité dans le système de calendrier ISO.
public Duration getDuration()
Toutes les parts de cette catégorie disposent d'une durée estimée. Les jours varient en raison de l'heure d'été (DST), alors que les mois disposent de longueurs différentes.
Par exemple : Un mois est estimé à 30 jours, mais en heures, il est estimé à 730 (30,41 jours).
ChronoUnit_getDuration_ex1.java
Duration monthDuration = ChronoUnit.MONTHS.getDuration();  
// to days: 30 days
System.out.println("monthDuration.toDays(): " + monthDuration.toDays());  

// to hours: 730 hours ~ 30.41 days.
System.out.println("monthDuration.toHours(): " + monthDuration.toHours());
Output:
monthDuration.toDays(): 30
monthDuration.toHours(): 730
Par exemple : Estimer le nombre d'heures dans «1 an 2 mois 15 jours».
ChronoUnit_getDuration_ex2.java
Period period = Period.of(1, 2, 15); // 1 year 2 months 15 days.

int years = period.getYears(); // 1
int months = period.getMonths(); // 2
int days = period.getDays(); // 15

System.out.println("years: " + years); // 1
System.out.println("months: " + months);// 2
System.out.println("days: " + days); // 15

Duration yearsDuration = ChronoUnit.YEARS.getDuration().multipliedBy(years);
Duration monthsDuration = ChronoUnit.MONTHS.getDuration().multipliedBy(months);
Duration daysDuration = ChronoUnit.DAYS.getDuration().multipliedBy(days);

Duration totalDuration = yearsDuration.plus(monthsDuration).plus(daysDuration);

long estimatedDays = totalDuration.toDays();
long estimatedHours = totalDuration.toHours();
System.out.println("Estimated days: " + estimatedDays); // 441 days
System.out.println("Estimated hours: " + estimatedHours); // 10586 hours ~ 441.08 days.
Output:
years: 1
months: 2
days: 15
Estimated days: 441
Estimated hours: 10586

21. isDurationEstimated()

Vérifier si la durée de l'unité est une estimation.
public boolean isDurationEstimated()
Toutes les unités de temps de cette classe sont considérées comme exactes, alors que toutes les unités de date de cette classe sont considérées comme estimées. Voir plus de méthodes isTimeBased() et isDateBased().
Cette définition ignore les secondes intercalaires, mais considère que les jours varient en raison de l'heure d'été et que les mois disposent de longueurs différentes.
Par exemple: Imprimer une liste d'unités de précision de cette classe.
ChronoUnit_isDurationEstimated_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isDurationEstimated()) {
        System.out.println(unit.name());
    }
}
Output:
DAYS
WEEKS
MONTHS
YEARS
DECADES
CENTURIES
MILLENNIA
ERAS
FOREVER

22. isDateBased()

Vérifier si cette unité est basée sur la date ?
public boolean isDateBased()
Toutes les unités de DAYS à ERAS renvoient true. Les unités basées sur le temps et FOREVER renvoient false.
ChronoUnit_isDateBased_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isDateBased()) {
        System.out.println(unit.name());
    }
}
Output:
DAYS
WEEKS
MONTHS
YEARS
DECADES
CENTURIES
MILLENNIA
ERAS

23. isTimeBased()

Vérifier si cette unité est basée sur le temps ?
public boolean isTimeBased()
Toutes les unités de NANOS à HALF_DAYS renvoient true. Les unités basées sur la date et FOREVER renvoient false.
ChronoUnit_isTimeBased_ex1.java
for (ChronoUnit unit : ChronoUnit.values()) {
    if (unit.isTimeBased()) {
        System.out.println(unit.name());
    }
}
Output:
NANOS
MICROS
MILLIS
SECONDS
MINUTES
HOURS
HALF_DAYS

24. isSupportedBy(Temporal)

Vérifie si cette unité est prise en charge par l'objet Temporal spécifié.
public boolean isSupportedBy(Temporal temporal)
Par exemple : Rechercher des unités prises en charge par LocalDate :
ChronoUnit_isSupportedBy_ex1.java
Temporal localDate = LocalDate.now();
System.out.println("Does LocalDate support: ");

for(ChronoUnit unit: ChronoUnit.values()) {
    System.out.println(unit.name() + "? " + unit.isSupportedBy(localDate));  
}
Output:
Does LocalDate support:
NANOS? false
MICROS? false
MILLIS? false
SECONDS? false
MINUTES? false
HOURS? false
HALF_DAYS? false
DAYS? true
WEEKS? true
MONTHS? true
YEARS? true
DECADES? true
CENTURIES? true
MILLENNIA? true
ERAS? true
FOREVER? false

25. addTo(R temporal, long amount)

Renvoyer une copie de l'objet Temporal spécifié avec la période spécifiée ajoutée.
public <R extends Temporal> R addTo(R temporal, long amount)
Cette méthode est équivalente à la méthode Temporal.plus(long,TemporalUnit). Cette approche est recommandée.
// Defined in Temporal interface
public Temporal plus​(long amountToAdd, TemporalUnit unit)
Par exemple:
ChronoUnit_addTo_ex1.java
Temporal ym = YearMonth.of(2020, 3); // 2020-03
// Add 10 monthds to ym.
YearMonth ym2 = (YearMonth) ChronoUnit.MONTHS.addTo(ym, 10);

System.out.println("ym2: " + ym2); // 2021-01

26. between(Temporal, Temporal)

Renvoyer la durée entre deux objets Temporal. Cette unité doit être prise en charge par les deux objets Temporal, sinon une exception sera levée.
public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
Cette méthode équivaut à utiliser la méthode Temporal.until(Temporal,TemporalUnit).
// Defined in Temporal interface
public long until​(Temporal endExclusive, TemporalUnit unit)
Par exemple:
ChronoUnit_between_ex1.java
LocalDate from = LocalDate.of(2020, 3, 15);
LocalDate to = LocalDate.of(2020, 3, 17);

long days = ChronoUnit.DAYS.between(from, to);
System.out.println("days: " + days); // 2
Par exemple:
ChronoUnit_between_ex2.java
YearMonth from = YearMonth.of(2020, 7);
LocalDateTime to = LocalDateTime.of(2021, 3, 17, 13, 45, 30);

long months = ChronoUnit.MONTHS.between(from, to);
System.out.println("months: " + months); // 8