/*****************************************************************************
*                                                                            *
*   DATE2YMD.SPL Copyright (C) 2024 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Converts Julian date to years, months, days                 *
*                                                                            *
*   Revisions:    2 Dec 2024  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_DATE2YMD

    DATE2YMD

    Purpose: Converts Julian date series to years, months and days.

    Syntax:  DATE2YMD(date)

             (years, months, days) = DATE2YMD(date)

              date   - A scalar or series, the Julian date values.


    Returns: An Nx3 array of year, month and day values.

             (years, months, days) = DATE2YMD(date) returns the years,
             months and day components in separate variables.

    Example:
             W1: date2ymd(2462806)

             W1 == {{2030, 10, 31}}, a 1x3 series representing 2030 years,
             10 months and 31 days.

    Example:
             W2: date2ymd(julstr("2030-10-31"))

             Same as above, except the date value is entered as a string
             to the JULSTR function.

    Example:
             (y, m, d) = date2ymd(julstr("2030-10-31"))

             Same as above, except the time components are returned in three
             separate series variables.

             y == {2030}
             m == {10}
             d == {31}

    Example:
             W1: ymd2date({2010, 2020, 2030}, {5, 6, 7}, {1, 2, 3})
             W2: date2ymd(w1)

             W1 contains the date values:

                5/1/2010
                6/2/2020
                7/3/2030

             W2 converts the date values in W1 to individual date components
             replicating the input values of W1.

             W2 == {{2010, 5, 1},
                    {2020, 6, 2},
                    {2030, 7, 3}}

    Remarks:
             DATE2YMD creates a date component series by converting individual
             Julian day values to years, months and day values.

             A Julian day is the number of days since January 1, 4713 BC at
             noon UTC time.

             See YMD2DATE to create Julian day values from years, months,
             and day values.
             
    See Also:
             Date2ymd
             Hms2time
             Julstr
             Strjul
             Ymd2date
#endif


/* convert Julian date to year, month, day */
date2ymd(date)
{
        local y, m, d, ymd;

        if (argc == 0)
        {
                /* current date string */
                date = getdate();
        }

        if (isstring(date))
        {
                if (isdatestr(date))
                {
                        date = julstr(date);
                }
                else
                {
                        error(sprintf("%s - unrecognized date '%s'", __FUNC__, date));
                }
        }

        /* internal conversion - force series */
        (y, m, d) = ymdfromjul({date});

        if (outargc > 1)
        {
                return(y, m, d);
        }
        else
        {
                ymd = ravel(y, m, d);
                settable(ymd);

                return(ymd);
        }
}