/****************************************************************************
*                                                                           *
*   DT2DATE.SPL   Copyright 2024 (C) DSP Development Corporation            *
*                                                                           *
*   Author:       Randy Race                                                *
*                                                                           *
*   Synopsis:     Converts date time to fractional Julian date              *
*                                                                           *
*   Revisions:    10 Nov 2024     RRR     Creation                          *
*                                                                           *
****************************************************************************/


#if @HELP_DT2DATE

    DT2DATE

    Purpose: Converts date time values to fractional Julian date values.

    Syntax:  DT2DATE(date, time, "timezone")

                    date - Optional. A string or integer Julian date, the
                           input date. Defaults to the current date.

                    time - Optional. A string or real TOD, the input time.
                           Defaults to the current time.

              "timezone" - Optional. A string, the local time zone. Defaults
                           to the current time zone. If specified, the
                           resulting timestamps are based on the UTC time
                           offset UTC time.

    Alternate Syntax:  DT2DATE(datetime, "timezone")

                datetime - An array, the date and time values in adjacent
                           columns.

              "timezone" - Optional. A string, the local time zone. Defaults
                           to the current time zone. If specified, the
                           timestamps are based on UTC time.

    Returns: A series of fractional Julian date values.

    Example:
             W1: dt2date()

             W1 contains a 1x1 series with the current date and time as
             fractional Julian date,

    Example:
             W2: dt2date("1-1-2024", "12:30:00")

             W2 contains a 1x1 series with the following value:

             {2460311.020833}

    Example:
             W2: dt2date("1-1-2024", "12:30:00")
             W3: date2dt(w2)

             Same as above except W3 converts the fractional Julian date
             value in W2 to a date time series. W3 contains the date time:

             1-1-2024 12:30:00

    Example:
             W1: {{2030, 10, 30, 18, 0, 0},
                  {2030, 10, 31,  0, 0, 0},
                  {2030, 10, 31,  6, 0, 0},
                  {2030, 10, 31, 12, 0, 0}}

             W2: ymdhms2dt(w1)
             W3: dt2date(w2)
             W4: date2dt(w3)

             W1 contains raw date time values in year, month, date, hours,
             minutes, seconds format.

             W2 converts the raw YMDHMS values in W1 to date time values. W2
             contains the date times:

               10-30-2030 18:00:00
               10-31-2030 00:00:00
               10-31-2030 06:00:00
               10-31-2030 12:00:00

             W3 converts the date time values of W2 into fractional Julian
             dates. W3 contains the values:

               {2462805.25,
                2462805.50, 
                2462805.75,
                2462806.00}

             W4 converts the fractional Julian date values in W3 to date time
             values. W4 contains the same date time values as W2:

               10-30-2030 18:00:00
               10-31-2030 00:00:00
               10-31-2030 06:00:00
               10-31-2030 12:00:00

    Remarks:
             DT2DATE converts a date time series to fractional or
             astronomical Julian date values.

             A fractional Julian day is the number of days since
             January 1, 4713 BC at noon UTC time. For example, a fraction
             of 0.25 represents time 18:00:00 or 6 hours (one quarter of a
             day) after noon.

             A date time series consists of 2 columns of values where the
             first column is an integer Julian date starting at midnight
             and the second column is time in seconds starting from
             midnight.

             See DATE2DT to convert fractional Julian date values to date
             time values.

    See Also:
             DATE2DT
             DT2UNIX
             DT2YMDHMS
             GETDT
             YMDHMS2DT
#endif


/* convert date and time to fractional Julian days */
dt2date(date = getdate(), time = gettime(13), timezone = "")
{
        local yr, mo, dy, hr, mn, ss, frac;

        (date, time, timezone, isstring) = utc_parse_args(date, time, timezone, TRUE, FALSE);

        if (strlen(timezone) > 0)
        {
                /* convert to UTC */
                (date, time) = local2utc(date, time, timezone);
        }

        (yr, mo, dy, hr, mn, ss) = dt2ymdhms(date, time);

        /* julian days */
        dd = ymd2date(yr, mo, dy);

        /* fractional days */
        frac = hr / 24 + mn / 1440 + ss / 86400;

        /* fractional julians are from 12:00 noon */
        dd += frac - 0.5;

        setvunits(dd, "Days", -1);
        
        return(dd);
}