stringi (version 1.8.7)

stri_datetime_add: Date and Time Arithmetic

Description

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

Value

Both functions return an object of class POSIXct.

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

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

Author

Marek Gagolewski and other contributors

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, tools:::Rd_expr_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()

Examples

x <- stri_datetime_now()
print(x)
stri_datetime_add(x, units='months') <- 2
print(x)

x <- stri_datetime_create(2025, 4, 20)
print(x)
stri_datetime_add(x, -2, units='months')
stri_datetime_add(x, 1, units='years')
stri_datetime_add(x, 1, units='years', locale='@calendar=hebrew')

stri_datetime_add(stri_datetime_create(2024, 1, 31), 1, units='months')