unit_scheme: Describe a time unit's naming scheme

View source: R/01_time_unit.R

unit_schemeR Documentation

Describe a time unit's naming scheme

Description

Builds the function a unit_labels() method is: assign its result directly, e.g. method(unit_labels, granule) <- unit_scheme(...). A unit scheme names a granule itself, e.g. the "month" in "3 months", and is the single source of truth for every output that renders a count of a unit: duration formatting and parsing (dur() tokens), granule labels (format(month(3L))), tsibble interval displays and messages.

Usage

unit_scheme(vocab, symbol = "", locale = NULL)

unit_labels(granule, ...)

Arguments

vocab

A function ⁠function(type = NULL, locale = NULL)⁠ returning either the full named list of renderings for one locale (type = NULL), or one rendering (e.g. vocab("wide")), as for a label_scheme(). Each rendering is a cli-style plural template, e.g. "day{?/s}" or "{?zero/one/other}". The "wide" type gives the unit's full name. vocab_table() builds this from a plain lookup table.

symbol

A short identifier for the unit, e.g. "D". It is used as the prefix of default format strings, in abbreviated label fallbacks (e.g. "5Y") and when parsing durations. Symbols are not localised, and should be distinct across units (e.g. "M" for month and "m" for minute).

locale

A caller-overridable default locale, selecting which vocab() entry to use by default.

granule

A time granule instance (e.g. cal_gregorian$month(1L)).

...

Unused; only present for S7 dispatch.

Details

method(unit_labels, cal_gregorian$month) <- unit_scheme(
  vocab = vocab_table(`en-GB` = list(wide = "month{?/s}")),
  symbol = "M"
)

This differs from a label_scheme(), which labels the values of a granule (e.g. "March" or "2024") rather than the granule itself, but the two share the same vocab and locale fields.

Value

A function function(granule) list(vocab =, symbol =, locale =), assignable directly as a unit_labels() method. granule is only used for dispatch: a scheme describes a granule class, not the instance a method happens to be called with.

See Also

unit_labels(), the generic a scheme is returned from; label_scheme() for labelling the values of a granule; vocab_table() for the common hand-listed name table case.

Examples

scheme <- unit_labels(cal_gregorian$year(1L))
scheme$vocab("wide")
scheme$symbol


mixtime documentation built on Nov. 18, 2026, 5:08 p.m.