/****************************************************************************
*                                                                           *
*   UNIX2DT.SPL Copyright 2024 (C) DSP Development Corporation              *
*                                                                           *
*   Author:     Randy Race                                                  *
*                                                                           *
*   Synopsis:   Converts UNIX seconds to Julian date and seconds            *
*                                                                           *
*   Revisions:   2 Nov 2024     RRR     Creation                            *
*                                                                           *
****************************************************************************/


#if @HELP_UNIX2DT

    UNIX2DT

    Purpose: Converts UNIX timestamp to Julian date and clock seconds.

    Syntax:  UNIX2DT(ut, offset, startdate)

             (d, t) = UNIX2DT(ut, offset, startdate)

                     ut - A series of UNIX format time stamps.

                 offset - Optional. A real, the time offset in seconds.
                          Defaults to 0.0.

              startdate - Optional. A string, the starting date. Defaults
                          to "1-1-1970".

    Returns: A two column series of dates and clock time.

             (d, t) = unix2dt(ut) returns the dates and clock
             time in two separate variables.

    Example:
             W1: {1407159000, 1408159082, 1411150163, 1417159180, 1427159240}
             W2: unix2dt(W1)

             W2 contains the date and time values:

              8-04-2014  13:30:00
              8-16-2014   3:18:02
              9-19-2014  18:09:23
             11-28-2014   7:19:40
              3-24-2015   1:07:20

    Example:
             W3: {1407159000, 1408159082, 1411150163, 1417159180, 1427159240}
             W4: (d, t) = unix2dt(W3); ravel(d, t)

             W4 contains the date and time values:

              8-04-2014  13:30:00
              8-16-2014   3:18:02
              9-19-2014  18:09:23
             11-28-2014   7:19:40
              3-24-2015   1:07:20

    Remarks:
             UNIX timestamps are generally in seconds elapsed since
             midnight January 1, 1970 UTC time. UNIX2DT converts the
             UNIX second values into date and clock time for the day.

    See Also:
             DT2UNIX
             DTXY
             JULSTR
             STRJUL
             STRTOD
             TODSTR
             XYDT
#endif


/* convert UNIX timestamps to date/time */
ITERATE unix2dt(ut = dt2unix(), offset = 0, startdate = "1-1-1970")
{
        local days, jul, secs, dt, vunits, frac, utoff;

        /* force series */
        ut = {ut};

        utoff = ut + offset;
        frac  = utoff - int(utoff);

        /* Real Time if total time has fractional part */
        vunits = any(frac % 1) ? "Real Time" : "Time";

        /* unix timestamp in seconds to days */
        days = int(utoff / 86400);

        /* offset by julian start date */
        jul = days + julstr(startdate);

        /* seconds */
        secs = utoff - days * 86400;

        setmatrix(jul, 0);
        setvunits(jul, "Date");

        setmatrix(secs, 0);
        setvunits(secs, vunits);

        if (jul[1] > 0)
        {
                /* set date of time series to first date */
                setdate(secs, strjul(jul[1], 0));
        }

        if (outargc > 1)
        {
                return(jul, secs);
        }
        else
        {
                /* return as table */
                dt = ravel({jul}, {secs});
                setplotstyle(dt, 4);

                return(dt);
        }
}