Temporal.ZonedDateTime : méthode add()

Syntaxe

add(duration)
add(duration, options)

Paramètres

duration

Une chaîne de caractères, un objet ou une instance de Temporal.Duration représentant une durée à ajouter à cette date et heure. Elle est convertie en objet Temporal.Duration en utilisant le même algorithme que Temporal.Duration.from().

options Facultatif

Un objet contenant la propriété suivante :

overflow Facultatif

Une chaîne de caractères définissant le comportement lorsque une composante de date est hors de portée. Les valeurs possibles sont :

"constrain" (par défaut)

La composante de date est contraint à la plage valide.

"reject"

Un objet RangeError est levé si la composante de date est hors de portée.

Valeur de retour

Un nouvel objet Temporal.ZonedDateTime représentant la date et l'heure définies par le ZonedDateTime d'origine, plus la durée.

Exceptions

RangeError

Levée si le résultat n'est pas dans la plage représentable, qui est de ±10⁸ jours, soit environ ±273 972,6 ans, à partir de l'époque Unix.

Description

Pour savoir comment les durées de calendrier sont ajoutées, voir Temporal.PlainDate.prototype.add().

L'addition et la soustraction sont effectuées selon les règles définies dans le RFC 5545 (iCalendar) ^(angl.) :

• Ajouter ou soustraire la partie date d'une durée en utilisant l'arithmétique de calendrier : en d'autres termes, ajouter la partie date à son PlainDateTime en utilisant Temporal.PlainDateTime.prototype.add(), puis interpréter le résultat dans le même fuseau horaire. Le résultat s'ajustera automatiquement à l'heure d'été en utilisant les règles du champ timeZone de cette instance. Par exemple, 2024-11-03T01:00:00-04:00[America/New_York] plus un jour donne 2024-11-04T01:00:00-05:00[America/New_York], comme si le jour avait 25 heures.
  • Si la date et l'heure sont ambiguës ou invalides en raison d'une transition de décalage du fuseau horaire, elles sont résolues en utilisant le comportement disambiguation: "compatible" : le plus tardif des deux instants possibles sera utilisé pour les transitions sautées et le plus tôt des deux instants possibles sera utilisé pour les transitions répétées. Par exemple, 2024-03-09T02:05:00-05:00[America/New_York] plus un jour devrait donner 2024-03-10T02:05:00-05:00[America/New_York], mais cette heure n'existe pas, donc l'heure affichée une heure plus tard, 2024-03-10T03:05:00-04:00[America/New_York], est retournée.
  • Si le décalage est ambigu, il est résolu en utilisant le comportement offset: "prefer" : le décalage est utilisé s'il est valide pour le fuseau horaire et l'heure locale, et recalculé sinon. Par exemple, 2024-11-02T01:00:00-04:00[America/New_York] plus un jour donne 2024-11-03T01:00:00-04:00[America/New_York], tandis que 2024-11-04T01:00:00-05:00[America/New_York] moins un jour donne 2024-11-03T01:00:00-05:00[America/New_York].
  • Si les composantes de la date et de l'heure résultantes sont hors limites, ils sont résolus en utilisant l'option overflow. Par exemple, 2024-08-31 plus un mois donne 2024-09-31 qui n'existe pas, donc il est ramené à 2024-09-30 par défaut.
  • Si les composantes de la date et de l'heure obtenues dépassent les limites autorisées, elles sont ajustées à l'aide de l'option overflow. Par exemple, 2024-08-31 plus un mois donne 2024-09-31, qui n'existe pas, donc cette date est limitée à 2024-09-30 par défaut.
• Ajouter ou soustraire la partie temps d'une durée en utilisant le temps réel ; en d'autres termes, ajouter la partie temps à son Instant en utilisant Temporal.Instant.prototype.add(), puis interpréter le résultat dans le même fuseau horaire. Par exemple, 2024-11-03T01:00:00-04:00[America/New_York] plus une heure donne 2024-11-03T01:00:00-05:00[America/New_York].

Ces règles rendent l'arithmétique avec Temporal.ZonedDateTime « sûre pour l'heure d'été », ce qui signifie que les résultats correspondent au mieux aux attentes des utilisateur·ice·s réels et des personnes qui implémentent d'autres applications de calendrier conformes aux standards. Ces attentes incluent :

• Ajouter ou soustraire des jours doit maintenir l'heure affichée cohérente lors des transitions d'heure d'été. Par exemple, si vous avez un rendez-vous le samedi à 13h00 et que vous demandez à le reprogrammer un jour plus tard, vous vous attendez à ce que le rendez-vous reprogrammé soit toujours à 13h00, même s'il y a eu une transition d'heure d'été pendant la nuit.
• Ajouter ou soustraire la partie temps d'une durée doit ignorer les transitions d'heure d'été. Par exemple, un·e ami·e à qui vous avez demandé de vous retrouver dans 2 heures sera contrarié·e si vous arrivez 1 heure ou 3 heures plus tard. Il doit y avoir un ordre d'opérations cohérent et relativement peu surprenant.
• Si les résultats sont à ou près d'une transition d'heure d'été, les ambiguïtés doivent être gérées automatiquement (sans plantage) et de manière déterministe.

Ajouter une durée équivaut à soustraire sa négation.

Exemples

Ajouter une durée

const start = Temporal.ZonedDateTime.from(
  "2021-11-01T12:34:56-04:00[America/New_York]",
);
const end = start.add({
  years: 1,
  months: 2,
  weeks: 3,
  days: 4,
  hours: 5,
  minutes: 6,
  seconds: 7,
  milliseconds: 8,
});
console.log(end.toString()); // 2023-01-26T17:41:03.008-05:00[America/New_York]

Pour plus d'exemples, en particulier sur la façon dont différents calendriers et l'option overflow interagissent avec les durées de calendrier, voir Temporal.PlainDate.prototype.add().

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Temporal.ZonedDateTime
• L'objet Temporal.Duration
• La méthode Temporal.ZonedDateTime.prototype.subtract()