new_calendar: Create a new calendar

View source: R/01_calendar.R

new_calendarR Documentation

Create a new calendar

Description

Define a new calendar as a collection of time units. Calendars are the foundation for representing dates and times in terms of human-readable components like years, months, days, hours, minutes, and seconds. Each calendar is defined by specifying the time units it contains, which determine how time values can be interpreted and manipulated.

Usage

new_calendar(..., name, inherit = NULL, class = lifecycle::deprecated())

Arguments

...

Named time unit class definitions. Each argument should be a time unit class (typically created with new_time_unit()) that inherits from mt_unit or mt_tz_unit. The names define the calendar's fields and are used to access unit constructors (e.g., calendar$year()).

name

A string naming the calendar (e.g. "cal_gregorian"). Together with the package that defines it, this identifies the calendar of time units. Calendars defined in a package should be bound in that package's namespace under this name, so that they can be found when time objects are read back in from a file.

inherit

Optional calendar to inherit time units from. Units defined in ... will override inherited units with the same name.

class

[Deprecated] Use name instead.

Details

Time units are typically S7 class definitions that inherit from mt_unit for standard units, mt_tz_unit for timezone-aware units (civil time), or mt_loc_unit for location-aware units (astronomical time). The calendar object provides a namespace for accessing these unit constructors and defines the relationships between them for calendar arithmetic.

Value

A calendar object, the single instance of a new S7 class name which inherits from mt_calendar. A calendar is a named list containing the specified time unit classes.

See Also

linear_time(), cyclical_time()

Examples

# Create a simple calendar with year and month units
# (inheriting from civil time units for day, hour, minute, second, ...)
cal_simple <- new_calendar(
  year = new_time_unit("tu_year", parent = mt_tz_unit),
  month = new_time_unit("tu_month", parent = mt_tz_unit),
  inherit = cal_time_civil,
  name = "cal_simple"
)

# Create time granules from the calendar
cal_simple$year(1L)
cal_simple$month(1L)


mixtime documentation built on Nov. 18, 2026, 5:08 p.m.