/****************************************************************************
*                                                                           *
*   LOCAL2UTC.SPL Copyright 2024 (C) DSP Development Corporation            *
*                                                                           *
*   Author:       Randy Race                                                *
*                                                                           *
*   Synopsis:     Convert local date time to UTC date time                  *
*                                                                           *
*   Revisions:    1 Nov 2024     RRR     Creation                           *
*                                                                           *
****************************************************************************/


#if @HELP_LOCAL2UTC

    LOCAL2UTC

    Purpose: Converts local date time values to UTC date time values.

    Syntax:  LOCAL2UTC(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 string or series, the date and time of the input values
             in UTC.

    Example:
             local2utc()

             Returns the current date and time as a string in UTC.
            
    Example:
             local2utc("1-1-2024", "12:00:00", "America/New_York")

             Returns "1-01-2024 17:00:00", the corresponding UTC date time
             of noon on January 1, 2024 in the US Eastern time zone.

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

             Returns "1-01-2024 20:00:00", the corresponding UTC date time
             of January 1, 2024 in the US Pacific time zone.

   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: local2utc(W1, "America/Chicago")

             W2 contains the date time:

               11-03-2024  6:59:00
               11-03-2024  8:01:00

             the corresponding UTC date time of the date times in the US
             Central time zone 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.

   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: local2utc(W1, "America/Chicago")
             W3: utc2local(W2, "America/Chicago")

             Same as above except W3 converts the UTC values in W2 back
             into local values. Both W1 and W3 contain:

               11-03-2024  1:59:00
               11-03-2024  2:01:00
                        
   Example:
             W1: {ymdhms2dt(2024, 11, 3, 1, 59, 0), ymdhms2dt(2024, 11, 3, 2, 1, 0)}
             W2: local2utc(W1, "America/Chicago")
             W3: utc2local(W2, "America/Chicago")

             Same as above except the date and time values are entered in
             YMDHMS format. Both W1 and W3 contain:

               11-03-2024  1:59:00
               11-03-2024  2:01:00
                        
    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.

             LOCAL2UTC converts local date and times within a specified time
             zone to UTC date and times.

             The TIMEZONE string is case sensitive and should adhere to 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 UTC2LOCAL to convert UTC date time data to local date time.

             See TZCONVERT to convert date time values to a target time zone.

    See Also:
             CLOCK
             GETDATE
             GETDT
             GETTIME
             TZCONVERT
             UTC2LOCAL
             YMDHMS2DT
#endif


/* convert local time to UTC time */
local2utc(locdate = "", loctime = "", timezone = "")
{
        local isstring, utcdate, utctime, dt;
 
        (locdate, loctime, timezone, isstring) = utc_parse_args(locdate, loctime, timezone);

        if (outargc > 1)
        {
                /* date and time */
                (utcdate, utctime) = local2utc_iterate(locdate, loctime, timezone, isstring);

                return(utcdate, utctime);
        }
        else
        {
                dt = local2utc_iterate(locdate, loctime, timezone, isstring);

                return(dt);
        }
}


ITERATE local2utc_iterate(locdate, loctime, timezone, isstring)
{
        local utcdate, utctime, msec, dt;
 
        /* date and time */
        (utcdate, utctime) = convertutc(locdate, loctime, 0, timezone);

        /* Real Time if time has fractional part */
        msec = any((utctime - int(utctime)) % 1);

        if (isstring)
        {
                /* return strings */
                utcdate = strjul(utcdate[1]);
                utctime = (msec) ? strtodmsec(utctime[1]) : strtod(utctime[1]);

                if (outargc > 1)
                {
                        return(utcdate, utctime);
                }
                else
                {
                        return(utcdate + " " + utctime);
                }
        }
        else
        {
                setmatrix(utcdate, 0);
                setmatrix(utctime, 0);

                utcdate.vunits = "Date";
                utctime.vunits = (msec) ? "Real Time" : "Time";

                if (outargc > 1)
                {
                        return(utcdate, utctime);
                }
                else
                {
                        dt = ravel(utcdate, utctime);
                        setplotstyle(dt, 4);

                        return(dt);
                }
        }
}