@spec add(Feel.Value.t(), Feel.Value.t()) :: outcome()

Adds two values, one of which is a date, a time or a date and time and the other a duration.

iex> {:ok, date} = Feel.Runtime.Temporal.add(~D[2021-01-31], Feel.Value.YearsAndMonthsDuration.new(1))
iex> date
~D[2021-02-28]
iex> {:ok, date} = Feel.Runtime.Temporal.add(~D[2021-01-01], Feel.Value.DaysAndTimeDuration.new(36 * 3600))
iex> date
~D[2021-01-02]

@spec compare(
  :time | :date_and_time,
  Feel.Value.Time.t() | Feel.Value.DateTime.t(),
  Feel.Value.Time.t() | Feel.Value.DateTime.t()
) :: {:ok, :lt | :eq | :gt} | {:error, Feel.Diagnostic.t()}

Compares two times, or two dates and times, and says whether the first is before, equal to or after the second: {:ok, :lt | :eq | :gt}. It is {:error, diagnostic} for a zone that is not in the time zone database.

The instants are compared when both have a zone, and the local fields when one has none (see the table above). The resolution is the second: 10:30:00.0001 and 10:30:00.0002 are equal, as the TCK has it (0068#time_005), and so for the other four operators, so that they stay consistent with =.

iex> {:ok, a} = Feel.Value.DateTime.parse("2002-04-02T12:00:00-01:00")
iex> {:ok, b} = Feel.Value.DateTime.parse("2002-04-02T17:00:00+04:00")
iex> Feel.Runtime.Temporal.compare(:date_and_time, a, b)
{:ok, :eq}
iex> {:ok, a} = Feel.Value.DateTime.parse("2018-12-08T00:00:00@Europe/Paris")
iex> {:ok, b} = Feel.Value.DateTime.parse("2018-12-08T00:00:00@Asia/Dhaka")
iex> Feel.Runtime.Temporal.compare(:date_and_time, a, b)
{:ok, :gt}

@spec seconds(Feel.Value.Time.t() | Feel.Value.DateTime.t()) ::
  {:floating, integer()} | {:zoned, integer()} | {:error, Feel.Diagnostic.t()}

The whole seconds that compare/3 looks at in a time or a date and time: {:floating, local} for one with no time offset or zone, and {:zoned, instant} for one that has either. Two floating values are equal as compare/3 says exactly when their local is the same, and two zoned ones when their instant is (a time of day less the offset for a time, the seconds since the start of year 0 for a date and time). A floating value and a zoned one are compared by their local fields, which this does not give, and equality between them is not transitive (see the table above): 10:00:00+01:00 is equal to 10:00:00 and that to 10:00:00Z, and the first is not equal to the third. It is {:error, diagnostic} for a zone that is not in the time zone database.

iex> {:ok, a} = Feel.Value.Time.parse("10:00:00+01:00")
iex> {:ok, b} = Feel.Value.Time.parse("09:00:00Z")
iex> Feel.Runtime.Temporal.seconds(a) == Feel.Runtime.Temporal.seconds(b)
true
iex> {:ok, floating} = Feel.Value.Time.parse("10:00:00.5")
iex> Feel.Runtime.Temporal.seconds(floating)
{:floating, 36_000}

@spec subtract(Feel.Value.t(), Feel.Value.t()) :: outcome()

Subtracts the second value from the first: a duration from a date, a time or a date and time, or a date, a time or a date and time from another of the same kind (a date and a date and time mix).

iex> {:ok, difference} = Feel.Runtime.Temporal.subtract(~D[2021-01-02], ~D[2021-01-01])
iex> Decimal.to_string(difference.seconds)
"86400"
iex> {:ok, date} = Feel.Runtime.Temporal.subtract(~D[2021-01-02], Feel.Value.DaysAndTimeDuration.new(3600))
iex> date
~D[2021-01-01]

@spec value(Date.t() | Feel.Value.Time.t() | Feel.Value.DateTime.t()) ::
  {:ok, Decimal.t()} | {:error, Feel.Diagnostic.t()}

The value property of a date, a time or a date and time (Table 67, D-68): the number that the specification's value function gives, in seconds.

The number is exact up to 34 digits, as every number is.

iex> Feel.Runtime.Temporal.value(~D[1970-01-02])
{:ok, Decimal.new(86400)}
iex> {:ok, date_time} = Feel.Value.DateTime.parse("1970-01-01T01:00:00.5+01:00")
iex> Feel.Runtime.Temporal.value(date_time)
{:ok, Decimal.new("0.5")}
iex> {:ok, time} = Feel.Value.Time.parse("00:30:00+01:00")
iex> Feel.Runtime.Temporal.value(time)
{:ok, Decimal.new(-1800)}
iex> {:ok, floating} = Feel.Value.DateTime.parse("1970-01-01T00:00:00")
iex> {:error, %Feel.Diagnostic{code: :invalid_property}} = Feel.Runtime.Temporal.value(floating)