Temporal.Instant : méthode add()

Syntaxe

add(duration)

Paramètres

duration

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

Valeur de retour

Un nouvel objet Temporal.Instant représentant l'ajout de duration à cet instant. Si duration est positive, l'instant retourné est ultérieur à cet instant ; si duration est négative, l'instant retourné est antérieur à cet instant.

Exceptions

RangeError

Levée dans l'un des cas suivants :

• duration est une durée de calendrier (elle a des years, months ou weeks non nuls), ou a des days non nuls, car les durées de calendrier sont ambiguës sans calendrier et référence temporelle.
• Le résultat n'est pas dans la plage représentable, qui est ±10⁸ jours, soit environ ±273 972,6 ans, depuis l'époque Unix.

Description

En essence, la méthode add() obtient d'abord le nombre de nanosecondes représenté par duration, l'ajoute aux epochNanoseconds de cet instant, puis crée un nouvel objet Temporal.Instant à partir du résultat. Par conséquent, la durée doit représenter de manière non ambiguë une quantité de temps fixe.

Si vous souhaitez ajouter une durée calendaire, l'addition doit être effectuée dans le contexte d'un calendrier et d'un fuseau horaire pour tenir compte des longueurs variables des mois, des années et des jours (en raison de l'heure d'été). Dans ce cas, convertissez l'instant en un objet Temporal.ZonedDateTime, ajoutez la durée, puis convertissez le résultat en un instant.

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

Exemples

Ajouter une Temporal.Duration

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const duration = Temporal.Duration.from("PT1S");
const newInstant = instant.add(duration);
console.log(newInstant.epochMilliseconds); // 1000

Ajouter un objet ou une chaîne de caractères

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const newInstant = instant.add({ seconds: 1 });
console.log(newInstant.epochMilliseconds); // 1000

const newInstant2 = instant.add("PT1S");
console.log(newInstant2.epochMilliseconds); // 1000

Ajouter une durée calendaire

const instant = Temporal.Instant.fromEpochMilliseconds(1730610000000);
const duration = Temporal.Duration.from({ days: 1 });

// Cet instant est 2024-11-03T01:00:00-04:00[America/New_York],
// ce qui est un jour de transition DST aux États-Unis.
const instant2 = instant
  .toZonedDateTimeISO("America/New_York")
  .add(duration)
  .toInstant();
console.log(instant2.epochMilliseconds); // 1730700000000

// Le même instant n'est pas un jour de transition DST à Paris.
const instant3 = instant
  .toZonedDateTimeISO("Europe/Paris")
  .add(duration)
  .toInstant();
console.log(instant3.epochMilliseconds); // 1730696400000

Spécifications

Compatibilité des navigateurs

Voir aussi

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