% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/01_chronon_cardinality.R
\name{chronon_cardinality}
\alias{chronon_cardinality}
\title{Cardinality between time granules}
\usage{
chronon_cardinality(x, y, ...)
}
\arguments{
\item{x}{The finer time granule (e.g. \code{cal_gregorian$month(1L)})}

\item{y}{The coarser time granule (e.g. \code{cal_gregorian$year(1L)})}

\item{...}{Additional arguments for methods.}
}
\value{
Numeric describing how many \code{x} time granules fit into \code{y} at time \code{at}.
}
\description{
This S7 generic function defines the calendrical relationships between two
chronons, and is one of the building block for defining calendars in mixtime.
It calculates how many \code{x} chronons fit into the \code{y} chronon. Some chronon
sizes are context-dependent (such as the number of days in a month),
and so an optional time point defined in terms of \code{y} chronons can be
provided with \code{at}.
}
\details{
The methods are dispatched based on the shortest path along defined methods.
This allows for defining only the direct relationships between adjacent
time units, and relying on graph traversal to find how to convert between
more distant units. For example the number of seconds in an hour can be
calculated from the number of seconds in a minute and then number of minutes
in an hour.

If a method is defined for converting between time units of different
calendar systems (e.g., Gregorian calendar days to Chinese calendar days),
then that method can be used to convert times at any granularity between the
two systems.
}
\examples{
# There are 12 months in a year
with(cal_gregorian, chronon_cardinality(month(1L), year(1L)))

# There are 7 days in a week
with(cal_isoweek, chronon_cardinality(day(1L), week(1L)))

# There are 3600 seconds in an hour
with(cal_gregorian, chronon_cardinality(second(1L), hour(1L)))

# There are 18 "2 months" in 3 years
with(cal_gregorian, chronon_cardinality(month(2L), year(3L)))

# There are 365 days in 2025 (a common year)
chronon_cardinality(
  cal_gregorian$day(1L), cal_gregorian$year(1L),
  at = year(as.Date("2025-01-01"))
)

# There are 366 days in 2024 (a leap year)
chronon_cardinality(
  cal_gregorian$day(1L), cal_gregorian$year(1L), 
  at = mixtime::year(as.Date("2024-01-01"))
)

# There are 29 days in February 2024 (a leap year)
chronon_cardinality(
  cal_gregorian$day(1L), cal_gregorian$month(1L), 
  at = yearmonth(as.Date("2024-02-01"))
)

}
