% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/01_time_unit.R
\name{new_time_unit}
\alias{new_time_unit}
\title{Create a new time unit class}
\usage{
new_time_unit(
  name,
  parent = mt_unit,
  package = topNamespaceName(parent.frame()),
  properties = list(),
  abstract = FALSE,
  constructor = NULL,
  validator = NULL
)
}
\arguments{
\item{name}{A string naming the new S7 class (e.g., \code{"tu_my_year"}).
By convention, time unit class names are prefixed with \code{tu_}.}

\item{parent}{The parent S7 class. Should be one of \code{\link{mt_unit}},
\code{\link{mt_tz_unit}}, or \code{\link{mt_loc_unit}}, or a class that itself inherits from
one of these. Defaults to \code{\link{mt_unit}}.}

\item{package}{A string giving the package name that owns the class.
Defaults to the name of the calling namespace, so typically does not
need to be set explicitly.}

\item{properties}{A named list of additional \code{\link[S7:new_property]{S7::new_property()}}
definitions beyond those inherited from \code{parent}. Each entry becomes
a slot on instances of the new class. Defaults to an empty list.}

\item{abstract}{Logical. If \code{TRUE} the class cannot be instantiated
directly; it serves only as a base for further subclassing.}

\item{constructor}{A function to use as the class constructor, or \code{NULL}
(default) to generate one automatically. The auto-generated constructor
accepts \code{...} (forwarded to the parent constructor) plus one argument per
entry in \code{properties}, with defaults taken from each property's
\code{default} field.}

\item{validator}{A function of one argument (\code{self}) that returns \code{NULL}
when the object is valid, or a character string describing the problem.
See \code{\link[S7:new_class]{S7::new_class()}} for details.}
}
\value{
An S7 class object, as returned by \code{\link[S7:new_class]{S7::new_class()}}.
}
\description{
Define a new S7 class representing a time unit for use in a mixtime calendar.
Time units are the building blocks of calendars: each unit represents a
specific temporal component (e.g., day, month, year) and carries a step size
\code{n}. Units are combined via \code{\link[=new_calendar]{new_calendar()}} to form a complete calendar
system.
}
\details{
Choose the parent class based on the type of time the unit represents:
\itemize{
\item \code{\link{mt_unit}} — abstract or calendar-only time (no timezone or location
context; e.g., Gregorian year or ISO week).
\item \code{\link{mt_tz_unit}} — civil time with a timezone (e.g., a clock hour that
needs \code{tz} to resolve wall-clock ambiguity).
\item \code{\link{mt_loc_unit}} — astronomical time with a geographic location (e.g., a
solar day tied to observer longitude/latitude).
}
}
\examples{
# An abstract unit with no properties
tu_my_seq <- new_time_unit("tu_my_seq", parent = mt_unit)

# A civil-time unit with an extra property
tu_my_quarter <- new_time_unit(
  "tu_my_quarter",
  parent = mt_tz_unit,
  properties = list(
    fiscal = S7::new_property(S7::class_logical, default = FALSE)
  )
)

}
\seealso{
\itemize{
\item \code{\link{mt_unit}}, \code{\link{mt_tz_unit}}, \code{\link{mt_loc_unit}} for the base classes to
inherit from.
\item \code{\link[=new_calendar]{new_calendar()}} for assembling time units into a calendar.
\item \code{\link[S7:new_class]{S7::new_class()}} for the underlying S7 class constructor.
}
}
