/****************************************************************************
*                                                                           *
*   UNWRAPTIME.SPL Copyright 2008 (C) DSP Development Corporation           *
*                                                                           *
*   Author:     Randy Race                                                  *
*                                                                           *
*   Synopsis:   Converts AM/PM time to 24 hour time without day wrapping    *
*                                                                           *
*   Revisions:  27 Aug 2008     RRR     Creation                            *
*                                                                           *
****************************************************************************/

#if @HELP_UNWRAPTIME

    UNWRAPTIME

    Purpose: Converts 12 hour AM/PM time to 24 hour time without day wrapping

    Syntax:  UNWRAPTIME(t, ampm, wrap)

                 t - A series of time values

              ampm - Optional string, the starting time offset. "AM"
                     indicates morning time, "PM" indicates afternoon
                     time. Defaults to "AM".

              wrap - Optional integer, add day values to sequential time
                     changes such that 23:59:59 to 0:0:0 represents the
                     next day.

                       0: do not wrap days (default)
                       1: wrap days

    Returns: A series of time values.

    Example:
             W1: {todstr("12:59"),todstr("1:00"),todstr("1:01")};setvunits("Time")
             W2: unwraptime(w1)

             W2 contains the time values:

             12:59, 13:00, 13:01

    Example:
             W3: {todstr("10:59"), todstr("11:00"), todstr("11:01")};setvunits("Time")
             W4: unwraptime(w3, "pm")

             W4 contains the time values:

             22:59, 23:00, 23:01

    Remarks:
             As shown in the example, AM/PM time values will show an
             apparent discontinuity when the time changes at noon or
             midnight. UNWRAPTIME converts the values to 24 hour time and
             thus removes these discontinuities.

             If wrap is 1, the time values are considered
             sequential such that a change in time from 2359.59 to 0.0
             indicates a change in day.

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


/* convert AM/PM time to 24 hour time */
unwraptime(t, ampm, wrap)
{
        local dt;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("unwraptime - input series required");
                        
                        ampm = "am";
                }
                
                wrap = 0;
        }
        
        ampm = tolower(ampm);

        /* find time discontinuities */
        dt = extract(t - delay(t, 1), 2, length(t));
        dt[length(dt)] = dt[length(dt) - 1];

        /* time offsets */
        dt = partsum(dt < 0) * 43200;

        /* unwrap by adding offsets */
        t = extract(t + delay(dt, 1), 1, length(t));

        /* AM/PM offset */
        if (ampm == "pm") t = t + 43200.0;

        if (wrap != 1)
        {
                /* factor out day changes */
                t = t % 86400;
        }

        return(t);
}