Skip to contents

Date and Time Arithmetic

Source: R/time_calendar.R
stri_datetime_add.Rd

Modifies a date-time object by adding a specific amount of time units.

Usage

stri_datetime_add(
  time,
  value = 1L,
  units = "seconds",
  tz = NULL,
  locale = NULL
)

stri_datetime_add(time, units = "seconds", tz = NULL, locale = NULL) <- value

Arguments

time

an object of class POSIXct (as.POSIXct will be called on character vectors and objects of class POSIXlt, Date, and factor)

value

integer vector; signed number of units to add to time

units

single string; one of 'years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', or 'milliseconds'

tz

NULL or '' for the default time zone or a single string with a timezone identifier,

locale

NULL or '' for default locale, or a single string with locale identifier; a non-Gregorian calendar may be specified by setting the @calendar=name keyword

Value

Both functions return an object of class POSIXct.

The replacement version of stri_datetime_add modifies the state of the time object.

Details

Vectorized over time and value.

Note that, e.g., January, 31 + 1 month = February, 28 or 29.

References

Calendar Classes - ICU User Guide, https://unicode-org.github.io/icu/userguide/datetime/calendar/

See also

The official online manual of stringi at https://stringi.gagolewski.com/

Gagolewski M., stringi: Fast and portable character string processing in R, Journal of Statistical Software 103(2), 2022, 1-59, doi:10.18637/jss.v103.i02

Other datetime: stri_datetime_create(), stri_datetime_fields(), stri_datetime_format(), stri_datetime_fstr(), stri_datetime_now(), stri_datetime_symbols(), stri_timezone_get(), stri_timezone_info(), stri_timezone_list()

Author

Marek Gagolewski and other contributors

Examples

x <- stri_datetime_now()
print(x)
#> [1] "2025-11-25 19:56:32 UTC"
stri_datetime_add(x, units='months') <- 2
print(x)
#> [1] "2026-01-25 19:56:32 UTC"

x <- stri_datetime_create(2025, 4, 20)
print(x)
#> [1] "2025-04-20 UTC"
stri_datetime_add(x, -2, units='months')
#> [1] "2025-02-20 UTC"
stri_datetime_add(x, 1, units='years')
#> [1] "2026-04-20 UTC"
stri_datetime_add(x, 1, units='years', locale='@calendar=hebrew')
#> [1] "2026-04-09 UTC"

stri_datetime_add(stri_datetime_create(2024, 1, 31), 1, units='months')
#> [1] "2024-02-29 UTC"