% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/00_classes.R, R/cal0_time_astro.R,
%   R/cal0_time_civil.R
\name{mt_unit}
\alias{mt_unit}
\alias{mt_loc_unit}
\alias{mt_tz_unit}
\title{Base S7 class for creating new time units}
\usage{
mt_unit(n = 1L)

mt_loc_unit(n = 1L, lat = naive_loc, lon = naive_loc, alt = naive(0))

mt_tz_unit(n = 1L, tz = naive_tz)
}
\arguments{
\item{n}{The step size of time granule. For example, \code{n = 2L} is 2 time
units, and \code{cal_isoweek$week(2L)} would represent 2 weeks (a fortnight).}

\item{lat}{Numeric. Latitude in decimal degrees. Range: -90 to 90.
Default: naive location (astronomical calculations require \code{lat}).}

\item{lon}{Numeric. Longitude in decimal degrees. Range: -180 to 180.
Default: naive location (astronomical calculations require \code{lon}).}

\item{alt}{Numeric. Altitude in meters above sea level.
Default: 0 (sea level).}

\item{tz}{The timezone name for the unit (valid units can be found with \verb{[tzdb::tzdb_names()]})}
}
\value{
A time granule object of class \code{mt_unit}
}
\description{
This class is the primitive class for time units, and should
be extended from when creating new time units. A new class
is typically created with S7 using:
\code{S7::new_class("tu_***", parent = mt_tz_unit)}
}
\details{
Time units are the building blocks of calendars in mixtime. Each unit
represents a specific temporal component (e.g., day, month, year) and
can be combined using \code{\link[=new_calendar]{new_calendar()}} to create a calendar system.

When creating custom calendars, define time unit classes that inherit
from either \code{mt_unit} (for standard units) or \code{mt_tz_unit} (for
timezone-aware units), then pass them as named arguments to
\code{\link[=new_calendar]{new_calendar()}}. The calendar will use these names to create
constructor functions accessible via \code{$} notation (e.g., \code{calendar$day(1L)}).
}
\section{Calendar Algebra Methods}{


Time units enable calendar arithmetic through key generic methods
that should be implemented for custom time units:
\itemize{
\item \code{chronon_cardinality_fixed(x, y)} - Returns the number of unit \code{x}
granules that fit within one unit \code{y} granule, for relationships that are
a constant, context-independent number (e.g., 7 days per week, 24 hours
per day). Prefer this over \code{chronon_cardinality()} whenever the
relationship does not depend on \code{at}, since it is also used to determine
which relationships are safe to use for \code{\link[=chronon_divmod]{chronon_divmod()}}'s graph
traversal.
\item \code{chronon_cardinality(x, y, at)} - Returns the number of \code{x} granule
that fit within one \code{y} granule. This is variable based on \code{at} (e.g.,
28-31 days per month). Only implement this directly (rather than
\code{chronon_cardinality_fixed()}) when the relationship genuinely depends on
\code{at}, and pair it with a direct \code{chronon_divmod()} method so that the
relationship remains reachable during graph traversal.
\item \code{chronon_divmod(x, from, to)} - Converts time point \code{x} from granules of
\code{from} to granules of \code{to}, returning a list with \code{div} (the quotient)
and \code{mod}. This enables conversions between granules that have
variable cardinality (e.g., the date 2020-03-23 to the month 2020-03).
All conversions should be based on chronons since epoch (1970-01-01),
in the UTC time zone.
}

These methods work together to enable mixtime to perform calendar-aware
arithmetic, understanding that months have variable lengths and handling
timezone-aware conversions.
}

\examples{
# Create a timezone-aware unit class

# Use these units to create a calendar
my_calendar <- new_calendar(
  day = S7::new_class("tu_my_day", parent = mt_unit),
  month = S7::new_class("tu_my_month", parent = mt_tz_unit),
  class = "my_calendar"
)

# Access unit constructors from the calendar
my_calendar$day(1L)
my_calendar$month(3L, tz = "America/New_York")

}
\seealso{
\code{\link[=new_calendar]{new_calendar()}} for creating calendars from time units
}
