/*****************************************************************************
*                                                                            *
*   XCOLEXTRACT.SPL  Copyright (C) 2021 DSP Development Corporation          *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Extract sections based on X values                          *
*                                                                            *
*   Revisions:    1 Feb 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_XCOLEXTRACT

    XCOLEXTRACT

    Purpose: Extracts multiple sections of a table based on X values.


    Syntax:  XCOLEXTRACT(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 multi-column series.

    Example:
             W1: gnorm(1000, 1/1000)
             W2: integ(w1)
             W3: ravel(w1, w2)
             W4: xcolextract(w3, {0.2, 0.7}, {0.3, 0.8})
             W5: w1;overp(col(w4, 1))
             W6: w2;overp(col(w4, 2))

             W3 contains a two column series where the first column is
             identical to W1 and the second column is identical to W2.

             W4 extracts the segment from 0.2 to 0.3 of column 1 and the
             segment 0.7 to 0.8 from column 2.

             W5 displays the original data in W1 with the extracted segment
             from 0.2 to 0.3.

             W6 displays the original data in W2 with the extracted segment
             from 0.7 to 0.8.

    Example:
             W1: gnorm(1000, 1/1000)
             W2: xcolextract(w1, {0.2, 0.7}, {0.3, 0.8})
             W3: w1;overp(col(w2, 1));overp(col(w2, 2))
             W4: ravel(colmin(w2)', colmax(w2)')

             Similar to above but because the source series contains
             just one column, the series is used as the source for
             both extractions.

             W2 contains two columns where column 1 is the segment of
             W1 from 0.2 to 0.3 and column 2 is the segment of W1
             from 0.7 to 0.8.

             W3 displays the original data with the extracted
             segments as two overplots.

             W4 computes the minimum and maximum values of each
             segment and displays the result as a two column table
             where the first column contains the minimums of each
             segment and the second column contains the maximums.
      
    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 COLEXTRACT to perform the extraction with indices.

             See XSEREXTRACT to extract multiple segments from a
             series based on X values and place the result in a
             single column.

    See Also:
             Colextract
             Extract
             Serextract
             Xextract
             Xserextract
             Xtoidx

#endif


/* column extraction using X values */
xcolextract(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 colextract to extract segments */
        s = colextract(s, istart, ilen, xoffset);

        return(s);
}