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


#if @HELP_UTC2LOCAL

    UTC2LOCAL

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

    Syntax:  UTC2LOCAL(utcdate, utctime, "timezone")

               utcdate - Optional. A string or series of dates, the UTC
                         date. Defaults to the current date.

               utctime - Optional. A string or series of times, the UTC
                         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 local date time.

    Example:
             utc2local()

             Returns the current date and time as a string in local time.
            
    Example:
             utc2local("1-1-2024", "12:00:00", "America/New_York")
       
             Returns "1-01-2024 7:00:00", the corresponding local date time
             in the US Eastern time zone of noon on January 1, 2024 in UTC.

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

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

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

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

             W2 contains the date time:

               11-03-2024  1:59:00
               11-03-2024  2:01:00

             the corresponding local 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("6:59:00")},
                    {julstr("2024-11-03"), todstr("8:01:00")}};

             W1: dt;setvunits(w0, "date", 1, 1);setvunits(w0, "time", 1, 2)
             W2: utc2local(W1, "America/Chicago")
             W3: local2utc(W2, "America/Chicago")

             Both W1 and W3 contains the date time:

               11-03-2024  6:59:00
               11-03-2024  8: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.

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

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

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

    See Also:
             CLOCK
             GETDATE
             GETDT
             GETTIME
             LOCAL2UTC
             TZCONVERT
#endif


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

        /* parse args, return as series */
        (utcdate, utctime, timezone, isstring) = utc_parse_args(utcdate, utctime, timezone, FALSE);

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

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

                return(dt);
        }
}


ITERATE utc2local_iterate(utcdate, utctime, timezone, isstring)
{
        local locdate, loctime, msec, dt;

        /* date and time */
        (locdate, loctime) = convertutc(utcdate, utctime, 1, timezone);

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

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

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

                locdate.vunits = "Date";
                loctime.vunits = (msec) ? "Real Time" : "Time";

                if (outargc > 1)
                {
                        return(locdate, loctime);
                }
                else
                {
                        dt = ravel(locdate, loctime);
                        setplottype(dt, 4);

                        return(dt);
                }
        }
}