addToTemporal

AddToTemporal is a generic operation found in date-time libraries and temporal data models. It produces a new temporal value by adding a quantity to an existing temporal object, such as a date, time, or timestamp. The operation accepts the temporal input, an amount to add, and a unit or duration, and returns a new object of the same or compatible type if supported.

The semantics of addToTemporal depend on the library and the specific temporal type. It is typically non-destructive, meaning the original value remains unchanged in immutable APIs. Not all units may be supported by every temporal type; for example, adding months to a time-of-day may be invalid in some contexts. When the addition crosses calendar boundaries (such as varying month lengths or leap days), the result follows the calendar rules of the underlying system.

Examples illustrate common usage: addToTemporal(date, 7, "days") yields a date one week later, and addToTemporal(appointmentTime, 2, "hours") yields two hours later. In many languages, equivalent functionality is exposed through more specific methods such as plusDays, plusMonths, or a general plus method, with addToTemporal sometimes acting as a higher-level wrapper.

Relation to libraries and APIs: addToTemporal corresponds to general time arithmetic. In Java, a similar concept appears in the Temporal.plus(long amountToAdd, TemporalUnit unit) method. In Python, datetime objects use addition with timedelta; in JavaScript, libraries provide analogous helpers like addDays or addHours.

See also: Temporal, Duration, Period, ChronoUnit.