/*****************************************************************************
*                                                                            *
*   XSEREXTRACT.SPL  Copyright (C) 2024 DSP Development Corporation          *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Extract sections of same series based on X values           *
*                                                                            *
*   Revisions:    3 Oct 2024  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_XSEREXTRACT

    XSEREXTRACT

    Purpose: Extracts multiple sections from a series based on X values.


    Syntax:  XSEREXTRACT(s, xstart, xend, offset)

                   s - A series or table, the source series.

              xstart - A series. A list of starting X values.

                xend - A series. A list of ending X values.

              offset - Optional. A series, a list of X offsets for the result.
                       Defaults to XSTART, the starting X values.

    Returns: A series for a series input or a multi-column series for a
             multi-column input.

    Example:
             W1: 0..0.2..2
             W2: xserextract(w1, {0, 0.8, 1.0}, {0.4, 1.2, 1.6})
             W3: concat(xextract(w1, 0, 0.4), xextract(w1, 0.8, 1.2), xextract(w1, 1.0, 1.6))
             W4: w2 - w3

             W1 == {0.0, 0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 1.6, 1.8, 2.0}
             W2 == {0.0, 0.2, 0.4, 0.8, 1.0, 1.2, 1.0, 1.2, 1.4, 1.6}
             W3 == {0.0, 0.2, 0.4, 0.8, 1.0, 1.2, 1.0, 1.2, 1.4, 1.6}
             W4 == {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0}

             W1 contain 11 values ranging from 0.0 to 2.0 with a DELTAX
             of 0.2.

             W2 extracts 3 segments from W1. The segments start at X values
             0, 0.8 and 1.0. The segments end at X values, 0.4, 1.2 and 1.6.
             The segments are combined to produce a single series.

             W3 performs the same operation using CONCAT and XEXTRACT.

             W4 shows that W2 == W3, the two segment extraction operations
             are identical.

    Remarks:
             If XSTART is before the start of the series, zeros are
             prepended to the result. If XEND is beyond the end of
             the series, the result is appended with zeros.

             See SEREXTRACT to perform the extraction with indices.

             See XCOLEXTRACT to extract segments from a series based on X
             values and place the segments into columns.

    See Also:
             Colextract
             Extract
             Serextract
             Xcolextract
             Xextract
             Xtoidx

#endif


/* series extraction using X values */
ITERATE xserextract(s, xstart, xend, xoffset)
{
        local istart, iend, ilen;

        if (argc < 4)
        {
                if (argc < 3)
                {
                        error(sprintf("%s - 3 input series required", __FUNC__));
                }

                xoffset = {};
        }

        /* starting and ending indices */
        istart = xtoidx(s, xstart, 0);
        iend   = xtoidx(s, xend, 0);

        /* segment lengths */
        ilen = abs(iend - istart) + 1;

        /* use serextract to extract segments */
        s = serextract(s, istart, ilen, xoffset);

        return(s);
}