/****************************************************************************
*                                                                           *
*   UTCTIMEOFFSET.SPL Copyright 2024 (C) DSP Development Corporation        *
*                                                                           *
*   Author:       Randy Race                                                *
*                                                                           *
*   Synopsis:     Returns the time difference to UTC time                   *
*                                                                           *
*   Revisions:    1 Nov 2024     RRR     Creation                           *
*                                                                           *
****************************************************************************/


#if @HELP_UTCTIMEOFFSET

    UTCTIMEOFFSET

    Purpose: Returns the time difference in seconds between local time and
             UTC.

    Syntax:  UTCTIMEOFFSET(locdate, loctime, "timezone")

               locdate - Optional. A string or series of dates, the local
                         date. Defaults to the current date.

               loctime - Optional. A string or series of times, the local
                         time. Defaults to the current time.

              timezone - Optional. A string, the local time zone. Defaults
                         to the current time zone.


    Returns: A real, the number of seconds between the local date and time
             in the time zone and UTC.

    Example:
             utctimeoffset()

             Returns the number of seconds between the current date and time
             in the current time zone and UTC.
            
    Example:
             utctimeoffset() / 3600

             Returns the number of hours between the current date and time
             in the current time zone and UTC.
            
    Example:
             utctimeoffset("1-1-2024", "12:00:00", "America/New_York") / 3600

             Returns -5, the number of hours between noon on January 1, 2024
             in the US Eastern time zone and UTC.

    Example:
             utctimeoffset("1-1-2024", "12:00:00", "America/Los_Angeles") / 3600

             Returns -8, the number of hours between noon on January 1, 2024
             in the US Pacific time zone and UTC.

   Example:
             dt =  {{julstr("2024-11-03"), todstr("1:59:00")},
                    {julstr("2024-11-03"), todstr("2:01:00")}};

             W1: dt;setvunits(w0, "date", 1, 1);setvunits(w0, "time", 1, 2)
             W2: utctimeoffset(W1, "America/Chicago") / 3600

             W2 == {-5, -6} the number of hours between the US Central time
             zone and UTC for Daylight Savings Time and Standard Time since
             Central Daylight Savings time changed to Central Standard time
             on November 3, 2024 at 2:00 am.
                        
    Remarks:
             UTC stands for Coordinated Universal Time and is a reference
             time for all time zones worldwide. UTC is historically linked
             to Greenwich Mean Time (GMT), but is more precise.

             UTCTIMEOFFSET returns the number of seconds between a local
             date and time and UTC date and time. Divide the result by 3600
             to obtain hours.

             A positive offset indicates the time zone is ahead of UTC and
             a negative offset indicates the time zone is behind UTC.

             The TIMEZONE string is case sensitive should adhere to the the
             IANA timezone identifiers available at:

               https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

             and:
      
               https://www.iana.org/time-zones

             If TIMEZONE is blank or "local", the local time zone is used.

    See Also:
             CLOCK
             GETDATE
             GETDT
             GETTIME
#endif


/* local time difference from UTC time in seconds */
utctimeoffset(locdate = "", loctime = "", timezone = "")
{
        local utcdiff, isstring = 0;

        /* parse args  - inputs are local date/time */
        (locdate, loctime, timezone, isstring) = utc_parse_args(locdate, loctime, timezone);

        utcdiff = utctimeoffset_iterate(locdate, loctime, timezone);

        return(utcdiff);
}


ITERATE utctimeoffset_iterate(locdate, loctime, timezone)
{
        local utcdiff, isstring = 0;

        if (isempty(locdate))
        {
                /* only time values */
                utcdiff = convertutc(loctime, -1, timezone);
        }
        else
        {
                /* date and time */
                utcdiff = convertutc(locdate, loctime, -1, timezone);
        }

        setvunits(utcdiff, "Seconds");

        if (isstring)
        {
                utcdiff = utcdiff[1];
        }

        return(utcdiff);
}