% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/components.R
\name{time_components}
\alias{time_components}
\title{Extract linear and cyclical time components}
\usage{
time_components(x, ..., calendar = time_calendar(x))
}
\arguments{
\item{x}{A \code{mixtime} (or an object coercible to one via \code{\link[=as_mixtime]{as_mixtime()}}, such
as a \code{Date} or \code{POSIXct}).}

\item{...}{Named expressions using \code{\link[=lin]{lin()}} and \code{\link[=cyc]{cyc()}} describing the
components to extract. The granule names (e.g. \code{year}, \code{month}, \code{day}) are
resolved in the calendar of \code{x}.}

\item{calendar}{Calendar system used to resolve granule names, overlaid on the
calendar of \code{x}. Defaults to \code{time_calendar(x)}. Supply e.g. \link{cal_isoweek}
to make ISO \code{week}-based components available.}
}
\value{
A data frame with one column per requested component. \code{lin()} columns
are linear (\code{mt_linear}) time vectors and \code{cyc()} columns are cyclical
(\code{mt_cyclical}) time vectors.
}
\description{
\code{time_components()} decomposes a time vector into its constituent parts using
\code{dplyr::mutate()}-like semantics. Each named expression is built from the
\code{\link[=lin]{lin()}} and \code{\link[=cyc]{cyc()}} helpers (the same vocabulary used in \code{\link[=format]{format()}} strings)
and produces a component time vector:
}
\details{
\itemize{
\item \verb{lin(<granule>)} extracts a \strong{linear} component (a non-repeating count,
e.g. the year), returning a linear time vector.
\item \verb{cyc(<granule>, <cycle>)} extracts a \strong{cyclical} component (a repeating
position within a larger cycle, e.g. the month within the year), returning a
cyclical time vector.
}

All requested components are computed together in a single decomposition of
the underlying time vector (via \code{chronon_parts()}), reusing the shared
recursive \code{chronon_divmod()} results rather than converting each component
independently.
}
\examples{
t <- yearmonth(as.Date("2026-02-14") + c(0, 40, 400))

# Extract the year (linear) and month-of-year (cyclical)
time_components(t, yr = lin(year), mth = cyc(month, year))

# Components can be named automatically from the expression
time_components(as.Date("2025-12-15") + 0:3, cyc(day, cal_isoweek$week))

}
\seealso{
\code{\link[=lin]{lin()}} and \code{\link[=cyc]{cyc()}} for the component helpers, \code{\link[=linear_time]{linear_time()}} and
\code{\link[=cyclical_time]{cyclical_time()}} for constructing individual component vectors, and
\code{\link[=format]{format()}} for the string counterpart of this interface.
}
