@callback date_to_string(year(), month(), day()) :: String.t()

Converts the date into a string according to the calendar.

@callback datetime_to_string(
  year(),
  month(),
  day(),
  hour(),
  minute(),
  second(),
  microsecond(),
  time_zone(),
  zone_abbr(),
  utc_offset(),
  std_offset()
) :: String.t()

Converts the datetime (with time zone) into a string according to the calendar.

@callback day_of_era(year(), month(), day()) :: day_of_era()

Calculates the day and era from the given year, month, and day.

@callback day_of_week(year(), month(), day()) :: day_of_week()

Calculates the day of the week from the given year, month, and day.

@callback day_of_year(year(), month(), day()) :: non_neg_integer()

Calculates the day of the year from the given year, month, and day.

@callback day_rollover_relative_to_midnight_utc() :: day_fraction()

Define the rollover moment for the given calendar.

This is the moment, in your calendar, when the current day ends and the next day starts.

The result of this function is used to check if two calendars rollover at the same time of day. If they do not, we can only convert datetimes and times between them. If they do, this means that we can also convert dates as well as naive datetimes between them.

This day fraction should be in its most simplified form possible, to make comparisons fast.

Examples

• If, in your Calendar, a new day starts at midnight, return {0, 1}.
• If, in your Calendar, a new day starts at sunrise, return {1, 4}.
• If, in your Calendar, a new day starts at noon, return {1, 2}.
• If, in your Calendar, a new day starts at sunset, return {3, 4}.

@callback days_in_month(year(), month()) :: day()

Returns how many days there are in the given year-month.

@callback leap_year?(year()) :: boolean()

Returns true if the given year is a leap year.

A leap year is a year of a longer length than normal. The exact meaning is up to the calendar. A calendar must return false if it does not support the concept of leap years.

@callback months_in_year(year()) :: month()

Returns how many months there are in the given year.

@callback naive_datetime_from_iso_days(iso_days()) ::
  {year(), month(), day(), hour(), minute(), second(), microsecond()}

Converts iso_days/0 to the Calendar's datetime format.

@callback naive_datetime_to_iso_days(
  year(),
  month(),
  day(),
  hour(),
  minute(),
  second(),
  microsecond()
) :: iso_days()

Converts the given datetime (without time zone) into the iso_days/0 format.

@callback naive_datetime_to_string(
  year(),
  month(),
  day(),
  hour(),
  minute(),
  second(),
  microsecond()
) :: String.t()

Converts the datetime (without time zone) into a string according to the calendar.

@callback parse_date(String.t()) :: {:ok, {year(), month(), day()}} | {:error, atom()}

Parses the string representation for a date returned by date_to_string/3 into a date-tuple.

@callback parse_naive_datetime(String.t()) ::
  {:ok, {year(), month(), day(), hour(), minute(), second(), microsecond()}}
  | {:error, atom()}

Parses the string representation for a naive datetime returned by naive_datetime_to_string/7 into a naive-datetime-tuple.

The given string may contain a timezone offset but it is ignored.

@callback parse_time(String.t()) ::
  {:ok, {hour(), minute(), second(), microsecond()}} | {:error, atom()}

Parses the string representation for a time returned by time_to_string/4 into a time-tuple.

@callback parse_utc_datetime(String.t()) ::
  {:ok, {year(), month(), day(), hour(), minute(), second(), microsecond()},
   utc_offset()}
  | {:error, atom()}

Parses the string representation for a datetime returned by datetime_to_string/11 into a datetime-tuple.

The returned datetime must be in UTC. The original utc_offset it was written in must be returned in the result.

@callback quarter_of_year(year(), month(), day()) :: non_neg_integer()

Calculates the quarter of the year from the given year, month, and day.

@callback time_from_day_fraction(day_fraction()) ::
  {hour(), minute(), second(), microsecond()}

Converts day_fraction/0 to the Calendar's time format.

@callback time_to_day_fraction(hour(), minute(), second(), microsecond()) ::
  day_fraction()

Converts the given time to the day_fraction/0 format.

@callback time_to_string(hour(), minute(), second(), microsecond()) :: String.t()

Converts the time into a string according to the calendar.

@callback valid_date?(year(), month(), day()) :: boolean()

Should return true if the given date describes a proper date in the calendar.

@callback valid_time?(hour(), minute(), second(), microsecond()) :: boolean()

Should return true if the given time describes a proper time in the calendar.

@callback year_of_era(year()) :: {year(), era()}

Calculates the year and era from the given year.