# mixtime 0.1.0

This is the initial CRAN release of the package with provides the core data 
types and temporal manipulation for temporal analysis with mixed granularity
data.

## New features

### Time

* The generic `mixtime()` constructor for creating mixed temporal vectors that 
  combine time points of different granularities (e.g. monthly and quarterly)
  in a single vector via `vecvec`.

### Linear time

* `linear_time()` creates linear time vectors with a user-specified chronon
  (smallest indivisible time granule), supporting both discrete (integer) and
  continuous (fractional) time models.
* Convenience functions for common temporal granularities: `year()`,
  `yearquarter()`, `yearmonth()`, `yearweek()`, `date()`, and `datetime()`.

### Cyclical time

* `cyclical_time()` creates cyclical time vectors representing positions
  within a repeating cycle (e.g. day-of-week, month-of-year).
* Convenience functions for common cyclical temporal granularities:
  `month_of_year()`, `day_of_year()`, `day_of_month()`, `day_of_week()`, 
  `week_of_year()`, and `time_of_day()`.

### Calendar systems

* Three initial calendar systems:
  * `cal_gregorian`: standard Gregorian calendar with year, quarter, month,
    day, hour, minute, second, and millisecond units.
  * `cal_isoweek`: ISO 8601 week-date calendar with ISO year, week, and day
    units. Weeks always start on Monday; the first week of the year is the
    week containing the first Thursday.
  * `cal_sym454`: Symmetry454 perennial solar calendar with a symmetrical
    4–5–4 week pattern per quarter and a leap-week rule.

### Sequences

* `seq()` methods for `mixtime` and `mt_time` objects support integer, string
  (e.g. `"1 month"`), and time unit `by` arguments, as well as `length.out`
  and `along.with`. Overflow behaviour when step granules differ from sequence
  granules can be controlled with `on_invalid = "nearest"` (default) or
  `"overflow"`.

### Rounding

* `round_time()`, `floor_time()`, and `ceiling_time()` round time objects to a
  specified time granule, preserving the input class and timezone.

### Formatting

* A mixed-calendar general purpose formatting system is provided for `mixtime`
  objects. The format strings use glue-like `{}` substitutions with the helper
  functions `lin(x)` and `cyc(x, y)` to position linear and cyclical time
  components in a string. `x` and `y` are time granules from a calendar, which 
  can be used to create general purpose mixed-calendar time formats.

### Timezone support

* `tz_name()` extracts the timezone from a time object.
* `tz_offset()` returns the UTC offset for a datetime in its timezone.
* `tz_abbreviation()` returns the timezone abbreviation (e.g. `"EST"`, `"PDT"`).
* `tz_transitions()` returns a data frame of DST and other timezone transitions
  between two time points.

### Accessor functions

* `time_calendar()` extracts the calendar system from a time object.

### tsibble and fable compatibility

* Methods for `tsibble` index validation are provided, enabling `mixtime`
  vectors to be used as time indexes in `tsibble` objects and in forecasting
  with `fable`.

### Extensibility

* `new_calendar()` defines a calendar as a named collection of time unit
  classes, with optional inheritance from another calendar.
* `mt_unit()`, `mt_tz_unit()`, and `mt_loc_unit()` primitives for creating
  new time units.
* `new_linear_time_fn()` and `new_cyclical_time_fn()` are factories for building
  convenient linear and cyclical time functions (e.g. `yearmonth()`).
* Calendar arithmetic with:

  * `chronon_divmod()` performs division-with-remainder arithmetic between time
    granules (e.g. 1 day to 1 month), enabling cross-granule calendrical 
    arithmetic.
  * `chronon_cardinality()` returns the number of smaller granules contained in 
    a coarser granule (e.g. days in 1 month), with context-dependent results for
    variable-length granules.
  * `chronon_epoch()` returns the epoch offset for a given time unit.

* Displaying time with:

  * `time_unit_abbr()` and `time_unit_full()` for time unit text.
  * `linear_labels()` and `cyclical_labels()` for time labels (e.g. Jan, Feb,
     ... for months of year).
  * `chronon_format_linear()` and `chronon_format_cyclical()` for default
    formatting strings.
  * `chronon_format_attr()` for appending attribute information (e.g. timezones)

### Vignettes

* Extending mixtime - a vignette on how to define new calendars and implement
  calendar arithmetic for temporal operations within the calendar's units and
  with other calendars.
