PRO generate_subscripts_for_range_in_vector, xsize, xlo, xhi, subs, nsubs, status, NO_PAR_CHECK = no_par_check
; Description: This module generates a set of subscripts "subs" for the index range "xlo" to "xhi"
; in a vector of length "xsize" elements. If either (or both) of the indices "xlo"
; and "xhi" lie outside of the vector, then the index range is truncated to the overlap
; range with the vector length before generating the subscripts, which may of course be
; empty.
;
; N.B: The first element in the vector has an index of "0", and the last element in the
; vector has an index of "xsize-1".
;
; Input Parameters:
;
; xsize - INTEGER/LONG - The vector length. This parameter must be positive.
; xlo - INTEGER/LONG - The lower index in the index range.
; xhi - INTEGER/LONG - The upper index in the index range. This parameter must have a value that
; is greater than or equal to the value of the parameter "xlo".
;
; Output Parameters:
;
; subs - LONG VECTOR - A one-dimensional vector with "nsubs" elements representing the subscripts
; for the required index range in a vector of length "xsize" elements. All
; elements in this parameter are non-negative. If the overlap range between
; the index range and the vector length is empty, then this parameter is
; set to the single element vector "[-1]".
; nsubs - LONG - The number of subscripts in the vector of subscripts "subs". If the overlap range
; between the index range and the vector length is empty, then this parameter is
; set to "0".
; status - INTEGER - If the module successfully generated the set of subscripts "subs", then
; "status" is returned with a value of "1", otherwise it is returned with a
; value of "0".
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the module will not perform
; parameter checking on the input parameters, reducing module overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 04/01/2011 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "xsize" is a positive number of the correct type
;Check that "xlo" and "xhi" are of the correct number type and that they have sensible values
;Set "status" to "1"
;Determine the overlap range between the index range and the vector length
;If the overlap range between the index range and the vector length is empty, then return an empty
;set of subscripts
;Generate the subscripts for the index range