% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/01_labels.R
\name{linear_labels_format}
\alias{linear_labels_format}
\alias{cyclical_labels_format}
\alias{linear_labels_parse}
\alias{cyclical_labels_parse}
\title{Render and parse a granule's labels}
\usage{
linear_labels_format(granule, ...)

cyclical_labels_format(granule, cycle, ...)

linear_labels_parse(granule, ...)

cyclical_labels_parse(granule, cycle, ...)
}
\arguments{
\item{granule}{A time granule object representing the granule (e.g.
\code{month(1L)}).}

\item{...}{Passed on to the method. The default method (see below) takes:
\itemize{
\item \code{i}: Integer vector: the position along the linear axis, or within
the cycle for \code{cyclical_labels_format()}.
\item \code{at}: The linear position of the cycle granule, letting a method
produce labels specific to that cycle instance (mainly for irregular
cycles, e.g. a leap month). Same convention as \code{at} in
\code{\link[=chronon_cardinality]{chronon_cardinality()}}.
\item \code{label}: If \code{TRUE}, return named labels (e.g. "February"). If
\code{FALSE}, return the numeric position as character.
\item \code{abbreviate}: If \code{TRUE}, return abbreviated labels (e.g. "Feb"). If
\code{FALSE}, return full labels (e.g. "February").
\item \code{type}: Overrides \code{abbreviate}'s abbreviated/wide choice of
\code{\link[=vocab_table]{vocab_table()}} type outright, e.g. \code{type = "emoji"}. \code{NULL} (default)
defers to \code{abbreviate}.
\item \code{width},\code{locale}: Call-time overrides of the scheme's \code{width}/\code{locale}
defaults (see \code{\link[=label_scheme]{label_scheme()}}); \code{NULL} defers to the scheme.
}}

\item{cycle}{A time granule object representing the cycle (e.g.
\code{year(1L)}).}
}
\value{
Character vector of labels for the time point.
}
\description{
The generics turning a granule's internal position into display text
(\code{linear_labels_format()} for a non-repeating position, e.g. the year;
\code{cyclical_labels_format()} for a position within a larger cycle, e.g. the
month within the year) and back (\code{linear_labels_parse()}/
\code{cyclical_labels_parse()}).
}
\details{
Each has one default method (on the base \code{mt_unit} class) that looks up
the granule's scheme via \code{\link[=linear_labels]{linear_labels()}}/\code{\link[=cyclical_labels]{cyclical_labels()}} and
applies it (see \code{\link[=label_scheme]{label_scheme()}} for the fields). Calendar authors
usually declare a scheme instead of writing a method here directly.
Writing one directly overrides the generics for labels that aren't
index-shaped at all, see \code{\link[=linear_labels]{linear_labels()}}'s "Overriding the generics
directly" section.
}
\section{Epoch shift}{

\code{linear_labels_format()}'s \code{i} arrives already epoch-shifted for display
(\code{chronon_parts()} adds \code{\link[=chronon_epoch]{chronon_epoch()}} before calling it, e.g. a
Gregorian year's \code{i} is \code{2024}, not \code{54}). The default
\code{linear_labels_parse()} method shifts \code{decode()}'s output back, by
subtracting \code{\link[=chronon_epoch]{chronon_epoch()}} after the scheme's own decode runs. A
hand-written override method skips this and must do the same
subtraction itself if the granule has a non-zero epoch; see the example
in \code{\link[=linear_labels]{linear_labels()}}.
}

\examples{
# Labels for years on a linear axis
with(cal_gregorian, linear_labels_format(year(1L), 2020:2025))

# Labels for months in a year
with(cal_gregorian, cyclical_labels_format(month(1L), year(1L), 0:11))

}
\seealso{
\code{\link[=linear_labels]{linear_labels()}}/\code{\link[=cyclical_labels]{cyclical_labels()}} for the authoring
interface these generics' default methods interpret.
}
