Removal of time type restriction for add, subtract, and delta operations

[calvin.harman@…]

I'd like to remove the restriction that time math be only done on the TAI time
type (page 42 Version 8 of psLib SDRS). As long as both arguments to these
functions have the same time type, the operation should be allowed, but an
error should be generated if the types differ.

[Paul Price]

"Math" on times in UTC is complicated due to leap seconds.

I suggest that the restriction on subtraction may be dropped if the function
automatically converts to TAI before performing the math. For time addition, I
am hesitant --- this function would be used to add a small time difference to a
time, but the function doesn't know which of the inputs is the time and which is
the time difference, so it doesn't know which to convert.

I would appreciate Josh's input.

[jhoblitt]

I also share Paul's concerns about addition but also have the exact same concern
about subtraction. I believe the solution is to add a PS_TIME_DELTA type to
psTimeType. psTimeAdd and psTimeSubract would then require two psTime structs
as arguments. One being a validate time type and the other being a
PS_TIME_DELTA. The time would be converted to TAI, the delta applied, then the
time is converted back to it's original type and returned.

[Paul Price]

I hadn't realised that we had already specified differences in time as being
psF64 instead of psTimes. Is there a need for a PS_TIME_DELTA type, or is using
psF64 sufficient? (I think the latter.)

I changed the SDRS assuming that psF64 is fine for time differences. The idea
is that the psTime{Add,Subtract,Delta} functions perform dynamic conversion:

\begin{verbatim}
psTime *psTimeAdd(const psTime *time, psF64 delta);
psF64 psTimeSubtract(const psTime *time1, const psTime *time2);
psF64 psTimeDelta(const psTime *time1, const psTime *time2);
\end{verbatim}
\code{psTimeAdd} adds some time to a \code{psTime}.
\code{psTimeSubtract} subtracts two times. \code{psTimeDelta} gives
the absolute time difference between two times.

Time math may only be done on the \code{psTime} TAI type, and so the
functions shall internally convert the \code{psTime} inputs to TAI before
performing the math. The type of the time returned by
\code{psTimeAdd} shall be the same as that of the input \code{time}.

[calvin.harman@…]

I don't think that these functions should add or subtract leapseconds to its
UTC or TAI arguments. Addition or subtraction of leapseconds implies conversion
to/from UTC/TAI. What I had in mind was to simply be able to add or subtract
two times, and allow the user to make conversions with the appropriate
conversion function afterwards. As long as you don't allow arguments to this
function to consist of mixed types, this shouldn't be a problem, should it?

Also, I'd prefer to keep the return types for these functions as psTime, not
psF64, since we use the results of these functions in other psTime functions
that take psTime arguments.

[jhoblitt]

Adding/subtracting seconds for a UTC data has to include the leapsecond
correction or we're going to end up with a real mess when we try to compare to
times.

psF64 works fine for expressing deltas but I don't like the way psTimeSubtract
is returning a psF64 instead of a *psTime. psTimeSubtract is doing what
psTimeDelta was intended for and subtracting a time by adding a negative delta
with psTimeAdd just seems funny to me. I'd rather the API be symmetric ( I
think Ross and I agree here)...

psTime *psTimeAdd(const psTime *time, psF64 delta);
psTime *psTimeSubtract(const psTime *time, psF64 delta);
psF64 psTimeDelta(const psTime *time1, const psTime *time2);

[calvin.harman@…]

I caught the problem with the add function, regarding the overflow in
microseconds after the release.

I'm still not clear on why it's necessary to add leapseconds to UTC time when
adding two numbers. I thought it was the responsibility of the psTimeConvert
function to convert from TAI to UTC, which could be done to the psTime value
after the addition. Also, as a result of the discussions below, I'm not sure my
implementations of the add, subtract, and delta functions are what you're
looking for. It would be helpful if the SDRS or ADD were updated to include a
more detailed description, since there's currently only one or two lines of
description. Some examples would also be useful.

[Paul Price]

OK, reworked the section on the math a bit. Since the psTimeAdd and
psTimeSubtract were near identical, I combined them into a single psTimeMath,
that adds a given number of SI seconds to a psTime. psTimeDelta subtracts two
psTimes, returning the number of SI seconds between the two. Note that I say
"SI seconds", to distinguish between real seconds and leap seconds. Leap
seconds are supposed to be handled by psLib internally --- the user should never
notice. And so, if time math crosses a leap second boundary, care has to be
taken. This is why we specify that times are converted to TAI before math is
performed, since that takes care of all the worrying about leap seconds.

\subsubsection{Date and Time Math}

\begin{verbatim}
psTime *psTimeMath(const psTime *time, psF64 delta);
psF64 psTimeDelta(const psTime *time1, const psTime *time2);
\end{verbatim}
\code{psTimeMath} adds the \code{delta} (in seconds; may be negative)
to a \code{psTime}. \code{psTimeDelta} gives
the difference between times \code{time1} and \code{time2} (which may
be negative).

Note that in both these, the difference between two times is to be
expressed in \textit{SI} seconds, and not inclusive of leap seconds.
For example, if we add 30 seconds to 1998-12-31T23:59:45Z, the result
is 1999-01-01T00:00:14Z, since a leap second was introduced at
1999-01-01T00:00:00Z.

Time math may only be done on the \code{psTime} TAI type, and so the
functions shall internally convert the \code{psTime} inputs to TAI
before performing the math; this is in order that leap seconds are
accounted for.

The type of the time returned by \code{psTimeMath} shall be the same
as that of the input \code{time}.

[Paul Price]

Closing subsequent to release of SDRS-08, ADD-07.